openapi: 3.0.3
info:
  title: Figshare altmetric symplectic API
  description: 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
  description: Figshare API v2 (University of Auckland records via institution=12)
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'