DataCite dois API

openapi: 3.2.0
info:
  title: REST Dois API
  description: The REST API is used for all API interactions with DataCite services.
  contact:
    name: DataCite Support
    url: https://support.datacite.org
    email: support@datacite.org
  license:
    name: MIT
    url: https://raw.githubusercontent.com/datacite/lupo/master/LICENSE
  version: 2.3.0
servers:
- url: https://api.test.datacite.org
  description: Staging server
- url: https://api.datacite.org
  description: Production server
security:
- {}
- BasicAuth: []
- bearerAuth: []
tags:
- name: dois
  description: DOIs
paths:
  /dois:
    get:
      tags:
      - dois
      summary: Return a list of DOIs.
      parameters:
      - in: query
        name: query
        description: Search [DOI metadata fields](https://support.datacite.org/docs/api-queries#using-the-query-parameter) using OpenSearch query string syntax.
        schema:
          type: string
      - in: query
        name: created
        description: Filter by the DOI date created (yyyy). Use commas to filter by multiple years (yyyy,yyyy).
        schema:
          type: string
          pattern: ^\d{4}(,\d{4})*$
      - in: query
        name: registered
        description: Filter by the DOI date registered (yyyy). Use commas to filter by multiple years (yyyy,yyyy).
        schema:
          type: string
          pattern: ^\d{4}(,\d{4})*$
      - in: query
        name: published
        description: Filter by the DOI date published (yyyy). Use commas to filter by multiple years (yyyy,yyyy).
        schema:
          type: string
          pattern: ^\d{4}(,\d{4})*$
      - in: query
        $ref: '#/components/parameters/providerIdParam'
      - in: query
        $ref: '#/components/parameters/clientIdParam'
      - in: query
        $ref: '#/components/parameters/consortiumIdParam'
      - in: query
        name: prefix
        description: Filter by a specific prefix. Use commas to include multiple prefixes.
        schema:
          type: string
        example: 10.5438
      - in: query
        name: client-type
        schema:
          $ref: '#/components/schemas/client-type'
      - in: query
        name: certificate
        schema:
          type: array
          items:
            $ref: '#/components/schemas/certificate'
        explode: false
        style: form
      - in: query
        name: affiliation-id
        description: Search creators.affiliation.affiliationIdentifier and contributors.affiliation.affiliationIdentifier for a ROR ID.
        schema:
          type: string
      - in: query
        name: affiliation-country
        description: Filter DOIs by associated country inferred from ROR IDs in creators/contributors affiliations. Use comma-separated ISO 3166-1 alpha-2 country codes.
        schema:
          type: string
        example: US,GB
      - in: query
        name: funded-by
        description: Search fundingReferences.funderIdentifier for a ROR ID. Results also include DOIs containing a Crossref Funder ID in fundingReferences.funderIdentifier corresponding to the ROR ID.
        schema:
          type: string
      - in: query
        name: include-funder-child-organizations
        description: When the `funded-by=` parameter is set to a ROR ID and `include-funder-child-organizations=true`, the returned list of DOIs will be filtered to DataCite resources funded by the organization identified by the ROR ID as well as all of its child organizations. Child organizations include direct descendants as well as children of children.
        schema:
          type: boolean
      - in: query
        name: funder-id
        description: Search fundingReferences.funderIdentifier for a Crossref Funder ID.
        schema:
          type: string
      - in: query
        name: user-id
        description: Search creators.nameIdentifiers.nameIdentifier for an ORCID iD.
        schema:
          type: string
      - in: query
        name: resource-type-id
        description: Filter by the resourceTypeGeneral. Use commas to include multiple values.
        schema:
          type: array
          items:
            type: string
            enum:
            - audiovisual
            - award
            - book
            - book-chapter
            - collection
            - computational-notebook
            - conference-paper
            - conference-proceeding
            - data-paper
            - dataset
            - dissertation
            - event
            - image
            - instrument
            - interactive-resource
            - journal
            - journal-article
            - model
            - output-management-plan
            - peer-review
            - physical-object
            - poster
            - preprint
            - presentation
            - project
            - report
            - service
            - software
            - sound
            - standard
            - study-registration
            - text
            - workflow
            - other
        explode: false
        style: form
      - in: query
        name: resource-type
        description: Filter by the free text resourceType. Use commas to include multiple values.
        schema:
          type: string
      - in: query
        name: subject
        description: Filter by the free text Subject. Use commas to include multiple terms.
        schema:
          type: string
      - in: query
        name: field-of-science
        schema:
          type: string
      - in: query
        name: license
        schema:
          type: string
      - in: query
        name: schema-version
        schema:
          type: string
        example: 4
      - in: query
        name: state
        description: Filter by the [DOI state](https://support.datacite.org/docs/doi-states). Authentication is required to retrieve registered DOIs and draft records.
        schema:
          type: array
          items:
            $ref: '#/components/schemas/state'
        explode: false
        style: form
        examples:
          findable:
            value: findable
          findable or registered:
            value: findable,registered
      - in: query
        $ref: '#/components/parameters/affiliationParam'
      - in: query
        $ref: '#/components/parameters/publisherParam'
      - in: query
        name: link-check-status
        schema:
          type: string
          enum:
          - 200
          - 400
          - 401
          - 403
          - 404
          - 410
          - 429
          - 500
          - 502
          - 503
      - in: query
        name: has-citations
        description: Search the citationCount field for integer values greater than or equal to the inputted value.
        schema:
          type: integer
      - in: query
        name: has-references
        description: Search the referenceCount field for integer values greater than or equal to the inputted value.
        schema:
          type: integer
      - in: query
        name: has-parts
        description: Search the partCount field for integer values greater than or equal to the inputted value.
        schema:
          type: integer
      - in: query
        name: has-part-of
        description: Search the partOfCount field for integer values greater than or equal to the inputted value.
        schema:
          type: integer
      - in: query
        name: has-versions
        description: Search the versionCount field for integer values greater than or equal to the inputted value.
        schema:
          type: integer
      - in: query
        name: has-version-of
        description: Search the versionOfCount field for integer values greater than or equal to the inputted value.
        schema:
          type: integer
      - in: query
        name: has-views
        description: Search the viewCount field for integer values greater than or equal to the inputted value.
        schema:
          type: integer
      - in: query
        name: has-downloads
        description: Search the downloadCount field for integer values greater than or equal to the inputted value.
        schema:
          type: integer
      - in: query
        name: has-person
        description: Return DOIs where creators.nameIdentifiers.nameIdentifierScheme has at least one "ORCID" value.
        schema:
          type: boolean
      - in: query
        name: has-affiliation
        description: Return DOIs where either creators.affiliation.affiliationIdentifierScheme or contributors.affiliation.affiliationIdentifierScheme has at least one "ROR" value.
        schema:
          type: boolean
      - in: query
        name: has-organization
        description: Return DOIs where either creators.nameIdentifiers.nameIdentifierScheme or contributors.nameIdentifiers.nameIdentifierScheme has at least one "ROR" value.
        schema:
          type: boolean
      - in: query
        name: has-funder
        description: Return DOIs where fundingReferences.funderIdentifierType has at least one "Crossref Funder ID" value.
        schema:
          type: boolean
      - in: query
        name: random
        description: Retrieve a random sample of DOIs. When true, the `page[number]` parameter is ignored.
        schema:
          type: boolean
      - in: query
        name: sample-size
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - in: query
        name: sample-group
        schema:
          type: string
          enum:
          - client
          - provider
          - resource-type
      - in: query
        $ref: '#/components/parameters/pageNumberParam'
      - in: query
        $ref: '#/components/parameters/pageSizeParam'
      - in: query
        $ref: '#/components/parameters/pageCursorParam'
      - in: query
        name: include
        schema:
          type: string
          enum:
          - client
          - media
      - in: query
        name: sort
        description: "Sort order:\n * `relevance` - Relevance score descending \n * `name` - DOI name alphabetical ascending \n * `-name` - DOI name alphabetical descending\n * `created` - Created date ascending\n * `-created` - Created date descending\n * `updated` - Updated date ascending\n * `-updated` - Updated date descending\n * `published` - Published date ascending\n * `-published` - Published date descending\n * `view-count` - viewCount ascending\n * `-view-count` - viewCount descending\n * `download-count` - downloadCount ascending\n * `-download-count` - downloadCount descending\n * `citation-count` - citationCount ascending\n * `-citation-count` - citationCount descending\n * `title` - first title alphabetical ascending\n * `-title` - first title alphabetical descending\n"
        schema:
          type: string
          enum:
          - relevance
          - name
          - -name
          - created
          - -created
          - updated
          - -updated
          - published
          - -published
          - view-count
          - -view-count
          - download-count
          - -download-count
          - citation-count
          - -citation-count
          - title
          - -title
      - in: query
        name: disable-facets
        description: Exclude facets from the response.
        schema:
          type: boolean
      - in: query
        name: detail
        description: "When set to `true`, will include the following in the response:\n * attributes:\n   * `prefix`\n   * `suffix`\n   * `viewsOverTime`\n   * `citationsOverTime`\n   * `references`\n   * `citations`\n   * `parts`\n   * `partOf`\n   * `versions`\n   * `versionOf`\n   * `xml`\n   * `alternateIdentifiers`\n* relationships:\n   * `provider`\n"
        schema:
          type: boolean
      - in: query
        name: fields[dois]
        description: Only return the attributes specified. For example, `fields[dois]=titles,subjects` will only return titles and subjects.
        schema:
          type: string
      - in: query
        name: source
        description: The [system used to create the DOI](https://support.datacite.org/docs/api-get-doi#source).
        schema:
          $ref: '#/components/schemas/source'
      responses:
        '200':
          description: A JSON array of DOIs.
          content:
            application/vnd.api+json:
              schema:
                description: Represents a list of DOIs and provides access to metadata attributes, further schema specific information can be found at https://schema.datacite.org
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DoiListItem'
                  meta:
                    allOf:
                    - $ref: '#/components/schemas/MetaCore'
                    - type: object
                      properties:
                        states:
                          allOf:
                          - description: Counts by DOI state.
                          - $ref: '#/components/schemas/MetaArray'
                        resourceTypes:
                          allOf:
                          - description: resourceTypes in the search results with counts.
                          - $ref: '#/components/schemas/MetaArray'
                        created:
                          allOf:
                          - description: Histogram of the create date of the DOI record by top 10 years with counts.
                          - $ref: '#/components/schemas/MetaArray'
                        published:
                          allOf:
                          - description: Histogram of publicationYear years with counts.
                          - $ref: '#/components/schemas/MetaArray'
                        registered:
                          allOf:
                          - description: Histogram of the registered date of the DOI record by top 10 years with counts.
                          - $ref: '#/components/schemas/MetaArray'
                        providers:
                          allOf:
                          - description: The top 10 DataCite Members or Consortium Organizations with account IDs, titles, and counts.
                          - $ref: '#/components/schemas/MetaArray'
                        clients:
                          allOf:
                          - description: The top 10 repositories in the search results with account IDs, titles, and counts.
                          - $ref: '#/components/schemas/MetaArray'
                        affiliations:
                          allOf:
                          - description: The top 10 represented ROR affiliations with ROR ID, research organization title, and counts.
                          - $ref: '#/components/schemas/MetaArray'
                        prefixes:
                          allOf:
                          - description: The top 10 prefixes in the search with counts.
                          - $ref: '#/components/schemas/MetaArray'
                        certificates:
                          allOf:
                          - description: Repository certificates in the search with counts.
                          - $ref: '#/components/schemas/MetaArray'
                        licenses:
                          allOf:
                          - description: The top 10 rights with rights identifiers in the search with counts.
                          - $ref: '#/components/schemas/MetaArray'
                        schemaVersions:
                          allOf:
                          - description: The DataCite Metadata Schema versions represented in the search with counts.
                          - $ref: '#/components/schemas/MetaArray'
                        linkChecksStatus:
                          allOf:
                          - description: The status of the landing pages of DOIs in the search (when and if last checked) with counts.
                          - $ref: '#/components/schemas/MetaArray'
                        subjects:
                          allOf:
                          - description: The top 10 subjects represented in the search with counts.
                          - $ref: '#/components/schemas/MetaArray'
                        fieldsOfScience:
                          allOf:
                          - description: The top 10 Fields of Science and Technology (FOS) subjects in the search with counts.
                          - $ref: '#/components/schemas/MetaArray'
                        citations:
                          allOf:
                          - description: A histogram of citations by publicationYear in the search by top 10 years with counts.
                          - $ref: '#/components/schemas/MetaArray'
                        views:
                          allOf:
                          - description: A histogram of views by publicationYear in the search by top 10 years with counts.
                          - $ref: '#/components/schemas/MetaArray'
                        downloads:
                          allOf:
                          - description: A histogram of downloads by publicationYear in the search by top 10 years with counts.
                          - $ref: '#/components/schemas/MetaArray'
                  links:
                    allOf:
                    - $ref: '#/components/schemas/Links'
                example:
                  data:
                    type: dois
                    attributes:
                      doi: 10.5438/0014
                      prefix: '10.5438'
                      suffix: '0014'
                      identifiers:
                      - identifier: https://doi.org/10.5438/0014
                        identifierType: DOI
                      creators:
                      - name: DataCite Metadata Working Group
                      titles:
                      - title: DataCite Metadata Schema Documentation for the Publication and Citation of Research Data v4.1
                      publisher: DataCite
                      publicationYear: 2017
                      types:
                        resourceTypeGeneral: Text
                      url: https://schema.datacite.org/meta/kernel-4.1/
    post:
      tags:
      - dois
      summary: Add a new DOI.
      security:
      - BasicAuth: []
      - bearerAuth: []
      parameters:
      - in: query
        $ref: '#/components/parameters/affiliationParam'
      - in: query
        $ref: '#/components/parameters/publisherParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DoiDetailItem'
      responses:
        '201':
          description: Created
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/DoiDetailItem'
  /dois/{id}:
    get:
      parameters:
      - name: id
        in: path
        description: DOI
        required: true
        schema:
          type: string
      - in: query
        $ref: '#/components/parameters/affiliationParam'
      - in: query
        $ref: '#/components/parameters/publisherParam'
      tags:
      - dois
      summary: Return a DOI.
      responses:
        '200':
          description: A JSON object.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/DoiDetailItem'
    put:
      parameters:
      - name: id
        in: path
        description: The DOI to update.
        required: true
        schema:
          type: string
      - in: query
        $ref: '#/components/parameters/affiliationParam'
      - in: query
        $ref: '#/components/parameters/publisherParam'
      tags:
      - dois
      summary: Update a DOI.
      description: PUT requests to the /dois endpoint will update a DOI record if it already exists and create a new record if the DOI name is not already taken.
      security:
      - BasicAuth: []
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DoiDetailItem'
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/DoiDetailItem'
    delete:
      parameters:
      - name: id
        in: path
        description: DOI
        required: true
        schema:
          type: string
      tags:
      - dois
      summary: Delete a DOI (for DOIs in draft state only).
      security:
      - BasicAuth: []
      - bearerAuth: []
      responses:
        '204':
          description: No content
  /dois/{id}/activities:
    get:
      parameters:
      - name: id
        in: path
        description: DOI
        required: true
        schema:
          type: string
      tags:
      - dois
      summary: Return activities for a specific DOI.
      responses:
        '200':
          description: A JSON object.
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Activity'
                  meta:
                    allOf:
                    - $ref: '#/components/schemas/MetaCore'
                  links:
                    allOf:
                    - $ref: '#/components/schemas/Links'
components:
  schemas:
    versionCount:
      description: Total number of versions, pulled from Event Data.
      readOnly: true
      type: number
    DoiDetailItem:
      description: Represents a single DOI and provides access to metadata attributes. More information is available at https://schema.datacite.org.
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              readOnly: true
            type:
              type: string
              enum:
              - dois
            attributes:
              allOf:
              - type: object
                properties:
                  doi:
                    description: The full DOI name.
                    type: string
                  event:
                    description: "Can be set to trigger a [DOI state change](https://support.datacite.org/docs/updating-metadata-with-the-rest-api#changing-the-doi-state). When not set, a [Draft record](https://support.datacite.org/docs/doi-states#draft-record) is created.\n  * `publish` - Create a DOI in [Findable state](https://support.datacite.org/docs/doi-states#findable-doi-name) (or change an existing Draft record/Registered DOI to Findable state).\n  * `register` - Create a DOI in [Registered state](https://support.datacite.org/docs/doi-states#registered-doi-name) (or change an existing Draft record to Registered state).\n  * `hide` - Change a DOI from Findable to Registered state.\n"
                    type: string
                    enum:
                    - publish
                    - register
                    - hide
                    writeOnly: true
                  prefix:
                    description: The DOI prefix.
                    type: string
                  suffix:
                    description: The DOI suffix.
                    readOnly: true
                    type: string
                  identifiers:
                    description: Equivalent to the [AlternateIdentifier](https://datacite-metadata-schema.readthedocs.io/en/4/properties/alternateidentifier/) property in the DataCite Metadata Schema. For more information, see [What is the "identifiers" attribute in the REST API?](https://support.datacite.org/docs/what-is-the-identifiers-attribute-in-the-rest-api)
                    type: array
                    items:
                      type: object
                      properties:
                        identifier:
                          type: string
                        identifierType:
                          type: string
                  alternateIdentifiers:
                    description: '[DataCite Metadata Schema: AlternateIdentifier](https://datacite-metadata-schema.readthedocs.io/en/4/properties/alternateidentifier/)'
                    type: array
                    items:
                      type: object
                      properties:
                        alternateIdentifierType:
                          type: string
                        alternateIdentifier:
                          type: string
              - $ref: '#/components/schemas/DoiPropertiesMetadata'
              - type: object
                properties:
                  xml:
                    description: DataCite Metadata Schema XML encoded in Base64 format.
                    type: string
              - $ref: '#/components/schemas/DoiPropertiesOther'
              - type: object
                properties:
                  viewCount:
                    $ref: '#/components/schemas/viewCount'
                  viewsOverTime:
                    readOnly: true
                    type: array
                    items:
                      type: object
                      properties:
                        yearMonth:
                          type: string
                        total:
                          type: number
                  downloadCount:
                    $ref: '#/components/schemas/downloadCount'
                  downloadsOverTime:
                    readOnly: true
                    type: array
                    items:
                      type: object
                      properties:
                        yearMonth:
                          type: string
                        total:
                          type: number
                  referenceCount:
                    $ref: '#/components/schemas/referenceCount'
                  citationCount:
                    $ref: '#/components/schemas/citationCount'
                  citationsOverTime:
                    readOnly: true
                    type: array
                    items:
                      type: object
                      properties:
                        year:
                          type: string
                        total:
                          type: number
                  partCount:
                    $ref: '#/components/schemas/partCount'
                  partOfCount:
                    $ref: '#/components/schemas/partOfCount'
                  versionCount:
                    $ref: '#/components/schemas/versionCount'
                  versionOfCount:
                    $ref: '#/components/schemas/versionOfCount'
                  landingPage:
                    readOnly: true
                    description: Data describing the landing page, used by link checking.
                    type: object
                    properties:
                      checked:
                        type: string
                      url:
                        type: string
                      contentType:
                        type: string
                      error:
                        type: string
                      redirectCount:
                        type: number
                      redirectUrls:
                        type: array
                        items:
                          type: string
                      downloadLatency:
                        type: number
                      hasSchemaOrg:
                        type: boolean
                      schemaOrgid:
                        type: string
                      dcIdentifier:
                        type: string
                      citationDoi:
                        type: string
                      bodyhasPid:
                        type: boolean
              - $ref: '#/components/schemas/DoiPropertiesDates'
            relationships:
              type: object
              readOnly: true
              properties:
                client:
                  type: object
                  description: The DataCite client (repository) associated with the DOI.
                  properties:
                    data:
                      $ref: '#/components/schemas/DataObject'
                provider:
                  type: object
                  description: The DataCite provider (Direct Member or Consortium Organization) associated with the DOI.
                  properties:
                    data:
                      $ref: '#/components/schemas/DataObject'
                media:
                  type: object
                  description: Legacy attribute for media support.
                  properties:
                    data:
                      $ref: '#/components/schemas/DataObject'
                references:
                  type: object
                  description: An array of references as dictionaries.
                  properties:
                    data:
                      $ref: '#/components/schemas/DataArray'
                citations:
                  type: object
                  description: An array of citations as dictionaries.
                  properties:
                    data:
                      $ref: '#/components/schemas/DataArray'
                parts:
                  description: An array of parts as dictionaries.
                  type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/DataArray'
                partOf:
                  description: An array of parents as dictionaries.
                  type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/DataArray'
                versions:
                  type: object
                  description: An array of versions as dictionaries.
                  properties:
                    data:
                      $ref: '#/components/schemas/DataArray'
                versionOf:
                  type: object
                  description: An array of objects to which this DOI is a version as dictionaries.
                  properties:
                    data:
                      $ref: '#/components/schemas/DataArray'
          required:
          - type
      example:
        data:
          type: dois
          attributes:
            doi: 10.5438/0014
            prefix: '10.5438'
            suffix: '0014'
            identifiers:
            - identifier: https://doi.org/10.5438/0014
              identifierType: DOI
            creators:
            - name: DataCite Metadata Working Group
            titles:
            - title: DataCite Metadata Schema Documentation for the Publication and Citation of Research Data v4.1
            publisher: DataCite
            publicationYear: 2017
            types:
              resourceTypeGeneral: Text
            url: https://schema.datacite.org/meta/kernel-4.1/
    titleType:
      type: string
      enum:
      - AlternativeTitle
      - Subtitle
      - TranslatedTitle
      - Other
    nameType:
      type: string
      enum:
      - Personal
      - Organizational
    referenceCount:
      description: Total references, pulled from Event Data.
      readOnly: true
      type: number
    relationType:
      description: '[DataCite Metadata Schema: relationType](https://datacite-metadata-schema.readthedocs.io/en/4/appendices/appendix-1/relationType/)'
      type: string
      enum:
      - IsCitedBy
      - Cites
      - IsSupplementTo
      - IsSupplementedBy
      - IsContinuedBy
      - Continues
      - IsDescribedBy
      - Describes
      - 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
      - IsCollectedBy
      - Collects
      - IsTranslationOf
      - HasTranslation
      - Other
    partOfCount:
      description: Total number of parents, pulled from 

# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/datacite/refs/heads/main/openapi/datacite-dois-api-openapi.yml