openapi: 3.1.0
info:
  title: Dryad datasets versions API
  description: "Dryad's REST API allows detailed interaction and programmatic interfacing with Dryad contents. The most common case is to use GET requests to retrieve information about datasets, versions, and files.\n\nWhen using the API, any DOI included must be <a href=\"https://www.w3schools.com/tags/ref_urlencode.ASP\" target=\"blank\">URL-encoded<i class=\"fas fa-arrow-up-right-from-square exit-icon\" aria-label=\" (opens in new window)\" role=\"img\"></i></a> to ensure correct processing. Anonymous users of the API are limited to 30 requests per minute, and are not allowed to download data files. \n\nExamples:\n\n- [List datasets](https://datadryad.org/api/v2/datasets)\n- [Search for datasets](https://datadryad.org/api/v2/search?q=carbon)\n- [Get information about a dataset](https://datadryad.org/api/v2/datasets/doi%3A10.5061%2Fdryad.j1fd7)\n- [List versions of a dataset](https://datadryad.org/api/v2/datasets/doi%3A10.5061%2Fdryad.j1fd7/versions)\n- [List files in a version](https://datadryad.org/api/v2/versions/26724/files)\n\nDetailed documentation:\n\n- For details on all of our REST API operations, click the links in the menu on this page.\n- [Search API](https://github.com/datadryad/dryad-app/blob/main/documentation/apis/search.md)\n- [Submission API](https://github.com/datadryad/dryad-app/blob/main/documentation/apis/submission.md)\n\n## API accounts \n\nTo access more powerful features, an API account is required. API accounts allow users to:\n\n- Access the API at higher rates (authenticated users may make up to 240 requests per minute)\n- Download data files\n- Access datasets that are not yet public, but are associated with the account's community (institution, journal, etc.)\n- Update datasets associated with the account's community\n\nSee the <a href=\"https://github.com/datadryad/dryad-app/blob/main/documentation/apis/api_accounts.md\" target=\"blank\">API accounts document<i class=\"fas fa-arrow-up-right-from-square exit-icon\" aria-label=\" (opens in new window)\" role=\"img\"></i></a> for more information on requesting an API account and using it to access datasets.\n\n\n## Submission\n\nThe Submission API is used by organizations that partner closely with Dryad, and use systems to create dataset submissions directly. Please contact us if you are [interested in partnering with Dryad](/contact#get-involved), and setting up an API account for submission.\n\nThe <a href=\"https://github.com/datadryad/dryad-app/blob/main/documentation/apis/submission.md\" target=\"blank\">API submission examples document<i class=\"fas fa-arrow-up-right-from-square exit-icon\" aria-label=\" (opens in new window)\" role=\"img\"></i></a> gives concrete examples of submission through the Dryad API.\n\n\n### Dryad sandbox\n\n<a href=\"https://sandbox.datadryad.org/\" target=\"blank\">Dryad's sandbox server<i class=\"fas fa-arrow-up-right-from-square exit-icon\" aria-label=\" (opens in new window)\" role=\"img\"></i></a> allows users to experiment with data submission and the Dryad API, without worrying about the effects on \"real\" data. Anyone may create an account on the sandbox server for testing purposes. When creating an account, keep in mind that Dryad's sandbox relies on the <a href=\"https://sandbox.orcid.org/\" target=\"_blank\">sandbox version of ORCID<i class=\"fas fa-arrow-up-right-from-square exit-icon\" aria-label=\" (opens in new window)\" role=\"img\"></i></a>, which allows you to make test ORCID accounts. Sandbox ORCID IDs should be used in the Dryad sandbox, while use of Dryad's production system requires a real ORCID ID.\n"
  version: 2.1.0
servers:
- url: https://datadryad.org/api/v2
  description: Main Dryad server
- url: https://sandbox.datadryad.org/api/v2
  description: Sandbox server, for testing new features.
tags:
- name: versions
  description: Operations on individual versions of a dataset
paths:
  /versions/{id}:
    get:
      summary: Show a specific dataset version
      tags:
      - versions
      description: If you know the dataset version's internal id, you can request its record directly. The <code>/versions</code> endpoint lists the versions of a dataset and their ids.
      parameters:
      - $ref: '#/components/parameters/version_id'
      responses:
        '200':
          description: The requested version of the dataset.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/version'
                - properties:
                    changedFields:
                      type: array
                      items:
                        type: string
              examples:
                success:
                  $ref: api/v2/docs/examples/version.json
        '406':
          $ref: '#/components/responses/Unacceptable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /versions/{id}/files:
    get:
      summary: List the files and file metadata in this version
      tags:
      - versions
      description: Returns the list of files and file metadata for a known version of a dataset with the version ID you specify.
      parameters:
      - $ref: '#/components/parameters/version_id'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: A list of the files in the version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/files'
              examples:
                success:
                  $ref: api/v2/docs/examples/files.json
        '406':
          $ref: '#/components/responses/Unacceptable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /versions/{id}/download:
    get:
      summary: Get a download package for a dataset version
      tags:
      - versions
      description: This downloads the zip package of a specified, submitted version of the dataset that is visible to the user (or public).
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/version_id'
      responses:
        '200':
          description: The binary content for a compressed archive.
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: not found
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    file_links:
      properties:
        _links:
          allOf:
          - $ref: '#/components/schemas/hal_self_link'
          - $ref: '#/components/schemas/hal_file_links'
    embedded_files:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            stash:files:
              type: array
              items:
                $ref: '#/components/schemas/file'
    geolocationBox:
      properties:
        swLongitude:
          description: The longitude of the southwest corner of the box.
          type: number
        swLatitude:
          description: The latitude of the southwest corner of the box.
          type: number
        neLongitude:
          description: The longitude of the northeast corner of the box.
          type: number
        neLatitude:
          description: The latitude of the northeast corner of the box.
          type: number
    hal_page_links:
      properties:
        first:
          $ref: '#/components/schemas/hal_link'
        last:
          $ref: '#/components/schemas/hal_link'
        prev:
          $ref: '#/components/schemas/hal_link'
        next:
          $ref: '#/components/schemas/hal_link'
    relatedWork:
      properties:
        relationship:
          format: string
          enum:
          - article
          - dataset
          - preprint
          - software
          - supplemental_information
          - primary_article
          - data_management_plan
        identifierType:
          type: string
        identifier:
          type: string
    hal_paged_response:
      allOf:
      - properties:
          _links:
            allOf:
            - $ref: '#/components/schemas/hal_self_link'
            - $ref: '#/components/schemas/hal_page_links'
      - $ref: '#/components/schemas/paging_counts'
    paging_counts:
      properties:
        count:
          type: integer
        total:
          type: integer
    hal_version_links:
      properties:
        stash:dataset:
          $ref: '#/components/schemas/hal_link'
        stash:files:
          $ref: '#/components/schemas/hal_link'
        stash:download:
          $ref: '#/components/schemas/hal_link'
        curies:
          type: array
          items:
            $ref: '#/components/schemas/hal_curie'
    funder:
      properties:
        organization:
          type: string
        identifier:
          type: string
          description: The organization identifier, for example a ROR ID.
          example: https://ror.org/00x6h5n95
        identifierType:
          description: Type of identifier — ror, isni, grid, crossref_funder_id or other.
          type: string
          example: ror
        awardNumber:
          type: string
        awardDescription:
          description: Usually used for the program or the division of the award.
          type: string
        order:
          type: integer
    hal_link:
      type: object
      properties:
        href:
          type: string
          format: uri
      required:
      - href
    Error:
      type: object
      properties:
        error:
          type: string
    geolocationPoint:
      type: object
      properties:
        latitude:
          description: The latitude of the point.
          type: number
        longitude:
          description: The longitude of the point.
          type: number
    dc_metadata:
      type: object
      properties:
        title:
          type: string
        authors:
          type: array
          items:
            $ref: '#/components/schemas/author'
        abstract:
          type: string
          description: An abstract introducing the dataset.
        funders:
          type: array
          items:
            $ref: '#/components/schemas/funder'
        keywords:
          type: array
          items:
            type: string
        fieldOfScience:
          type: string
          description: A term from the FOS (Fields of Science and Technology) controlled vocabulary. The main category of the dataset.
        hsiStatement:
          type: string
          description: A statement explaining the de-identification of any human subject data in the dataset.
        methods:
          type: string
          description: The methods by which the data was produced. Not required for publication.
        usageNotes:
          type: string
          description: Usage notes for the dataset (Deprecated; It is preferred for this content to appear in the README file for the dataset). If the dataset has been retracted, the retraction statement will appear here.
        locations:
          type: array
          items:
            $ref: '#/components/schemas/geolocation'
        relatedWorks:
          type: array
          items:
            $ref: '#/components/schemas/relatedWork'
      required:
      - title
      - authors
      - abstract
    file:
      allOf:
      - $ref: '#/components/schemas/file_links'
      - properties:
          path:
            type: string
          size:
            type: integer
          mimeType:
            type: string
          status:
            type: string
          digest:
            type: string
          digestType:
            type: string
          description:
            type: string
    version:
      allOf:
      - $ref: '#/components/schemas/version_links'
      - $ref: '#/components/schemas/dc_metadata'
      - properties:
          versionNumber:
            type: integer
          versionStatus:
            type: string
            enum:
            - in_progress
            - processing
            - submitted
            description: Internal processing status of files.
          curationStatus:
            type: string
            enum:
            - In progress
            - Processing
            - Queued for curation
            - Private for Peer Review
            - Awaiting payment
            - Curation
            - Action required
            - Withdrawn
            - Embargoed
            - Published
            description: Status of the submission in the curation workflow.
          versionChanges:
            type: string
            enum:
            - files_changed
            - metadata_changed
          publicationDate:
            type: string
          lastModificationDate:
            type: string
          visibility:
            type: string
            description: Whether or not this version is publicly visible.
    hal_file_links:
      properties:
        stash:dataset:
          $ref: '#/components/schemas/hal_link'
        stash:version:
          $ref: '#/components/schemas/hal_link'
        stash:files:
          $ref: '#/components/schemas/hal_link'
        stash:download:
          $ref: '#/components/schemas/hal_link'
        curies:
          type: array
          items:
            $ref: '#/components/schemas/hal_curie'
    geolocation:
      properties:
        place:
          description: A place name.
          type: string
        box:
          $ref: '#/components/schemas/geolocationBox'
          description: A bounding box.
        point:
          $ref: '#/components/schemas/geolocationPoint'
          description: A coordinate point.
    files:
      allOf:
      - $ref: '#/components/schemas/hal_paged_response'
      - $ref: '#/components/schemas/embedded_files'
    hal_self_link:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/hal_link'
    hal_curie:
      type: object
      properties:
        name:
          type: string
        href:
          type: string
          format: uri
        templated:
          type: boolean
      required:
      - name
      - href
      - templated
    version_links:
      properties:
        _links:
          allOf:
          - $ref: '#/components/schemas/hal_self_link'
          - $ref: '#/components/schemas/hal_version_links'
    author:
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        affiliation:
          type: string
        affiliationROR:
          type: string
          description: Preferred identifier for the author affiliation.
        affiliations:
          type: array
          items:
            name: string
            ror_id: string
        affiliationISNI:
          type: string
        orcid:
          type: string
        order:
          type: integer
  parameters:
    per_page:
      in: query
      name: per_page
      schema:
        type: integer
      description: Number of results to return on each page. Defaults to 20. Maximum allowed is 100.
    page:
      in: query
      name: page
      schema:
        type: integer
      description: Which page of results to view. Defaults to page 1.
    version_id:
      in: path
      name: id
      schema:
        type: integer
      required: true
      description: The version ID is a unique integer and can be obtained from the list of versions for a dataset.
  responses:
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not Found
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized, must have current bearer token.
    Unacceptable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: '406 - unacceptable: please set your `Content-Type` or `Accept` headers for application/json. `Accept` header is optional if you are using `Content-Type: application/json`.'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT