Figshare API v2 (Manara - HBKU Research)

openapi: 3.0.3
info:
  title: Figshare 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
paths:
  /altmetric/institutions:
    get:
      tags:
      - altmetric
      summary: List Altmetric Institutions
      description: Returns a list of institutions available for Altmetric reporting
      operationId: altmetric_institutions_list
      x-internal: true
      parameters:
      - name: offset
        in: query
        description: Where to start the listing. The offset of the first item.
        schema:
          minimum: 0
          type: integer
          default: 0
      responses:
        '200':
          description: OK. An array of Altmetric institutions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AltmetricInstitution'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal Server Error
          content: {}
  /articles:
    get:
      tags:
      - articles
      summary: Public Articles
      description: Returns a list of public articles
      operationId: articles_list
      parameters:
      - name: X-Cursor
        in: header
        description: Unique hash used for bypassing the item retrieval limit of 9,000 entities. When using this parameter,
          please note that the offset parameter will not be available, but the limit parameter will still work as expected.
        schema:
          type: string
      - name: page
        in: query
        description: Page number. Used for pagination with page_size
        schema:
          maximum: 5000
          minimum: 1
          type: integer
      - name: page_size
        in: query
        description: The number of results included on a page. Used for pagination with page
        schema:
          maximum: 1000
          minimum: 1
          type: integer
          default: 10
      - name: limit
        in: query
        description: Number of results included on a page. Used for pagination with query
        schema:
          maximum: 1000
          minimum: 1
          type: integer
      - name: offset
        in: query
        description: Where to start the listing (the offset of the first result). Used for pagination with limit
        schema:
          maximum: 5000
          minimum: 0
          type: integer
      - name: order
        in: query
        description: The field by which to order. Default varies by endpoint/resource.
        schema:
          type: string
          default: published_date
          enum:
          - published_date
          - created_date
          - modified_date
          - views
          - shares
          - downloads
          - cites
      - name: order_direction
        in: query
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: institution
        in: query
        description: only return articles from this institution
        schema:
          type: integer
      - name: published_since
        in: query
        description: Filter by article publishing date. Will only return articles published after the date. date(ISO 8601)
          YYYY-MM-DD or date-time(ISO 8601) YYYY-MM-DDTHH:mm:ssZ
        schema:
          type: string
      - name: modified_since
        in: query
        description: Filter by article modified date. Will only return articles modified after the date. date(ISO 8601) YYYY-MM-DD
          or date-time(ISO 8601) YYYY-MM-DDTHH:mm:ssZ
        schema:
          type: string
      - name: group
        in: query
        description: only return articles from this group
        schema:
          type: integer
      - name: resource_doi
        in: query
        description: Deprecated by related materials. Only return articles with this resource_doi
        schema:
          type: string
      - name: item_type
        in: query
        description: 'Only return articles with the respective type. Mapping for item_type is: 1 - Figure, 2 - Media, 3 -
          Dataset, 5 - Poster, 6 - Journal contribution, 7 - Presentation, 8 - Thesis, 9 - Software, 11 - Online resource,
          12 - Preprint, 13 - Book, 14 - Conference contribution, 15 - Chapter, 16 - Peer review, 17 - Educational resource,
          18 - Report, 19 - Standard, 20 - Composition, 21 - Funding, 22 - Physical object, 23 - Data management plan, 24
          - Workflow, 25 - Monograph, 26 - Performance, 27 - Event, 28 - Service, 29 - Model'
        schema:
          type: integer
      - name: doi
        in: query
        description: only return articles with this doi
        schema:
          type: string
      - name: handle
        in: query
        description: only return articles with this handle
        schema:
          type: string
      responses:
        '200':
          description: OK. An array of articles
          headers:
            X-Cursor:
              description: Unique hash used for bypassing the item retrieval limit of 9,000 entities.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Article'
        '400':
          description: Bad Request
          content: {}
        '422':
          description: Unprocessable Entity. Syntax is correct but one of the parameters isn't correctly processed
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
  /articles/search:
    post:
      tags:
      - articles
      summary: Public Articles Search
      description: Returns a list of public articles, filtered by the search parameters
      operationId: articles_search
      parameters:
      - name: X-Cursor
        in: header
        description: Unique hash used for bypassing the item retrieval limit of 9,000 entities. When using this parameter,
          please note that the offset parameter will not be available, but the limit parameter will still work as expected.
        schema:
          type: string
      requestBody:
        description: Search Parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleSearch'
        required: false
      responses:
        '200':
          description: OK. An array of articles
          headers:
            X-Cursor:
              description: Unique hash used for bypassing the item retrieval limit of 9,000 entities.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleWithProject'
        '400':
          description: Bad Request
          content: {}
        '422':
          description: Unprocessable Entity. Syntax is correct but one of the parameters isn't correctly processed
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
      x-codegen-request-body-name: search
  /articles/{article_id}:
    get:
      tags:
      - articles
      summary: View article details
      description: View an article
      operationId: article_details
      parameters:
      - name: article_id
        in: path
        description: Article Unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          description: OK. Article representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleComplete'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
      x-subcategory: Public Article
  /articles/{article_id}/versions:
    get:
      tags:
      - articles
      summary: List article versions
      description: List public article versions
      operationId: article_versions
      parameters:
      - name: article_id
        in: path
        description: Article Unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          description: OK. Article version representations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleVersions'
        '400':
          description: Bad Request. Article ID must be an integer and bigger than 0.
          content: {}
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
      x-subcategory: Public Article
  /articles/{article_id}/versions/{version_id}:
    get:
      tags:
      - articles
      summary: Article details for version
      description: Article with specified version
      operationId: article_version_details
      parameters:
      - name: article_id
        in: path
        description: Article Unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      - name: version_id
        in: path
        description: Article Version Number
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          description: OK. Article representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleComplete'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
      x-subcategory: Public Article
  /articles/{article_id}/versions/{version_id}/files:
    get:
      tags:
      - articles
      summary: Public Article version files
      description: Article version file details
      operationId: article_version_files
      parameters:
      - name: article_id
        in: path
        description: Article Unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      - name: version_id
        in: path
        description: Article Version Unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      - name: page
        in: query
        description: Page number. Used for pagination with page_size
        schema:
          maximum: 5000
          minimum: 1
          type: integer
      - name: page_size
        in: query
        description: The number of results included on a page. Used for pagination with page
        schema:
          maximum: 1000
          minimum: 1
          type: integer
          default: 10
      - name: limit
        in: query
        description: Number of results included on a page. Used for pagination with query
        schema:
          maximum: 1000
          minimum: 1
          type: integer
      - name: offset
        in: query
        description: Where to start the listing (the offset of the first result). Used for pagination with limit
        schema:
          maximum: 5000
          minimum: 0
          type: integer
      responses:
        '200':
          description: OK. List of article files
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicFile'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
      x-subcategory: Public Article files
  /articles/{article_id}/download:
    get:
      tags:
      - articles
      summary: Public Article Download
      description: Download files from a public article preserving the folder structure
      operationId: public_article_download
      parameters:
      - name: article_id
        in: path
        description: Article unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      - name: folder_path
        in: query
        description: Folder path to download. If not provided, all files from the article will be downloaded
        schema:
          type: string
      responses:
        '200':
          description: OK
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
      x-subcategory: Public Article
  /articles/{article_id}/versions/{version_id}/download:
    get:
      tags:
      - articles
      summary: Public Article Version Download
      description: Download files from a certain version of an public article preserving the folder structure
      operationId: public_article_version_download
      parameters:
      - name: article_id
        in: path
        description: Article unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      - name: version_id
        in: path
        description: Version Number
        required: true
        schema:
          minimum: 1
          type: integer
      - name: folder_path
        in: query
        description: Folder path to download. If not provided, all files from the article will be downloaded
        schema:
          type: string
      responses:
        '200':
          description: OK
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
      x-subcategory: Public Article
  /articles/{article_id}/versions/{version_id}/embargo:
    get:
      tags:
      - articles
      summary: Public Article Embargo for article version
      description: Embargo for article version
      operationId: article_version_embargo
      parameters:
      - name: article_id
        in: path
        description: Article Unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      - name: version_id
        in: path
        description: Version Number
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          description: OK. Embargo representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleEmbargo'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
  /articles/{article_id}/versions/{version_id}/confidentiality:
    get:
      tags:
      - articles
      summary: Public Article Confidentiality for article version
      description: Confidentiality for article version. The confidentiality feature is now deprecated. This has been replaced
        by the new extended embargo functionality and all items that used to be confidential have now been migrated to items
        with a permanent embargo on files. All API endpoints related to this functionality will remain for backwards compatibility,
        but will now be attached to the new extended embargo workflows.
      operationId: article_version_confidentiality
      parameters:
      - name: article_id
        in: path
        description: Article Unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      - name: version_id
        in: path
        description: Version Number
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          description: OK. Confidentiality representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleConfidentiality'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
  /articles/{article_id}/files:
    get:
      tags:
      - articles
      summary: List article files
      description: Files list for article
      operationId: article_files
      parameters:
      - name: article_id
        in: path
        description: Article Unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      - name: page
        in: query
        description: Page number. Used for pagination with page_size
        schema:
          maximum: 5000
          minimum: 1
          type: integer
      - name: page_size
        in: query
        description: The number of results included on a page. Used for pagination with page
        schema:
          maximum: 1000
          minimum: 1
          type: integer
          default: 10
      - name: limit
        in: query
        description: Number of results included on a page. Used for pagination with query
        schema:
          maximum: 1000
          minimum: 1
          type: integer
      - name: offset
        in: query
        description: Where to start the listing (the offset of the first result). Used for pagination with limit
        schema:
          maximum: 5000
          minimum: 0
          type: integer
      responses:
        '200':
          description: OK. List of article files
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicFile'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
      x-subcategory: Public Article files
  /articles/{article_id}/files/{file_id}:
    get:
      tags:
      - articles
      summary: Article file details
      description: File by id
      operationId: article_file_details
      parameters:
      - name: article_id
        in: path
        description: Article Unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      - name: file_id
        in: path
        description: File Unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          description: OK. File representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicFile'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
      x-subcategory: Public Article files
  /account/articles/search:
    post:
      tags:
      - articles
      summary: Private Articles search
      description: Returns a list of private articles filtered by the search parameters
      operationId: private_articles_search
      requestBody:
        description: Search Parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrivateArticleSearch'
        required: true
      responses:
        '200':
          description: OK. An array of articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleWithProject'
        '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/articles:
    get:
      tags:
      - articles
      summary: Private Articles
      description: Get Own Articles
      operationId: private_articles_list
      parameters:
      - name: page
        in: query
        description: Page number. Used for pagination with page_size
        schema:
          maximum: 5000
          minimum: 1
          type: integer
      - name: page_size
        in: query
        description: The number of results included on a page. Used for pagination with page
        schema:
          maximum: 1000
          minimum: 1
          type: integer
          default: 10
      - name: limit
        in: query
        description: Number of results included on a page. Used for pagination with query
        schema:
          maximum: 1000
          minimum: 1
          type: integer
      - name: offset
        in: query
        description: Where to start the listing (the offset of the first result). Used for pagination with limit
        schema:
          maximum: 5000
          minimum: 0
          type: integer
      responses:
        '200':
          description: OK. An array of articles belonging to the account
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Article'
        '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
    post:
      tags:
      - articles
      summary: Create new Article
      description: Create a new Article by sending article information
      operationId: private_article_create
      requestBody:
        description: Article description
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleCreate'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationWarnings'
        '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-subcategory: Private Article
      x-codegen-request-body-name: Article
  /account/articles/{article_id}:
    get:
      tags:
      - articles
      summary: Article details
      description: View a private article
      operationId: private_article_details
      parameters:
      - name: article_id
        in: path
        description: Article unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          description: OK. Article representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleCompletePrivate'
        '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
      x-subcategory: Private Article
    put:
      tags:
      - articles
      summary: Update article
      description: Update an article by passing full body parameters.
      operationId: private_article_update
      parameters:
      - name: article_id
        in: path
        description: Article unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      requestBody:
        description: Full article representation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleUpdate'
        required: true
      responses:
        '205':
          description: Reset Content
          headers:
            Location:
              description: Location of newly created article
              schema:
                type: string
                format: link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationWarningsUpdate'
        '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
      x-subcategory: Private Article
      x-codegen-request-body-name: Article
    delete:
      tags:
      - articles
      summary: Delete article
      description: Delete an article
      operationId: private_article_delete
      parameters:
      - name: article_id
        in: path
        description: Article unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '204':
          description: No Content
          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
      x-subcategory: Private Article
    patch:
      tags:
      - articles
      summary: Partially update article
      description: Partially update an article by sending only the fields to change.
      operationId: private_article_partial_update
      parameters:
      - name: article_id
        in: path
        description: Article unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      requestBody:
        description: Subset of article fields to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleUpdate'
        required: true
      responses:
        '205':
          description: Reset Content
          headers:
            Location:
              description: Location of the updated article
              schema:
                type: string
                format: link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationWarningsUpdate'
        '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
      x-subcategory: Private Article
      x-codegen-request-body-name: Article
  /account/articles/{article_id}/embargo:
    get:
      tags:
      - articles
      summary: Article Embargo Details
      description: View a private article embargo details
      operationId: private_article_embargo_details
      parameters:
      - name: article_id
        in: path
        description: Article unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          description: OK. Embargo for article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleEmbargo'
        '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
      x-subcategory: Private Article Embargo
    put:
      tags:
      - articles
      summary: Update Article Embargo
      description: 'Note: setting an article under whole embargo does not imply that the article will be published when the
        embargo will expire. You must explicitly call the publish endpoint to enable this functionality.'
      operationId: private_article_embargo_update
      parameters:
      - name: article_id
        in: path
        description: Article unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      requestBody:
        description: Embargo description
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleEmbargoUpdater'
        required: true
      responses:
        '205':
          description: Reset Content
          headers:
            Location:
              description: Location of embargo
              schema:
                type: string
                format: link
          content: {}
        '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
      x-subcategory: Private Article Embargo
      x-codegen-request-body-name: Embargo
    delete:
      tags:
      - articles
      summary: Delete Article Embargo
      description: Will lift the embargo for the specified article
      operationId: private_article_embargo_delete
      parameters:
      - name: article_id
        in: path
        description: Article unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '204':
          description: No Content
          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
      x-subcategory: Private Article Embargo
  /account/articles/{article_id}/resource:
    post:
      tags:
      - articles
      summary: Private Article Resource
      description: Edit article resource data.
      operationId: private_article_resource
      parameters:
      - name: article_id
        in: path
        description: Article unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      requestBody:
        description: Resource data
        content:
          application/json:
            schema:
              $ref: '#/comp

# --- truncated at 32 KB (329 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hbku/refs/heads/main/openapi/hbku-figshare-api.yaml