openapi: 3.1.0
info:
  title: Dryad datasets search 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: search
  description: Searching datasets
paths:
  /search:
    get:
      summary: Search publicly-available datasets
      tags:
      - search
      description: Search the published Dryad datasets. Query all fields, or look for terms in specific metadata fields of the dataset.
      parameters:
      - in: query
        name: q
        schema:
          type: string
        description: A list of terms to be searched. If multiple terms are supplied, matches will only be returned for items that contain all terms. Terms may include an `*` at the end to indicate a wildcard. A term may be negated to indicate that it should *not* be present in the results (e.g., `cat -fish`). Use quotation marks to search for an exact phrase.
      - in: query
        name: subject
        schema:
          type: string
        description: Search for a dataset by subject keyword.
      - in: query
        name: orcid
        schema:
          type: string
        description: Search for authors using author [ORCIDs](https://orcid.org/). If multiple, separate with a space.
      - in: query
        name: author
        schema:
          type: string
        description: Search for authors by name.
      - in: query
        name: affiliation
        schema:
          type: string
        description: A ROR identifier for an institutional affiliation that must be present in the list of dataset authors. The identifier should be in the full "https" format and should be URL-encoded, e.g., `https%3A%2F%2Fror.org%2F00x6h5n95`.
      - in: query
        name: facility
        schema:
          type: string
        description: A ROR identifier for the dataset research facility. The identifier should be in the full "https" format and should be URL-encoded, e.g., `https%3A%2F%2Fror.org%2F00x6h5n95`.
      - in: query
        name: funder
        schema:
          type: string
        description: A ROR identifier for a dataset funder. The identifier should be in the full "https" format and should be URL-encoded, e.g., `https%3A%2F%2Fror.org%2F00x6h5n95`.
      - in: query
        name: org
        schema:
          type: string
        description: A ROR identifier for a dataset funder, affiliation, or research facility. The identifier should be in the full "https" format and should be URL-encoded, e.g., `https%3A%2F%2Fror.org%2F00x6h5n95`.
      - in: query
        name: tenant
        schema:
          type: string
        description: The abbreviation for a partner organization in Dryad. This will automatically search all organizations associated with the given tenant.
      - in: query
        name: award
        schema:
          type: string
        description: An award or grant number associated with the dataset.
      - in: query
        name: journalISSN
        schema:
          type: string
        description: The journal ISSN.
      - in: query
        name: relatedId
        schema:
          type: string
        description: Any related work ID associated with the dataset, including manuscript numbers and PubMed IDs.
      - in: query
        name: publishedSince
        schema:
          type: string
        description: A date or timestamp for limiting results. Datasets will only be returned that have been published since the given date/time. The date must be specified in ISO 8601 format (`2020-10-08`). If including a time, the time must be specified in ISO 8601 format, and the time zone must be set to UTC, e.g., `2020-10-08T10:24:53Z`.
      - in: query
        name: publishedBefore
        schema:
          type: string
        description: A date or timestamp for limiting results. Datasets will only be returned that have been published before the given date/time. The date must be specified in ISO 8601 format (`2020-10-08`). If including a time, the time must be specified in ISO 8601 format, and the time zone must be set to UTC, e.g., `2020-10-08T10:24:53Z`.
      - in: query
        name: relatedWorkIdentifier
        schema:
          type: string
        description: A DOI or other URL that links a dataset to a related work. It allows `*` as a wildcard at the beginning and/or end of the value.
      - in: query
        name: relatedWorkRelationship
        schema:
          type: string
        description: The type of relationship expressed by a related work.
      - in: query
        name: modifiedSince
        schema:
          type: string
        description: A date or timestamp for limiting results. Datasets will only be returned that have been modified since the given date/time. The date must be specified in ISO 8601 format (`2020-10-08`). If including a time, the time must be specified in ISO 8601 format, and the time zone must be set to UTC, e.g., `2020-10-08T10:24:53Z`.
      - in: query
        name: modifiedBefore
        schema:
          type: string
        description: A date or timestamp for limiting results. Datasets will only be returned that have been modified before the given date/time. The date must be specified in ISO 8601 format (`2020-10-08`). If including a time, the time must be specified in ISO 8601 format, and the time zone must be set to UTC, e.g., `2020-10-08T10:24:53Z`.
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: A list of datasets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/datasets'
              examples:
                success:
                  $ref: api/v2/docs/examples/datasets.json
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Dryad encountered an error parsing the query options for the search. The most likely cause of this problem is an improperly-formatted timestamp for the `modifiedSince` parameter.
components:
  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.
  schemas:
    embedded_datasets:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            stash:datasets:
              type: array
              items:
                $ref: '#/components/schemas/dataset'
    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
    dataset_links:
      properties:
        _links:
          allOf:
          - $ref: '#/components/schemas/hal_self_link'
          - $ref: '#/components/schemas/hal_dataset_links'
    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
    dataset:
      allOf:
      - properties:
          identifier:
            type: string
          id:
            type: integer
          storageSize:
            type: integer
          relatedPublicationISSN:
            type: string
      - $ref: '#/components/schemas/version'
      - $ref: '#/components/schemas/dataset_links'
      - properties:
          metrics:
            type: object
            properties:
              views:
                type: integer
              downloads:
                type: integer
              citations:
                type: integer
          license:
            type: string
            description: The license of the dataset
    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
    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.
    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.
    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
    hal_dataset_links:
      properties:
        stash:versions:
          $ref: '#/components/schemas/hal_link'
        stash:version:
          $ref: '#/components/schemas/hal_link'
        stash:download:
          $ref: '#/components/schemas/hal_link'
        curies:
          type: array
          items:
            $ref: '#/components/schemas/hal_curie'
    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
    datasets:
      allOf:
      - $ref: '#/components/schemas/hal_paged_response'
      - $ref: '#/components/schemas/embedded_datasets'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT