{
"openapi": "3.1.0",
"info": {
"title": "Dryad 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 URL-encoded to ensure correct processing. Anonymous users of the API are limited to 30 requests per minute, with a lower limit for downloads of 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- [See versions of a dataset](https://datadryad.org/api/v2/datasets/doi%3A10.5061%2Fdryad.j1fd7/versions)\n- [Get files from a version](https://datadryad.org/api/v2/versions/26724/files)\n- [Download the most recent version of a dataset](https://datadryad.org/api/v2/datasets/doi%3A10.5061%2Fdryad.j1fd7/download)\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 120 requests per minute)\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 API accounts document 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 API submission examples document gives concrete examples of submission through the Dryad API.\n\n\n### Dryad sandbox\n\nDryad's sandbox server 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 sandbox version of ORCID, 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": "root",
"description": "Root-level API calls"
},
{
"name": "datasets",
"description": "Dataset operations"
},
{
"name": "versions",
"description": "Operations on individual versions of a dataset"
},
{
"name": "files",
"description": "Operations on individual files of a dataset"
},
{
"name": "reports",
"description": "Reports on content in Dryad"
},
{
"name": "internal",
"description": "Internal APIs not of general interest to the public"
}
],
"paths": {
"/": {
"get": {
"summary": "The root of the API",
"tags": [
"root"
],
"description": "Displays links to root level API objects, like the list of datasets.",
"responses": {
"200": {
"description": "The root of the API.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/root_links"
},
"examples": {
"success": {
"$ref": "api/v2/docs/examples/root.json"
}
}
}
}
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
}
},
"/test": {
"get": {
"security": [
{
"bearerAuth": []
}
],
"summary": "Test OAuth2 and bearer authentication",
"tags": [
"root"
],
"description": "Test your API account authentication by sending authenticated headers: `Accept: application/json`, `Content-Type: application/json`, `Authorization: Bearer {your-token}`. \n\n `Accept` header is optional if you are using `Content-Type: application/json`.",
"responses": {
"200": {
"description": "Shows a welcome message if successful.",
"content": {
"application/json": {
"schema": {
"properties": {
"message": {
"type": "string",
"example": "Welcome Brenda Ngrulu"
},
"user_id": {
"type": "integer",
"example": 10
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
}
},
"/datasets": {
"get": {
"summary": "Get a list of all datasets",
"tags": [
"datasets"
],
"description": "The items returned may depend on user permissions, and are paged.",
"parameters": [
{
"$ref": "#/components/parameters/page"
},
{
"$ref": "#/components/parameters/per_page"
},
{
"$ref": "#/components/parameters/publicationISSN"
},
{
"$ref": "#/components/parameters/publicationName"
},
{
"$ref": "#/components/parameters/manuscriptNumber"
},
{
"$ref": "#/components/parameters/curationStatus"
}
],
"responses": {
"200": {
"description": "A list of datasets.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/datasets"
},
"examples": {
"success": {
"$ref": "api/v2/docs/examples/datasets.json"
}
}
}
}
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
},
"post": {
"summary": "Create a new dataset with an automatically-generated DOI",
"tags": [
"datasets"
],
"description": "You must be logged in. Use a JSON structure as shown below.\n\nIf no funders are declared, users will be asked to list them later; to declare no funding submit a funder with identifier: '0' (see the \"Set no funding\" example). If human subject information is in the dataset, include a statement explaining how the data was de-identified (see the 'Include HSI statement' example).\n\nFor a more full list of properties that can be sent, check the Model below and the sample dataset object.",
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/dc_metadata"
},
{
"$ref": "#/components/schemas/admin_values"
}
]
},
"examples": {
"Post": {
"$ref": "api/v2/docs/examples/dataset_post_request.json"
},
"Include journal information": {
"$ref": "api/v2/docs/examples/dataset_post_request_jr.json"
},
"Set no funding": {
"$ref": "api/v2/docs/examples/dataset_post_request_nf.json"
},
"Include HSI statement": {
"$ref": "api/v2/docs/examples/dataset_post_request_hsi.json"
}
}
}
}
},
"responses": {
"201": {
"description": "Show the dataset information that has been saved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/datasets"
},
"examples": {
"Success": {
"$ref": "api/v2/docs/examples/dataset_post_response.json"
},
"With journal": {
"$ref": "api/v2/docs/examples/dataset_post_response_jr.json"
},
"Without funding": {
"$ref": "api/v2/docs/examples/dataset_post_response_nf.json"
},
"With HSI statement": {
"$ref": "api/v2/docs/examples/dataset_post_response_hsi.json"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/datasets/{doi}": {
"get": {
"summary": "Get a dataset record by its DOI",
"tags": [
"datasets"
],
"description": "Be sure to URL encode the DOI (see example below). Datasets that are not yet published are only retrievable by users with permission to access them.",
"parameters": [
{
"$ref": "#/components/parameters/doi"
}
],
"responses": {
"200": {
"description": "Dataset information retrieved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dataset"
},
"examples": {
"success": {
"$ref": "api/v2/docs/examples/dataset.json"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
},
"put": {
"summary": "Update (overwrite) dataset metadata for DOI",
"tags": [
"datasets"
],
"description": "This will overwrite writeable metadata for an in-progress dataset. This is an insert or update action (upsert). Be sure to URL encode the DOI (see example below). You must be logged in. Use a JSON structure as shown below. For a more full list of properties that can be sent, check the Schema below and the sample dataset object.",
"parameters": [
{
"$ref": "#/components/parameters/doi"
}
],
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/dc_metadata"
},
{
"properties": {
"identifier": {
"type": "string",
"description": "The Dryad dataset DOI"
}
}
},
{
"$ref": "#/components/schemas/admin_values"
}
]
},
"examples": {
"success": {
"$ref": "api/v2/docs/examples/dataset_post_request.json"
}
}
}
}
},
"responses": {
"200": {
"description": "Show the dataset information that has been saved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/datasets"
},
"examples": {
"success": {
"$ref": "api/v2/docs/examples/dataset.json"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
},
"patch": {
"parameters": [
{
"$ref": "#/components/parameters/doi"
}
],
"security": [
{
"bearerAuth": []
}
],
"summary": "Update the state of an in-progress dataset",
"tags": [
"datasets"
],
"description": "Sending a JSON patch request whose JSON body looks like **[ { 'op': 'replace', 'path': '/versionStatus', 'value': 'submitted' } ]**. (This is the most common command, attempting to change the versionStatus to Submitted.) Other options are available that are useful for integration with manuscript processing systems. See the [embedded Dryad documentation](https://github.com/datadryad/dryad-app/blob/main/documentation/apis/embedded_submission.md) for details. Set http header **'Content-Type: application/json-patch+json'** when making the request instead of a standard json content-type.",
"requestBody": {
"description": "JSON Patch object",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/dataset_submission"
}
}
}
}
},
"responses": {
"202": {
"description": "Submission taking place, watch the dataset versionStatus for changes.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dataset"
},
"examples": {
"success": {
"$ref": "api/v2/docs/examples/dataset.json"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "Your dataset cannot be updated now"
}
}
}
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
}
},
"/datasets/{doi}/download": {
"get": {
"summary": "Get a download package for a dataset",
"tags": [
"datasets"
],
"description": "This downloads the zip package of the latest submitted version of the dataset that is visible to the user (or public).",
"parameters": [
{
"$ref": "#/components/parameters/doi"
}
],
"responses": {
"200": {
"description": "The binary content for a compressed archive.",
"content": {
"application/zip": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/datasets/{doi}/versions": {
"get": {
"summary": "Show all versions of a dataset",
"tags": [
"datasets"
],
"description": "The /versions endpoint lists all versions visible to the user (or public). This is in contrast to GETting the datasets endpoint for a DOI, since it only embeds metadata for the latest visible version.",
"parameters": [
{
"$ref": "#/components/parameters/doi"
},
{
"$ref": "#/components/parameters/page"
},
{
"$ref": "#/components/parameters/per_page"
}
],
"responses": {
"200": {
"description": "A list of a dataset's versions.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/versions"
},
"examples": {
"success": {
"$ref": "api/v2/docs/examples/versions.json"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
}
},
"/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 /versions 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"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
}
},
"/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"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
}
},
"/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).",
"parameters": [
{
"$ref": "#/components/parameters/version_id"
}
],
"responses": {
"200": {
"description": "The binary content for a compressed archive.",
"content": {
"application/zip": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "not found"
}
}
}
}
}
}
},
"/files/{id}": {
"get": {
"summary": "Get metadata information about a file",
"tags": [
"files"
],
"description": "Returns file metadata information visible to the user (or public) by the file ID. The version file list embeds this metadata and also lists the file IDs.",
"parameters": [
{
"$ref": "#/components/parameters/file_id"
}
],
"responses": {
"200": {
"description": "A single file.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/file"
},
"examples": {
"success": {
"$ref": "api/v2/docs/examples/file.json"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
},
"delete": {
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/file_id"
}
],
"summary": "Remove a file from an in-progress dataset version",
"tags": [
"files"
],
"description": "This action only works on an in-progress dataset (this means that the latest version of a dataset associated with this file has to be in-progress). It will destroy the metadata and file if it's a staged file that hasn't been submitted to the repository yet. If the file was submitted previously in an earlier version of the same dataset it will stage removal from the in-progress dataset version. In order to finalize staged file changes into the storage repository, the in-progress dataset must be submitted again after all changes are ready.",
"responses": {
"201": {
"description": "The file and metadata was removed from staging. Or the file and metadata was staged for removal from this version.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/file"
},
"examples": {
"success": {
"$ref": "api/v2/docs/examples/file.json"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "This file must be part of an an in-progress version."
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
}
},
"/files/{id}/download": {
"get": {
"summary": "Download a specific file",
"tags": [
"files"
],
"description": "Only files that have been stored in the storage repository may be downloaded (and ability to download may depend on the user). Versions of a dataset still in-progress only have staged files that may not be downloaded until they have been submitted to the storage repository.",
"parameters": [
{
"$ref": "#/components/parameters/file_id"
}
],
"responses": {
"200": {
"description": "The binary content of the file downloads as the http body. The \"Content-Type\" and \"Content-Disposition\" headers will be set to reflect the file content-type and filename when downloading (following http standards).",
"content": {
"*/*": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/datasets/{doi}/files/{filename}": {
"put": {
"summary": "Upload and stage a file for an in-progress dataset",
"tags": [
"files"
],
"description": "Allows uploading a file to be staged for submission to the storage repository. The files will be stored in the storage repository after the dataset is submitted. The body of the request will be the file you are uploading. Set the `Content-Type` http header to the appropriate mimetype for your file when uploading.",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/doi"
},
{
"$ref": "#/components/parameters/filename"
}
],
"requestBody": {
"description": "A binary file with `Content-Type` set.",
"required": true,
"content": {
"*/*": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"responses": {
"201": {
"description": "File was created on the server.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/file"
},
{
"properties": {
"url": {
"type": "string"
}
}
}
]
},
"examples": {
"success": {
"$ref": "api/v2/docs/examples/upload_file.json"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/datasets/{doi}/urls": {
"post": {
"summary": "Stage a file submission by URL",
"tags": [
"files"
],
"description": "The URL you specify will be deposited into the storage repository from a publicly accessible URL on the internet when the in-progress dataset is submitted. The dataset must be an in-progress dataset. The URL will be validated and metadata about it obtained to populate metadata about the file when it is added. Send the url to be retrieved as part of a JSON document like **{'url': 'http://example.org/testing/my/file.csv' }**. Priviliged users may have additional options to specify URL metadata rather than having live-validation and metadata gathering performed from the Internet.",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/doi"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/url_json"
}
}
}
},
"responses": {
"201": {
"description": "Metadata for the URL was saved and the response JSON indicates information populated for a file object based on the URL.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/file"
},
{
"properties": {
"url": {
"type": "string"
}
}
}
]
},
"examples": {
"success": {
"$ref": "api/v2/docs/examples/upload_file.json"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
}
},
"/processor_results/{id}": {
"get": {
"security": [
{
"bearerAuth": []
}
],
"summary": "Get processor results for the ID given",
"tags": [
"internal"
],
"description": "Shows the processor results stored in the database for the given ID.",
"parameters": [
{
"$ref": "#/components/parameters/processor_result_id"
}
],
"responses": {
"200": {
"description": "A JSON representation of processor results.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/processor_result"
}
}
}
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
},
"put": {
"security": [
{
"bearerAuth": []
}
],
"summary": "Overwrite processor results for the ID given",
"tags": [
"internal"
],
"description": "Overwrite the processor results stored in the database for the given ID, resource_id, dates can't be manually changed",
"parameters": [
{
"$ref": "#/components/parameters/processor_result_id"
}
],
"responses": {
"200": {
"description": "A JSON representation of processor results that were saved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/processor_result"
}
}
}
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
}
},
"/versions/{version_id}/processor_results": {
"get": {
"security": [
{
"bearerAuth": []
}
],
"summary": "Get processor results for the version given",
"tags": [
"internal"
],
"description": "Shows the processor results stored in the database for the resource_id",
"parameters": [
{
"$ref": "#/components/parameters/version_id"
}
],
"responses": {
"200": {
"description": "A JSON representation of processor results for the version ID.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/processor_results"
}
}
}
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
},
"post": {
"security": [
{
"bearerAuth": []
}
],
"summary": "Create processor results for the ID given",
"tags": [
"internal"
],
"description": "Create a new processor result in the database.",
"parameters": [
{
"$ref": "#/components/parameters/processor_result_id"
}
],
"responses": {
"200": {
"description": "A JSON representation of processor results that were saved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/processor_result"
}
}
}
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
}
},
"/datasets/{doi}/related_works/{related_doi}": {
"put": {
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/related_type"
}
}
}
},
"summary": "Update related works for a Dryad DOI",
"tags": [
"internal"
],
"description": "Adds or updates related works for a Dryad DOI.",
"parameters": [
{
"$ref": "#/components/parameters/doi"
},
{
"$ref": "#/components/parameters/doi"
}
],
"responses": {
"200": {
"description": "A JSON representation of the related work that was saved.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/relatedWork"
}
}
}
},
"401": {
"$ref": "#/components/responses/unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
}
},
"/reports": {
"get": {
"summary": "Get a list of reports that are updated regularly",
"tags": [
"reports"
],
"responses": {
"200": {
"description": "A list of reports URLs.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/reports"
}
}
}
},
"406": {
"$ref": "#/components/responses/Unacceptable"
}
}
}
},
"/reports/{name}": {
"get": {
"summary": "Get a particular report",
"tags": [
"reports"
],
"parameters": [
{
"in": "path",
"name": "name",
"schema": {
"type": "string"
},
"required": true,
"description": "The name of a report."
}
],
"responses": {
"200": {
"description": "A report (CSV download)",
"examples": null,
"content": {
"text/csv": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "Could not find requested report {name}."
}
}
}
},
"406": {
"$ref": "#/components/responses/Unacceptable"
},
"500": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "Unable to render report file."
}
}
}
}
}
}
},
"/search": {
"get": {
"summary": "Search publicly-available datasets",
"tags": [
"root"
],
"description": "Search the published Dryad datasets by keyword, institutional affiliation, and date.",
"parameters": [
{
"$ref": "#/components/parameters/page"
},
{
"$ref": "#/components/parameters/per_page"
},
{
"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 terms that should *not* be present in the results (e.g., `cat -fish`)."
},
{
"in": "query",
"name": "affiliation",
"schema": {
"type": "string"
},
"description": "A ROR identifier specifying 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": "tenant",
"schema": {
"type": "string"
},
"description": "The abbreviation for a partner organization in Dryad. This will automatically search all affiliations associated with the given tenant. If both a *tenant* and *affiliation* are specified, the tenant will be ignored."
},
{
"in": "query",
"name": "journalISSN",
"schema": {
"type": "string"
},
"description": "The journal ISSN."
},
{
"in": "query",
"name": "modifiedSince",
"schema": {
"type": "string"
},
"description": "A timestamp for limiting results. Datasets will only be returned that have been modified since the given 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 timestamp for limiting results. Datasets will only be returned that have been modified before the given 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": "The identifier that is present in 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."
}
],
"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": {
"responses": {
"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`."
}
}
}
},
"BadRequest": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "400 - Bad Request"
}
}
}
},
"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."
}
}
}
},
"unauthorized": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "unauthorized"
}
}
}
},
"UnprocessableEntity": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "422 - Unprocessable Content: the server understood the content type of the request, and the syntax of the request content was correct, but it was unable to process the contained instructions.\n\nExample: _A dataset with same information already exists._"
}
}
}
}
},
"schemas": {
"root": {
"type": "object",
"properties": {
"_links": {
"$ref": "#/components/schemas/root_links"
}
},
"required": [
"_links"
]
},
"root_links": {
"type": "object",
"properties": {
"self": {
"$ref": "#/components/schemas/hal_link"
},
"stash:datasets": {
"$ref": "#/components/schemas/hal_link"
},
"reports": {
"$ref": "#/components/schemas/hal_link"
},
"curies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/hal_curie"
}
}
},
"required": [
"self"
]
},
"datasets": {
"allOf": [
{
"$ref": "#/components/schemas/hal_paged_response"
},
{
"$ref": "#/components/schemas/embedded_datasets"
}
]
},
"embedded_datasets": {
"type": "object",
"properties": {
"_embedded": {
"type": "object",
"properties": {
"stash:datasets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/dataset"
}
}
}
}
}
},
"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"
}
}
}
]
},
"dataset_links": {
"properties": {
"_links": {
"allOf": [
{
"$ref": "#/components/schemas/hal_self_link"
},
{
"$ref": "#/components/schemas/hal_dataset_links"
}
]
}
}
},
"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"
}
}
}
},
"dataset_submission": {
"properties": {
"op": {
"type": "string",
"enum": [
"replace"
],
"example": "replace"
},
"path": {
"type": "string",
"enum": [
"/versionStatus",
"/curationStatus",
"publicationISSN"
],
"example": "/versionStatus"
},
"value": {
"type": "string",
"oneOf": [
{
"title": "/versionStatus",
"enum": [
"submitted"
]
},
{
"title": "/curationStatus",
"enum": [
"in_progress'",
"submitted",
"processing",
"peer_review",
"curation",
"action_required",
"withdrawn",
"embargoed",
"published"
]
},
{
"title": "/publicationISSN"
}
],
"example": "submitted"
}
}
},
"versions": {
"allOf": [
{
"$ref": "#/components/schemas/hal_paged_response"
},
{
"$ref": "#/components/schemas/embedded_versions"
}
]
},
"embedded_versions": {
"type": "object",
"properties": {
"_embedded": {
"type": "object",
"properties": {
"stash:versions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/version"
}
}
}
}
}
},
"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",
"submitted",
"processing",
"peer_review",
"curation",
"action_required",
"withdrawn",
"embargoed",
"published"
],
"description": "Status 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."
}
}
}
]
},
"version_links": {
"properties": {
"_links": {
"allOf": [
{
"$ref": "#/components/schemas/hal_self_link"
},
{
"$ref": "#/components/schemas/hal_version_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"
}
}
}
},
"simple_version": {
"allOf": [
{
"$ref": "#/components/schemas/dc_metadata"
}
]
},
"files": {
"allOf": [
{
"$ref": "#/components/schemas/hal_paged_response"
},
{
"$ref": "#/components/schemas/embedded_files"
}
]
},
"embedded_files": {
"type": "object",
"properties": {
"_embedded": {
"type": "object",
"properties": {
"stash:files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/file"
}
}
}
}
}
},
"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"
}
}
}
]
},
"file_links": {
"properties": {
"_links": {
"allOf": [
{
"$ref": "#/components/schemas/hal_self_link"
},
{
"$ref": "#/components/schemas/hal_file_links"
}
]
}
}
},
"processor_result": {
"allOf": [
{
"properties": {
"id": {
"type": "integer",
"example": 27
},
"resource_id": {
"type": "integer",
"example": 48
},
"processing_type": {
"type": "string",
"enum": [
"excel_to_csv",
"compressed_info",
"frictionless"
],
"example": "excel_to_csv"
},
"parent_id": {
"type": "integer",
"example": 747
},
"completion_state": {
"type": "string",
"enum": [
"not_started",
"processing",
"success",
"error"
],
"example": "success"
},
"message": {
"type": "string",
"example": "Completed processing with no errors."
},
"structured_info": {
"type": "string",
"example": "{\"cat\": \"dog\"}"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
]
},
"processor_results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/processor_result"
}
},
"url": {
"properties": {
"url": {
"type": "string"
}
}
},
"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"
}
}
}
},
"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."
},
"locations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/geolocation"
}
},
"relatedWorks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/relatedWork"
}
}
},
"required": [
"title",
"authors",
"abstract"
]
},
"admin_values": {
"properties": {
"userId": {
"type": "string",
"description": "The Dryad user ID, or ORCID iD, of the user who will submit the dataset. If this is unknown, the userId must be set to `0` to allow for an invitation link."
},
"publicationISSN": {
"type": "string",
"description": "An ISSN for the associated journal"
},
"publicationName": {
"type": "string",
"description": "The title of the associated journal"
},
"manuscriptNumber": {
"type": "string",
"description": "The internal manuscript number assigned to an associated article before publication"
},
"skipEmails": {
"type": "boolean",
"default": false,
"description": "Administrator value. Prevents emails being sent automatically."
},
"triggerSubmitInvitation": {
"type": "boolean",
"default": false,
"description": "Administrator value. Sends an editing invitation email to the first author."
},
"preserveCurationStatus": {
"type": "boolean",
"default": false,
"description": "Administrator value. Prevents automatic curation status changes."
},
"holdForPeerReview": {
"type": "boolean",
"default": false,
"description": "Administrator value. Sets whether the submission will be sent to curation or a peer review hold status."
},
"loosenValidation": {
"type": "boolean",
"default": false,
"description": "For superusers only."
},
"skipDataciteUpdate": {
"type": "boolean",
"default": false,
"description": "For superusers only."
},
"invoiceId": {
"type": "string",
"description": "For superusers only."
}
}
},
"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"
}
}
},
"simple_author": {
"properties": {
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"email": {
"type": "string"
},
"affiliation": {
"type": "string"
}
}
},
"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"
}
}
},
"relatedWork": {
"properties": {
"relationship": {
"format": "string",
"enum": [
"article",
"dataset",
"preprint",
"software",
"supplemental_information",
"primary_article",
"data_management_plan"
]
},
"identifierType": {
"type": "string"
},
"identifier": {
"type": "string"
}
}
},
"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."
}
}
},
"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"
}
}
},
"geolocationPoint": {
"type": "object",
"properties": {
"latitude": {
"description": "The latitude of the point.",
"type": "number"
},
"longitude": {
"description": "The longitude of the point.",
"type": "number"
}
}
},
"embargo": {
"type": "object",
"properties": {
"embargoEndDate": {
"format": "date",
"description": "The end date of the embargo, after which the dataset will become public.",
"type": "string"
}
}
},
"tenant": {
"type": "object",
"description": "Information about the Dryad member associated with the dataset.",
"properties": {
"id": {
"format": "string"
},
"abbreviation": {
"format": "string"
},
"shortName": {
"format": "string"
},
"longName": {
"format": "string"
},
"domainName": {
"format": "string"
}
}
},
"related_type": {
"type": "object",
"properties": {
"work_type": {
"format": "string",
"enum": [
"article",
"dataset",
"preprint",
"software",
"supplemental_information",
"primary_article",
"data_management_plan"
],
"example": "article"
}
}
},
"reports": {
"properties": {
"_links": {
"type": "object",
"properties": {
"self": {
"$ref": "#/components/schemas/hal_link"
},
"reports": {
"type": "array",
"items": {
"$ref": "#/components/schemas/hal_link"
}
},
"curies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/hal_curie"
}
}
}
}
}
},
"hal_links": {
"properties": {
"self": {
"$ref": "#/components/schemas/hal_link"
},
"curies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/hal_curie"
}
}
},
"required": [
"self"
]
},
"hal_self_link": {
"type": "object",
"properties": {
"self": {
"$ref": "#/components/schemas/hal_link"
}
}
},
"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"
}
}
},
"paging_counts": {
"properties": {
"count": {
"type": "integer"
},
"total": {
"type": "integer"
}
}
},
"hal_link": {
"type": "object",
"properties": {
"href": {
"type": "string",
"format": "uri"
}
},
"required": [
"href"
]
},
"hal_curie": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"href": {
"type": "string",
"format": "uri"
},
"templated": {
"type": "boolean"
}
},
"required": [
"name",
"href",
"templated"
]
},
"hal_paged_response": {
"allOf": [
{
"properties": {
"_links": {
"allOf": [
{
"$ref": "#/components/schemas/hal_self_link"
},
{
"$ref": "#/components/schemas/hal_page_links"
}
]
}
}
},
{
"$ref": "#/components/schemas/paging_counts"
}
]
},
"url_json": {
"type": "object",
"properties": {
"url": {
"type": "string"
}
},
"required": [
"url"
]
},
"Error": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
}
}
},
"parameters": {
"doi": {
"in": "path",
"name": "doi",
"schema": {
"type": "string"
},
"required": true,
"description": "DOI like doi:10.1000/18238577 that should be URL encoded (example: doi%3A10.1000%2F18238577)"
},
"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."
},
"processor_result_id": {
"in": "path",
"name": "id",
"schema": {
"type": "integer"
},
"required": true,
"description": "The processor results ID for a single item."
},
"file_id": {
"in": "path",
"name": "id",
"schema": {
"type": "integer"
},
"required": true,
"description": "The file ID is a unique integer and can be obtained from the list of files for a version of a dataset."
},
"filename": {
"in": "path",
"name": "id",
"schema": {
"type": "string"
},
"required": true,
"description": "The filename is the filename for the file. It should be escaped in the URL (for example 'cat tundra.jpg' would be 'cat%20tundra.jpg'. Your programming language will have a library to encode for you."
},
"page": {
"in": "query",
"name": "page",
"schema": {
"type": "integer"
},
"description": "Which page of results to view. Defaults to page 1."
},
"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."
},
"publicationISSN": {
"in": "query",
"name": "publicationISSN",
"schema": {
"type": "string"
},
"description": "ISSN of a journal associated with the datasets."
},
"publicationName": {
"in": "query",
"name": "publicationName",
"schema": {
"type": "string"
},
"description": "ISSN of a journal associated with the datasets."
},
"manuscriptNumber": {
"in": "query",
"name": "manuscriptNumber",
"schema": {
"type": "string"
},
"description": "Manuscript number associated with the dataset."
},
"curationStatus": {
"in": "query",
"name": "curationStatus",
"schema": {
"type": "string"
},
"description": "Curation Status"
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
}
}