OpenAPI Specification
openapi: 3.0.0
info:
title: REST activities 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:
citationCount:
description: Total citations, pulled from Event Data.
readOnly: true
type: number
Activity:
type: object
description: Represents an activity for an event within DataCite systems.
properties:
id:
type: string
example: 57690e72-b1be-4370-9f35-de6bec5f7b71
type:
type: string
enum:
- activities
attributes:
type: object
properties:
prov:wasGeneratedBy:
type: string
prov:generatedAtTime:
type: string
prov:wasDerivedFrom:
type: string
prov:wasAttributedTo:
type: string
action:
type: string
version:
type: number
changes:
type: object
DoiPropertiesMetadata:
type: object
properties:
creators:
description: '[DataCite Metadata Schema: Creator](https://datacite-metadata-schema.readthedocs.io/en/4/properties/creator/)'
type: array
items:
type: object
properties:
nameType:
$ref: '#/components/schemas/nameType'
nameIdentifiers:
type: array
items:
type: object
properties:
nameIdentifier:
type: string
nameIdentifierScheme:
type: string
schemeUri:
type: string
name:
type: string
givenName:
type: string
familyName:
type: string
affiliation:
description: Set `affiliation=true` to see additional affiliation information such as the affiliation identifier.
type: array
items:
type: object
properties:
affiliationIdentifier:
type: string
affiliationIdentifierScheme:
type: string
name:
type: string
schemeUri:
type: string
lang:
type: string
titles:
description: '[DataCite Metadata Schema: Title](https://datacite-metadata-schema.readthedocs.io/en/4/properties/title/)'
type: array
items:
type: object
properties:
title:
type: string
titleType:
$ref: '#/components/schemas/titleType'
lang:
type: string
publisher:
description: '[DataCite Metadata Schema: Publisher](https://datacite-metadata-schema.readthedocs.io/en/4/properties/publisher/) Set `publisher=true` to see additional publisher information such as the publisher identifier.
'
oneOf:
- type: object
properties:
name:
type: string
publisherIdentifier:
type: string
publisherIdentifierScheme:
type: string
schemeUri:
type: string
lang:
type: string
- type: string
container:
readOnly: true
type: object
properties:
type:
type: string
identifier:
type: string
identifierType:
type: string
title:
type: string
volume:
type: string
issue:
type: string
firstPage:
type: string
lastPage:
type: string
publicationYear:
description: '[DataCite Metadata Schema: PublicationYear](https://datacite-metadata-schema.readthedocs.io/en/4/properties/publicationyear/)'
type: integer
subjects:
description: '[DataCite Metadata Schema: Subject](https://datacite-metadata-schema.readthedocs.io/en/4/properties/subject/)'
type: array
items:
$ref: '#/components/schemas/subject'
contributors:
description: '[DataCite Metadata Schema: Contributor](https://datacite-metadata-schema.readthedocs.io/en/4/properties/contributor/)'
type: array
items:
type: object
properties:
nameType:
$ref: '#/components/schemas/nameType'
nameIdentifiers:
type: array
items:
type: object
properties:
nameIdentifier:
type: string
nameIdentifierScheme:
type: string
schemeUri:
type: string
name:
type: string
givenName:
type: string
familyName:
type: string
affiliation:
description: Set `affiliation=true` to see additional affiliation information such as the affiliation identifier.
type: array
items:
type: object
properties:
affiliationIdentifier:
type: string
affiliationIdentifierScheme:
type: string
name:
type: string
schemeUri:
type: string
contributorType:
$ref: '#/components/schemas/contributorType'
lang:
type: string
dates:
description: '[DataCite Metadata Schema: Date](https://datacite-metadata-schema.readthedocs.io/en/4/properties/date/)'
type: array
items:
type: object
properties:
date:
type: string
dateType:
type: string
enum:
- Accepted
- Available
- Copyrighted
- Collected
- Coverage
- Created
- Issued
- Submitted
- Updated
- Valid
- Withdrawn
- Other
dateInformation:
type: string
language:
description: '[DataCite Metadata Schema: Language](https://datacite-metadata-schema.readthedocs.io/en/4/properties/language/)'
type: string
types:
type: object
properties:
resourceTypeGeneral:
$ref: '#/components/schemas/resourceTypeGeneral'
resourceType:
description: '[DataCite Metadata Schema: ResourceType](https://datacite-metadata-schema.readthedocs.io/en/4/properties/resourcetype/)'
type: string
schemaOrg:
readOnly: true
type: string
bibtex:
readOnly: true
type: string
citeproc:
readOnly: true
type: string
ris:
readOnly: true
type: string
relatedIdentifiers:
description: '[DataCite Metadata Schema: RelatedIdentifier](https://datacite-metadata-schema.readthedocs.io/en/4/properties/relatedidentifier/)'
type: array
items:
type: object
properties:
relatedIdentifier:
type: string
relatedIdentifierType:
$ref: '#/components/schemas/relatedIdentifierType'
relationType:
$ref: '#/components/schemas/relationType'
resourceTypeGeneral:
$ref: '#/components/schemas/resourceTypeGeneral'
relatedMetadataScheme:
type: string
schemeUri:
type: string
schemeType:
type: string
relationTypeInformation:
type: string
relatedItems:
description: '[DataCite Metadata Schema: RelatedItem](https://datacite-metadata-schema.readthedocs.io/en/4/properties/relateditem/)'
type: array
items:
type: object
properties:
relatedItemType:
$ref: '#/components/schemas/resourceTypeGeneral'
relationType:
$ref: '#/components/schemas/relationType'
relatedItemIdentifier:
type: object
properties:
relatedItemIdentifier:
type: string
relatedItemIdentifierType:
$ref: '#/components/schemas/relatedIdentifierType'
relatedMetadataScheme:
type: string
schemeURI:
type: string
schemeType:
type: string
relationTypeInformation:
type: string
creators:
type: array
items:
type: object
properties:
name:
type: string
givenName:
type: string
familyName:
type: string
nameType:
$ref: '#/components/schemas/nameType'
titles:
type: array
items:
type: object
properties:
title:
type: string
titleType:
$ref: '#/components/schemas/titleType'
volume:
type: string
issue:
type: string
number:
type: string
numberType:
type: string
enum:
- Article
- Chapter
- Report
- Other
firstPage:
type: string
lastPage:
type: string
publisher:
type: string
publicationYear:
type: string
edition:
type: string
contributors:
type: array
items:
type: object
properties:
name:
type: string
givenName:
type: string
familyName:
type: strin
# --- 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