openapi: 3.0.3
info:
  title: Figshare API (Macquarie University Research Data Repository) altmetric symplectic API
  description: 'Macquarie University Research Data Repository (RDR) is built on Figshare for Institutions and surfaces its public datasets, theses and research outputs through the public Figshare REST API v2. Macquarie content is discoverable via this API (DOI prefix 10.25949, Figshare group id 39392) and the public figshare.mq.edu.au discovery portal. This is the faithful upstream Figshare API v2 OpenAPI 3.0.3 description (saved unmodified except for this contextual note).


    Figshare API v2 - Full REST API documentation for managing articles, collections, projects and more.'
  version: '2.0'
  contact:
    name: Figshare Support
    url: https://support.figshare.com/support/home
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.figshare.com/v2
tags:
- name: symplectic
paths:
  /symplectic/articles:
    get:
      tags:
      - symplectic
      summary: Get changed articles for Symplectic Elements
      description: Returns a list of articles for Symplectic Elements integration to synchronize article data.
      operationId: symplectic_changed_articles
      parameters:
      - name: since
        in: query
        description: 'ISO 8601 datetime string indicating the start of the search window (format: YYYY-MM-DD HH:MM:SS)'
        required: true
        schema:
          type: string
        example: '2015-01-01 00:00:00'
      - name: offset
        in: query
        description: Number of results to skip for pagination
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: limit
        in: query
        description: Maximum number of results to return
        required: false
        schema:
          type: integer
          minimum: 1
          default: 10
      - name: status
        in: query
        description: Filter by article status
        required: false
        schema:
          type: string
          enum:
          - public
          - private
          - draft
      - name: is_embargoed
        in: query
        description: Filter by embargo status. When true, only returns articles with EMBARGO_ARTICLE type
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: OK. Returns a list of symplectic articles
          headers:
            ETag:
              description: Hash of the returned articles for caching purposes
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '400':
          description: Bad Request - Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized - Missing or invalid OAuth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
      - OAuth2: []
  /symplectic/users/{user_id}:
    get:
      tags:
      - symplectic
      summary: Get institutional user ID for a user
      description: Returns the institution user ID for a given user within the authenticated account's institution.
      operationId: symplectic_user_id
      parameters:
      - name: user_id
        in: path
        description: User ID
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK. Returns the institutional user ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  institutionUserId:
                    type: string
        '401':
          description: Unauthorized - Missing or invalid OAuth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found - User not found or user has no account in this institution
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
      - OAuth2: []
  /symplectic/articles/{article_id}:
    get:
      tags:
      - symplectic
      summary: Get article details for Symplectic Elements
      description: Returns detailed information about a specific article for Symplectic Elements integration, including full metadata and author account information.
      operationId: symplectic_article
      parameters:
      - name: article_id
        in: path
        description: Article ID
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK. Returns the article details with full metadata
          headers:
            ETag:
              description: Hash of the returned article for caching purposes
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - Missing or invalid OAuth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found - Article not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
      - OAuth2: []
  /symplectic/accounts/{external_user_id}/articles:
    get:
      tags:
      - symplectic
      summary: Get articles for a specific account
      description: Returns a list of articles for a specific user account identified by external_user_id (symplectic_user_id or institution_user_id).
      operationId: symplectic_account_articles
      parameters:
      - name: external_user_id
        in: path
        description: External user ID (symplectic_user_id or institution_user_id)
        required: true
        schema:
          type: string
      - name: offset
        in: query
        description: Number of results to skip for pagination
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: limit
        in: query
        description: Maximum number of results to return
        required: false
        schema:
          type: integer
          minimum: 1
          default: 10
      - name: status
        in: query
        description: Filter by article status
        required: false
        schema:
          type: string
          enum:
          - public
          - private
          - draft
      - name: is_embargoed
        in: query
        description: Filter by embargo status
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: OK. Returns a list of articles for the specified account
          headers:
            ETag:
              description: Hash of the returned articles for caching purposes
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          description: Unauthorized - Missing or invalid OAuth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found - Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
      - OAuth2: []
  /symplectic/accounts:
    get:
      tags:
      - symplectic
      summary: Get changed accounts for Symplectic Elements
      description: Returns a list of accounts that have been modified since the specified date for Symplectic Elements integration.
      operationId: symplectic_accounts_ids
      parameters:
      - name: since
        in: query
        description: 'ISO 8601 datetime string indicating the start of the search window (format: YYYY-MM-DD HH:MM:SS)'
        required: true
        schema:
          type: string
        example: '2015-01-01 00:00:00'
      responses:
        '200':
          description: OK. Returns a list of modified accounts
          headers:
            ETag:
              description: Hash of the returned accounts for caching purposes
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    institutionUserId:
                      type: string
                    modifiedDate:
                      type: string
                      format: date-time
        '400':
          description: Bad Request - Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized - Missing or invalid OAuth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
      - OAuth2: []
components:
  schemas:
    ErrorMessage:
      type: object
      properties:
        code:
          type: integer
          description: A machine friendly error code, used by the dev team to identify the error.
        message:
          type: string
          description: A human friendly message explaining the error.
      x-tag: common
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://figshare.com/account/applications/authorize
          tokenUrl: https://api.figshare.com/v2/token
          scopes:
            all: Grants all access
x-additional-descriptions:
- title: Upload files
  position: bottom
  subsections:
  - title: Steps to upload file
    content: description_upload_steps
  - title: Uploads API
    content: description_upload_api
  - title: Parts API
    content: description_upload_parts_api
  - title: Example Upload on figshare
    content: description_upload_example
  - title: Output of Script
    content: description_upload_output
  - title: Upload Bash Script
    content: description_upload_bash
  - title: Upload S3 File to Figshare
    content: description_upload_from_s3
- title: Search
  position: bottom
  subsections:
  - title: How to find data on figshare
    content: description_search_intro
  - title: Search operators
    content: description_search_operators
  - title: Searchable attributes
    content: description_search_attributes
  - title: Quick search
    content: description_search_quick
  - title: Advanced search
    content: description_search_advanced
  - title: Combined field search
    content: description_search_combined
  - title: Complex searches
    content: description_search_complex
- title: Stats
  position: bottom
  subsections:
  - title: Stats service
    subsections:
    - title: Intro
      content: description_stats_service_intro
    - title: Authentication
      content: description_stats_service_auth
    - title: Errors
      content: description_stats_service_errors
    - title: Endpoints
      content: description_stats_service_endpoints
  - title: Breakdown
    subsections:
    - title: Endpoints for retrieving a breakdown
      content: description_stats_breakdown_endpoints
    - title: Authorization
      content: description_stats_breakdown_auth
    - title: Endpoint format
      content: description_stats_breakdown_format
    - title: Request parameters
      content: description_stats_breakdown_params
    - title: Examples
      content: description_stats_breakdown_examples
  - title: Timeline
    subsections:
    - title: Endpoints for retrieving a timeline
      content: description_stats_timeline_endpoints
    - title: Authorization
      content: description_stats_timeline_auth
    - title: Endpoint format
      content: description_stats_timeline_format
    - title: Request parameters
      content: description_stats_timeline_params
    - title: Examples
      content: description_stats_timeline_examples
  - title: Tops
    subsections:
    - title: Endpoints for retrieving tops
      content: description_stats_tops_endpoints
    - title: Authorization
      content: description_stats_tops_auth
    - title: Endpoint format
      content: description_stats_tops_format
    - title: Request parameters
      content: description_stats_tops_params
    - title: Examples
      content: description_stats_tops_examples
  - title: Totals
    subsections:
    - title: Endpoints for retrieving totals
      content: description_stats_totals_endpoints
    - title: Authorization
      content: description_stats_totals_auth
    - title: Endpoint format
      content: description_stats_totals_format
    - title: Examples
      content: description_stats_totals_examples
  - title: Count Articles
    subsections:
    - title: Endpoint for retrieving counts
      content: description_stats_count_endpoints
    - title: Authorization
      content: description_stats_count_auth
    - title: Endpoint format
      content: description_stats_count_format
    - title: Example
      content: description_stats_count_examples
- title: OAI PMH
  position: bottom
  subsections:
  - title: OAI-PMH
    content: description_oai_pmh
  - title: Base URL
    content: description_oai_baseurl
  - title: Item equals Article
    content: description_oai_itemarticle
  - title: Metadata formats
    content: description_oai_metadata
  - title: Datestamps
    content: description_oai_datestamp
  - title: Sets
    content: description_oai_sets
  - title: Update schedule
    content: description_oai_update_schedule
  - title: Pagination and Resumption Token Expiration
    content: description_oai_pagination
  - title: Rate limit
    content: description_oai_ratelimit
  - title: Future development
    content: description_oai_futuredev
  - title: Some examples
    content: description_oai_someexamples
- title: HR Feed
  position: bottom
  subsections:
  - title: HR Feed Private Endpoint
    content: description_hrfeed_endpoint
  - title: HR Feed examples
    subsections:
    - title: Python
      content: description_hrfeed_examples_python
    - title: Java
      content: description_hrfeed_examples_java
    - title: C Sharp
      content: description_hrfeed_examples_csharp
    - title: Curl
      content: description_hrfeed_examples_curl
  - title: Response
    content: description_hrfeed_response
  - title: Errors
    content: description_hrfeed_errors
  - title: Notes
    content: description_hrfeed_notes
- title: Custom Fields
  position: bottom
  subsections:
  - title: Custom Fields Private Endpoints
    content: description_custom_fields_endpoint
  - title: Custom Fields examples
    subsections:
    - title: Python
      content: description_custom_fields_examples_python
    - title: Java
      content: description_custom_fields_examples_java
    - title: C Sharp
      content: description_custom_fields_examples_csharp
    - title: Curl
      content: description_custom_fields_examples_curl
  - title: Response
    content: description_custom_fields_response
  - title: Errors
    content: description_custom_fields_errors
  - title: Notes
    content: description_custom_fields_notes
- title: figshare Documentation
  position: top
  subsections:
  - title: figshare Documentation
    content: description_intro
  - title: OAuth
    subsections:
    - title: Intro
      content: description_oauth_intro
    - title: Quick guide
      content: description_oauth_quick
    - title: Scope
      content: description_oauth_scope
    - title: Grant Types
      content: description_oauth_grant
  - title: API description
    subsections:
    - title: Feature list
      content: description_api_features
    - title: Sending parameters
      content: description_api_parameters
    - title: Resource representations
      content: description_api_resourcerepresentation
    - title: Authentication
      content: description_api_auth
    - title: Errors
      content: description_api_errors
    - title: Searching filtering and pagination
      content: description_api_search
    - title: Rate limiting
      content: description_api_ratelimit
    - title: Conditional requests
      content: description_api_requests
    - title: CORS policy
      content: description_api_cors
    - title: Impersonation
      content: description_api_impersonation
x-original-swagger-version: '2.0'