openapi: 3.0.3
info:
  title: DTU Data (Figshare API v2)
  description: Public read subset of the Figshare REST API v2 as consumed by DTU Data, DTU's institutional
    research data repository. DTU records are scoped via institution id 379. Public read access to published
    articles, files, and versions requires no authentication. Derived from the official Figshare OpenAPI
    3.0.3 specification (https://docs.figshare.com/swagger.json).
  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:
  /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/{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}/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
  /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
  /institutions/{institution_string_id}/articles/filter-by:
    get:
      tags:
      - institutions
      summary: Public Institution Articles
      description: Returns a list of articles belonging to the institution
      operationId: institution_articles
      parameters:
      - name: institution_string_id
        in: path
        required: true
        schema:
          type: string
      - name: resource_id
        in: query
        required: true
        schema:
          type: string
      - name: filename
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK. An array of articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Article'
        '500':
          description: Internal Server Error
          content: {}
components:
  schemas:
    ArticleVersions:
      required:
      - url
      - version
      type: object
      properties:
        version:
          type: integer
          description: Version number
          example: 1
        url:
          type: string
          description: Api endpoint for the item version
          format: url
          example: https://api.figshare.com/v2/articles/2000005/versions/1
      x-tag: articles
    ArticleComplete:
      required:
      - authors
      - custom_fields
      - download_disabled
      - embargo_options
      - figshare_url
      - files
      - folder_structure
      properties:
        figshare_url:
          type: string
          description: Article public url
          format: url
          example: http://figshare.com/articles/media/article_name/2000005
        download_disabled:
          type: boolean
          description: If true, downloading of files for this article is disabled
          example: false
        files:
          type: array
          description: List of up to 10 article files.
          items:
            $ref: '#/components/schemas/PublicFile'
        folder_structure:
          type: object
          properties: {}
          description: Mapping of file ids to folder paths, if folders are used
          example:
            '3000002': Test Folder
        authors:
          type: array
          description: List of article authors
          items:
            $ref: '#/components/schemas/Author'
        custom_fields:
          type: array
          description: List of custom fields values
          items:
            $ref: '#/components/schemas/CustomArticleField'
        embargo_options:
          type: array
          description: List of embargo options
          items:
            $ref: '#/components/schemas/GroupEmbargoOptions'
      allOf:
      - $ref: '#/components/schemas/ProjectArticle'
      x-tag: articles
    Timeline:
      allOf:
      - $ref: '#/components/schemas/TimelineUpdate'
      x-tag: timeline
    TimelineUpdate:
      type: object
      properties:
        firstOnline:
          type: string
          description: Online posted date
          example: '2015-12-31'
        publisherPublication:
          type: string
          description: Publish date
          example: '2015-12-31'
        publisherAcceptance:
          type: string
          description: Date when the item was accepted for publication
          example: '2015-12-31'
      x-tag: timeline_update
    Article:
      required:
      - created_date
      - defined_type
      - defined_type_name
      - doi
      - handle
      - id
      - resource_doi
      - resource_title
      - thumb
      - timeline
      - title
      - url
      - url_private_api
      - url_private_html
      - url_public_api
      - url_public_html
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for article
          example: 1434614
        title:
          type: string
          description: Title of article
          example: Test article title
        doi:
          type: string
          description: DOI
          example: 10.6084/m9.figshare.1434614
        handle:
          type: string
          description: Handle
          example: 111184/figshare.1234
        url:
          type: string
          description: Api endpoint for article
          format: url
          example: http://api.figshare.com/articles/1434614
        url_public_html:
          type: string
          description: Public site endpoint for article
          format: url
          example: https://figshare.com/articles/media/Test_article_title/1434614
        url_public_api:
          type: string
          description: Public Api endpoint for article
          format: url
          example: https://api.figshare.com/articles/1434614
        url_private_html:
          type: string
          description: Private site endpoint for article
          format: url
          example: https://figshare.com/account/articles/1434614
        url_private_api:
          type: string
          description: Private Api endpoint for article
          format: url
          example: https://api.figshare.com/account/articles/1434614
        timeline:
          $ref: '#/components/schemas/Timeline'
        thumb:
          type: string
          description: Thumbnail image
          format: url
          example: https://ndownloader.figshare.com/files/123456789/preview/12345678/thumb.png
        defined_type:
          type: integer
          description: Type of article identifier
          example: 3
        defined_type_name:
          type: string
          description: Name of the article type identifier
          example: media
        resource_doi:
          type: string
          description: Deprecated by related materials. Not applicable to regular users. In a publisher
            case, this is the publisher article DOI.
          default: ''
        resource_title:
          type: string
          description: Deprecated by related materials. Not applicable to regular users. In a publisher
            case, this is the publisher article title.
          default: ''
        created_date:
          type: string
          description: Date when article was created
          example: '2017-05-18T11:49:03Z'
      x-tag: articles
    GroupEmbargoOptions:
      required:
      - id
      - ip_name
      - type
      type: object
      properties:
        id:
          type: integer
          description: Embargo option id
          example: 364
        type:
          type: string
          description: Embargo permission type
          example: ip_range
          enum:
          - logged_in
          - ip_range
          - administrator
        ip_name:
          type: string
          description: IP range name; value appears if type is ip_range
          example: Figshare IP range
      x-tag: institutions
    ProjectArticle:
      required:
      - categories
      - citation
      - confidential_reason
      - created_date
      - description
      - embargo_reason
      - embargo_title
      - funding
      - funding_list
      - has_linked_file
      - is_confidential
      - is_embargoed
      - is_metadata_record
      - is_public
      - keywords
      - license
      - metadata_reason
      - references
      - size
      - status
      - tags
      - version
      properties:
        citation:
          type: string
          description: Article citation
          example: "lilliput, figshare admin (2017): first project item. figshare.\n \n Retrieved: 14\
            \ 01, May 22, 2017 (GMT)"
        confidential_reason:
          type: string
          description: Confidentiality reason
          example: none
        is_confidential:
          type: boolean
          description: Article Confidentiality
          example: true
        size:
          type: integer
          description: Article size
          example: 69939
        funding:
          type: string
          description: Article funding
          example: none
        funding_list:
          type: array
          description: Full Article funding information
          items:
            $ref: '#/components/schemas/FundingInformation'
        tags:
          type: array
          description: List of article tags. Keywords can be used instead
          example:
          - t1
          - t2
          - t3
          items:
            type: string
        keywords:
          type: array
          description: List of article keywords. Tags can be used instead
          example:
          - t1
          - t2
          - t3
          items:
            type: string
        version:
          type: integer
          description: Article version
          example: 1
        is_metadata_record:
          type: boolean
          description: True if article has no files
          example: false
        metadata_reason:
          type: string
          description: Article metadata reason
          example: hosted somewhere else
        status:
          type: string
          description: Article status
          example: public
        description:
          type: string
          description: Article description
          example: article description
        is_embargoed:
          type: boolean
          description: True if article is embargoed
          example: true
        is_public:
          type: boolean
          description: True if article is published
          example: true
        created_date:
          type: string
          description: Date when article was created
          example: '2017-05-18T11:49:03Z'
        has_linked_file:
          type: boolean
          description: True if any files are linked to the article
          example: true
        categories:
          type: array
          description: List of categories selected for the article
          items:
            $ref: '#/components/schemas/Category'
        license:
          $ref: '#/components/schemas/License'
        embargo_title:
          type: string
          description: Title for embargo
          example: File(s) under embargo
        embargo_reason:
          type: string
          description: Reason for embargo
          example: not complete
        references:
          type: array
          description: List of references
          example:
          - http://figshare.com
          - http://figshare.com/api
          items:
            type: string
            format: url
        related_materials:
          type: array
          description: List of related materials; supersedes references and resource DOI/title.
          example:
          - id: 10432
            identifier: 10.6084/m9.figshare.1407024
            identifier_type: DOI
            relation: IsSupplementTo
            title: Figshare for institutions brochure
            is_linkout: false
          items:
            $ref: '#/components/schemas/RelatedMaterial'
      allOf:
      - $ref: '#/components/schemas/Article'
      x-tag: articles
    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
    Author:
      required:
      - first_name
      - full_name
      - id
      - is_active
      - last_name
      - orcid_id
      - url_name
      type: object
      properties:
        id:
          type: integer
          description: Author id
          example: 97657
        full_name:
          type: string
          description: Author full name
          example: John Doe
        first_name:
          type: string
          description: Author first name
          example: John
        last_name:
          type: string
          description: Author last name
          example: Doe
        is_active:
          type: boolean
          description: True if author has published items
          example: false
        url_name:
          type: string
          description: Author url name
          example: John_Doe
        orcid_id:
          type: string
          description: Author Orcid
          example: 1234-5678-9123-1234
      x-tag: authors
    RelatedMaterial:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the related material; can be used to add existing materials of the same
            account to items.
          example: 10432
        identifier:
          type: string
          description: The related material identifier (e.g., DOI, Handle, ISBN). Mandatory if creating
            a new material.
          example: 10.6084/m9.figshare.1407024
        title:
          type: string
          description: The related material title
          example: 'Rooter: A Methodology for the Typical Unification of Access Points and Redundancy'
        relation:
          type: string
          description: The relation between the item and the related material; defaults to 'References'.
            Mandatory if creating a new material.
          example: IsSupplementTo
          default: References
          enum:
          - IsCitedBy
          - Cites
          - IsSupplementTo
          - IsSupplementedBy
          - IsContinuedBy
          - Continues
          - Describes
          - IsDescribedBy
          - HasMetadata
          - IsMetadataFor
          - HasVersion
          - IsVersionOf
          - IsNewVersionOf
          - IsPreviousVersionOf
          - IsPartOf
          - HasPart
          - IsPublishedIn
          - IsReferencedBy
          - References
          - IsDocumentedBy
          - Documents
          - IsCompiledBy
          - Compiles
          - IsVariantFormOf
          - IsOriginalFormOf
          - IsIdenticalTo
          - IsReviewedBy
          - Reviews
          - IsDerivedFrom
          - IsSourceOf
          - IsRequiredBy
          - Requires
          - IsObsoletedBy
          - Obsoletes
        identifier_type:
          type: string
          description: The type of the identifier of the related material; defaults to 'URL'. Mandatory
            if creating a new material.
          example: DOI
          default: URL
          enum:
          - ARK
          - arXiv
          - bibcode
          - DOI
          - EAN13
          - EISSN
          - Handle
          - IGSN
          - ISBN
          - ISSN
          - ISTC
          - LISSN
          - LSID
          - PMID
          - PURL
          - UPC
          - URL
          - URN
          - w3id
        is_linkout:
          type: boolean
          description: Flag for highlighting this related material in the call-out box
          example: true
        link:
          type: string
          description: The full hyperlink for the identifier. Automatically generated by Figshare.
          readOnly: true
          example: https://doi.org/10.6084/m9.figshare.1407024
    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
    CustomArticleField:
      required:
      - field_type
      - is_mandatory
      - name
      - order
      - settings
      - value
      type: object
      properties:
        name:
          type: string
          description: Custom  metadata name
          example: key
        value:
          type: object
          description: Custom metadata value (can be either a string or an array of strings)
          example: value
        field_type:
          type: string
          description: Custom field type
          example: textarea
          enum:
          - text
          - textarea
          - dropdown
          - url
          - email
          - date
          - dropdown_large_list
        settings:
          type: object
          properties: {}
          description: Settings for the custom field
          example:
            validations:
              min_length: 1
              max_length: 1000
            placeholder: Enter your custom field here
        order:
          type: integer
          description: Order of the custom field
          example: 1
        is_mandatory:
          type: boolean
          description: Whether the field is mandatory or not
          example: false
      x-tag: articles
    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
    PublicFile:
      required:
      - computed_md5
      - download_url
      - id
      - is_link_only
      - name
      - size
      - supplied_md5
      type: object
      properties:
        id:
          type: integer
          description: File id
          example: 3000002
        name:
          type: string
          description: File name
          example: test.xls
        size:
          type: integer
          description: File size
          example: 14848
        is_link_only:
          type: boolean
          description: True if file is hosted somewhere else
          example: false
        download_url:
          type: string
          description: Url for file download
          format: url
          example: https://ndownloader.figshare.com/files/3000002
        supplied_md5:
          type: string
          description: File supplied md5
          example: 043a51806d646e88cafbf19e7b82846f
        computed_md5:
          type: string
          description: File computed md5
          example: 043a51806d646e88cafbf19e7b82846f
        mimetype:
          type: string
          description: MIME Type of the file, it defaults to an empty string
          example: application/pdf
      x-tag: common