openapi: 3.0.3
info:
  title: Figshare altmetric other 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 (powers HKU DataHub)
tags:
- name: other
paths:
  /item_types:
    get:
      tags:
      - other
      summary: Item Types
      description: Returns the list of Item Types of the requested group. If no user is authenticated, returns the item types available for Figshare.
      operationId: item_types_list
      parameters:
      - name: group_id
        in: query
        description: Identifier of the group for which the item types are requested
        schema:
          minimum: 0
          type: integer
          default: 0
      responses:
        '200':
          description: OK. An array of item types
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ItemType'
        '400':
          description: Bad Request
          content: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security:
      - OAuth2:
        - all
  /account/funding/search:
    post:
      tags:
      - other
      summary: Search Funding
      description: Search for fundings
      operationId: private_funding_search
      requestBody:
        description: Search Parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FundingSearch'
        required: false
      responses:
        '200':
          description: OK. An array of funding information
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FundingInformation'
        '400':
          description: Bad Request
          content: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal Server Error
          content: {}
      security:
      - OAuth2:
        - all
      x-codegen-request-body-name: search
  /account:
    get:
      tags:
      - other
      summary: Private Account information
      description: Account information for token/personal token
      operationId: private_account
      responses:
        '200':
          description: OK. Account representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal Server Error
          content: {}
      security:
      - OAuth2:
        - all
  /categories:
    get:
      tags:
      - other
      summary: Public Categories
      description: Returns a list of public categories
      operationId: categories_list
      responses:
        '200':
          description: OK. An array of categories
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryList'
        '500':
          description: Internal Server Error
          content: {}
      security: []
  /licenses:
    get:
      tags:
      - other
      summary: Public Licenses
      description: Returns a list of public licenses
      operationId: licenses_list
      responses:
        '200':
          description: OK. An array of licenses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/License'
        '500':
          description: Internal Server Error
          content: {}
      security: []
  /account/licenses:
    get:
      tags:
      - other
      summary: Private Account Licenses
      description: This is a private endpoint that requires OAuth. It will return a list with figshare public licenses AND licenses defined for account's institution.
      operationId: private_licenses_list
      responses:
        '200':
          description: OK. An array of personal licenses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/License'
        '400':
          description: Bad Request
          content: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal Server Error
          content: {}
      security:
      - OAuth2:
        - all
  /file/download/{file_id}:
    get:
      tags:
      - other
      summary: Public File Download
      description: Starts the download of a file
      operationId: file_download
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          description: OK
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
components:
  schemas:
    FundingSearch:
      type: object
      properties:
        search_for:
          type: string
          description: Search term
      x-tag: funding
    Category:
      required:
      - id
      - parent_id
      - path
      - source_id
      - taxonomy_id
      - title
      type: object
      properties:
        parent_id:
          type: integer
          description: Parent category
          example: 1
        id:
          type: integer
          description: Category id
          example: 11
        title:
          type: string
          description: Category title
          example: Anatomy
        path:
          type: string
          description: Path to all ancestor ids
          example: /450/1024/6532
        source_id:
          type: string
          description: ID in original standard taxonomy
          example: '300204'
        taxonomy_id:
          type: integer
          description: Internal id of taxonomy the category is part of
          example: 4
      x-tag: common
    CategoryList:
      required:
      - has_children
      - is_selectable
      properties:
        is_selectable:
          type: boolean
          description: The selectable status
          example: true
        has_children:
          type: boolean
          description: True if category has children
          example: false
      allOf:
      - $ref: '#/components/schemas/Category'
      x-tag: common
    License:
      required:
      - name
      - url
      - value
      type: object
      properties:
        value:
          type: integer
          description: License value
          example: 1
        name:
          type: string
          description: License name
          example: CC BY
        url:
          type: string
          description: License url
          format: url
          example: http://creativecommons.org/licenses/by/4.0/
      x-tag: institutions
    ItemType:
      required:
      - icon
      - id
      - is_selectable
      - name
      - public_description
      - string_id
      - url_name
      type: object
      properties:
        id:
          minimum: 1
          type: integer
          description: The ID of the item type.
        name:
          type: string
          description: The name of the item type
          example: journal contribution
        string_id:
          type: string
          description: The string identifier of the item type.
          example: journal_contribution
        icon:
          type: string
          description: The string identifying the icon of the item type.
          example: paper
        public_description:
          type: string
          description: The description of the item type.
          example: This is the description of an item type
        is_selectable:
          type: boolean
          description: The selectable status
          example: true
        url_name:
          type: string
          description: The URL name of the item type.
          example: journal_contribution
    FundingInformation:
      required:
      - funder_name
      - grant_code
      - id
      - is_user_defined
      - title
      - url
      type: object
      properties:
        id:
          type: integer
          description: Funding id
          example: 1
        title:
          type: string
          description: The funding name
          example: Scholarly funding
        grant_code:
          type: string
          description: The grant code
        funder_name:
          type: string
          description: Funder's name
        is_user_defined:
          type: integer
          description: Return 1 whether the grant has been introduced manually, 0 otherwise
        url:
          type: string
          description: The grant url
          format: url
          example: https://app.dimensions.ai/details/grant/1
      x-tag: funding
    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
    Account:
      required:
      - active
      - created_date
      - email
      - first_name
      - group_id
      - id
      - institution_id
      - institution_user_id
      - last_name
      - maximum_file_size
      - modified_date
      - orcid_id
      - pending_quota_request
      - quota
      - symplectic_user_id
      - used_quota
      - used_quota_private
      - used_quota_public
      - user_id
      type: object
      properties:
        id:
          type: integer
          description: Account id
          example: 1495682
        first_name:
          type: string
          description: First Name
          example: Doe
        last_name:
          type: string
          description: Last Name
          example: John
        used_quota_private:
          type: integer
          description: Account used private quota
          example: 0
        modified_date:
          type: string
          description: Date of last account modification
          example: '2018-05-22T04:04:04'
        used_quota:
          type: integer
          description: Account total used quota
          example: 0
        created_date:
          type: string
          description: Date when account was created
          example: '2018-05-22T04:04:04'
        quota:
          type: integer
          description: Account quota
          example: 0
        group_id:
          type: integer
          description: Account group id
          example: 0
        institution_user_id:
          type: string
          description: Account institution user id
          example: djohn42
        institution_id:
          type: integer
          description: Account institution
          example: 1
        email:
          type: string
          description: User email
          example: user@domain.com
        used_quota_public:
          type: integer
          description: Account public used quota
          example: 0
        pending_quota_request:
          type: boolean
          description: True if a quota request is pending
          example: true
        active:
          type: integer
          description: Account activity status
          example: 0
        maximum_file_size:
          type: integer
          description: Maximum upload size for account
          example: 0
        user_id:
          type: integer
          description: User id associated with account, useful for example for adding the account as an author to an item
          example: 1000001
        orcid_id:
          type: string
          description: ORCID iD associated to account
          example: 0000-0001-2345-6789
        symplectic_user_id:
          type: string
          description: Symplectic ID associated to account
          example: djohn42
      x-tag: other
  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'