API Documentation for developers


Zenodo currently offers two different APIs:

  • REST API — includes support for uploading your research outputs.
  • OAI-PMH API — allows you to harvest all or parts of Zenodo via the OAI-PMH protocol.

REST API upload your research outputs


Introduction

The REST API allows you to programmatically upload and publish research outputs on Zenodo, with the same functionality which is available in our Upload user interface.

This short guide will give a quick overview of how to upload and publish on Zenodo, and will be using Python together with the Requests package.

  1. First, make sure you have the Requests module installed:

    $ pip install requests
  2. Next, fire up a Python command prompt:

    $ python
    Python 2.7.5+
    [GCC 4.8.1] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>>
  3. Import the requests and json modules (don't type the >>>-part):

    >>> import requests
    >>> import json
  4. Try to access the API:

    >>> r = requests.get("https://zenodo.org/api/deposit/depositions")
    >>> r.status_code
    401
    >>> r.json()
    {'message': "The server could not verify that you are authorized to access the URL requested.  You either supplied the wrong credentials (e.g. a bad password), or your browser doesn't understand how to supply the credentials required.",
     'status': 401}
    
  5. All API access requires an access token, so create one.
  6. Let's try again (replace ACCESS_TOKEN with your newly created personal access token):

    >>> r = requests.get("https://zenodo.org/api/deposit/depositions?access_token=ACCESS_TOKEN")
    >>> r.status_code
    200
    >>> r.json()
    []

    Note, if you already uploaded something, the output will be different.

  7. Next, let's create a new empty upload:

    >>> headers = {"Content-Type": "application/json"}
    >>> r = requests.post("https://zenodo.org/api/deposit/depositions?access_token=ACCESS_TOKEN", data="{}", headers=headers)
    >>> r.status_code
    201
    >>> r.json()
    {'created': '2016-06-15T16:10:03.319363+00:00',
     'files': [],
     'id': 1234,
     'links': {'discard': 'http://localhost:5000/api/deposit/depositions/1234/actions/discard',
      'edit': 'http://localhost:5000/api/deposit/depositions/1234/actions/edit',
      'files': 'http://localhost:5000/api/deposit/depositions/1234/files',
      'publish': 'http://localhost:5000/api/deposit/depositions/1234/actions/publish',
      'self': 'http://localhost:5000/api/deposit/depositions/1234'},
     'metadata': {'prereserve_doi': {'doi': '10.5072/zenodo.1234',
       'recid': 1234}},
     'modified': '2016-06-15T16:10:03.319371+00:00',
     'owner': 1,
     'record_id': 1234,
     'state': 'unsubmitted',
     'submitted': False,
     'title': ''}
    >>> deposition_id = r.json()['id']
    
  8. Now, let's upload a new file:

    >>> data = {'filename': 'myfirstfile.csv'}
    >>> files = {'file': open('/path/to/myfirstfile.csv', 'rb')}
    >>> r = requests.post("https://zenodo.org/api/deposit/depositions/%s/files?access_token=ACCESS_TOKEN" % deposition_id, data=data, files=files)
    >>> r.status_code
    201
    >>> r.json()
    {u'checksum': u'2b70e04bb31f2656ce967dc07103297f', u'filename': u'myfirstfile.csv', u'id': u'eb78d50b-ecd4-407a-9520-dfc7a9d1ab2c', u'filesize': u'27'}
    

    Maximum total record size is 50GB.

  9. Last thing missing, is just to add some metadata:

    >>> data = {"metadata": {"title": "My first upload", "upload_type": "poster", "description": "This is my first upload", "creators": [{"name": "Doe, John", "affiliation": "Zenodo"}]}}
    >>> r = requests.put("https://zenodo.org/api/deposit/depositions/%s?access_token=ACCESS_TOKEN" % deposition_id, data=json.dumps(data), headers=headers)
    >>> r.status_code
    200
    
  10. and, we're ready to publish:

    Don't execute this last step - it will put your test upload straight online.
    >>> r = requests.post("https://zenodo.org/api/deposit/depositions/%s/actions/publish?access_token=ACCESS_TOKEN" % deposition_id)
    >>> r.status_code
    202
    

Testing

We provide a sandbox environment where you can test your API integration during development. The sandbox environment is available at http://sandbox.zenodo.org.

Please note that the sandbox environment can be cleaned at anytime. Also, the sandbox environment will issue test DOIs using the 10.5072 prefix instead of Zenodo's normal prefix (10.5281).

Versioning

The REST API is versioned. We strive not to make backward incompatible changes to the API, but if we do, we release a new version. Changes to the API are documented on this page, and advance notification is given on our Twitter account.

Authentication

All API requests must be authenticated and over HTTPS. Any request over plain HTTP will fail. We support authentication with via OAuth 2.0.

Acquiring a personal access token

  1. Register for a Zenodo account if you don't already have one.
  2. Go to your Applications, to create a new token.
  3. Select the OAuth scopes you need (for the quick start tutorial you need deposit:write and deposit:actions).

Important! Do not share your personal access token with anyone else, and only use it over HTTPS.

Using access tokens

A access token must be included in all requests as a URL parameter:

https://zenodo.org/api/deposit/depositions?access_token=ACCESS_TOKEN

Scopes

Scopes assigns permissions to your access token to limit access to data and actions in Zenodo. The following scopes exists:
Name Description
deposit:write Grants write access to depositions, but does not allow publishing the upload.
deposit:actions Grants access to publish, edit and discard edits for depositions.

Requests

The base URL of the API is https://zenodo.org/api/.

All POST and PUT request bodies must be JSON encoded, and must have content type of application/json unless specified otherwise in the specific resource (e.g. in the case of file uploads). The API will return a 415 error (see HTTP status codes and error responses) if the wrong content type is provided.

Responses

All response bodies are JSON encoded (UTF-8 encoded). A single resource is represented as a JSON object:

{
    "field1": value,
    ...
}

A collection of resources is represented as a JSON array of objects:

[
    {
        "field1": value,
        ...
    },
    ...
]

Timestamps are in UTC and formatted according to ISO 8601:

YYYY-MM-DDTHH:MM:SS+00:00

HTTP status codes

We use the following HTTP status codes to indicate success or failure of a request.
Code Name Description
200 OK Request succeeded. Response included. Usually sent for GET/PUT/PATCH requests.
201 Created Request succeeded. Response included. Usually sent for POST requests.
202 Accepted Request succeeded. Response included. Usually sent for POST requests, where background processing is needed to fulfill the request.
204 No Content Request succeeded. No response included. Usually sent for DELETE requests.
400 Bad Request Request failed. Error response included.
401 Unauthorized Request failed, due to an invalid access token. Error response included.
403 Forbidden Request failed, due to missing authorization (e.g. deleting an already submitted upload or missing scopes for your access token). Error response included.
404 Not Found Request failed, due to the resource not being found. Error response included.
405 Method Not Allowed Request failed, due to unsupported HTTP method. Error response included.
409 Conflict Request failed, due to the current state of the resource (e.g. edit a deopsition which is not fully integrated). Error response included.
415 Unsupported Media Type Request failed, due to missing or invalid request header Content-Type. Error response included.
429 Too Many Requests Request failed, due to rate limiting. Error response included.
500 Internal Server Error Request failed, due to an internal server error. Error response NOT included. Don't worry, Zenodo admins have been notified and will be dealing with the problem ASAP.

Errors

Error responses for 400 series errors (e.g. 400, 401, 403, ...) are returned as a JSON object with two attributes message and status (HTTP status code), and possibly an attribute errors with a list of more detailed errors.

Example of a simple error message without further detailed errors:

{
    "message": "Deposition not found",
    "status": 404
}

Example of an error message with additional detailed error messages:

{
    "message": "Validation error",
    "status": 400,
    "errors": [
        {"code": 10, "message":"Not a valid choice", "field": "access_right"}
    ]
}

The attribute errors is a JSON array of objects, with the attributes message and code, and possibly field for validation errors.

Resources

Depositions

Description List all depositions for the currently authenticated user
URL https://zenodo.org/api/deposit/depositions
Method GET
Success response
  • Code: 200 OK
  • Body: an array of deposition resources.
Error response See HTTP status codes (400 and 500 series errors) and error responses.
Example
$ curl -i https://zenodo.org/api/deposit/depositions/?access_token=ACCESS_TOKEN
import requests
response = requests.get("https://zenodo.org/api/deposit/depositions/?access_token=ACCESS_TOKEN")
print response.json()
Description Create a new deposition resource.
URL https://zenodo.org/api/deposit/depositions
Method POST
Request headers Content-Type: application/json
Scopes deposit:write
Data parameters

An empty JSON object {} or a deposition metadata resource. Example:

{
    "metadata": {
        "upload_type": "presentation",
        ...
    }
}
Success response
Error response See HTTP status codes (400 and 500 series errors) and error responses.
Example
$ curl -i -H "Content-Type: application/json" --data '{}' https://zenodo.org/api/deposit/depositions/?access_token=ACCESS_TOKEN

or

$ curl -i -H "Content-Type: application/json" -X POST --data '{"metadata": {"title": "My first upload", "upload_type": "poster", "description": "This is my first upload", "creators": [{"name": "Doe, John", "affiliation": "Zenodo"}]}}' https://zenodo.org/api/deposit/depositions/?access_token=ACCESS_TOKEN
import json
import requests

url = "https://zenodo.org/api/deposit/depositions/?access_token=ACCESS_TOKEN"
headers = {"Content-Type": "application/json"}
r = requests.post(url, data="{}", headers=headers)

# or

data = {"metadata": {"title": "My first upload", "upload_type": "poster", "description": "This is my first upload", "creators": [{"name": "Doe, John", "affiliation": "Zenodo"}]}}
r = requests.post(url, data=json.dumps(data), headers=headers)
Description Retrieve a single deposition resource.
URL https://zenodo.org/api/deposit/depositions/:id
Method GET
URL parameters
  • Required:
    • id: Deposition identifier
Success response
Error response See HTTP status codes (400 and 500 series errors) and error responses.
Example
$ curl -i https://zenodo.org/api/deposit/depositions/1234?access_token=ACCESS_TOKEN
import requests

r = requests.get("https://zenodo.org/api/deposit/depositions/1234?access_token=ACCESS_TOKEN")
Description Update an existing deposition resource.
URL https://zenodo.org/api/deposit/depositions/:id
Method PUT
Request headers Content-Type: application/json
Scopes deposit:write
URL parameters
  • Required:
    • id: Deposition identifier
Data parameters

A deposition metadata resource. Example:

{
    "metadata": {
        "upload_type": "presentation",
        ...
    }
}
Success response
Error response See HTTP status codes (400 and 500 series errors) and error responses.
Example
$ curl -i -H "Content-Type: application/json" -X PUT --data '{"metadata": {"title": "My first upload", "upload_type": "poster", "description": "This is my first upload", "creators": [{"name": "Doe, John", "affiliation": "Zenodo"}]}}' https://zenodo.org/api/deposit/depositions/1234?access_token=ACCESS_TOKEN
import json
import requests

url = "https://zenodo.org/api/deposit/depositions/1234?access_token=ACCESS_TOKEN"
headers = {"Content-Type": "application/json"}
data = {"metadata": {"title": "My first upload", "upload_type": "poster", "description": "This is my first upload", "creators": [{"name": "Doe, John", "affiliation": "Zenodo"}]}}

r = requests.put(url, data=json.dumps(data), headers=headers)
}
Description Delete an existing deposition resource. Note, only unpublished depositions may be deleted.
URL https://zenodo.org/api/deposit/depositions/:id
Method DELETE
Scopes deposit:write
URL parameters
  • Required:
    • id: Deposition identifier
Success response
  • Code: 204 No Content
  • Body: Empty.
Error response
  • 404 Not found: Deposition does not exist.
  • 403 Forbidden: Deleting an already published deposition.

See also HTTP status codes (400 and 500 series errors) and error responses.

Example
$ curl -i -X DELETE https://zenodo.org/api/deposit/depositions/1234?access_token=ACCESS_TOKEN
import requests

r = requests.delete("https://zenodo.org/api/deposit/depositions/1234?access_token=ACCESS_TOKEN")

Deposition files

Description List all deposition files for a given deposition.
URL https://zenodo.org/api/deposit/depositions/:id/files
Method GET
URL parameters
  • Required:
    • id: Deposition identifier
Success response
Error response See HTTP status codes (400 and 500 series errors) and error responses.
Example
$ curl -i https://zenodo.org/api/deposit/depositions/1234/files?access_token=ACCESS_TOKEN
import requests

r = requests.get("https://zenodo.org/api/deposit/depositions/1234/files?access_token=ACCESS_TOKEN")
Description Upload a new file.
URL https://zenodo.org/api/deposit/depositions/:id/files
Method POST
Request headers Content-Type: multipart/form-data
Scopes deposit:write
URL parameters
  • Required:
    • id: Deposition identifier
Data parameters
Success response
Error response See HTTP status codes (400 and 500 series errors) and error responses.
Example
$ curl -i -F name=myfirstfile.csv -F file=@path/to/local_file.csv https://zenodo.org/api/deposit/depositions/1234/files?access_token=ACCESS_TOKEN
import json
import requests

url = "https://zenodo.org/api/deposit/depositions/1234/files?access_token=ACCESS_TOKEN"
data = {'filename': 'myfirstfile.csv'}
files = {'file': open('path/to/local_file.csv', 'rb')}
r = requests.post(url, data=data, files=files)
Description Sort the files for a deposition. By default, the first file is shown in the file preview.
URL https://zenodo.org/api/deposit/depositions/:id/files
Method PUT
Request headers Content-Type: application/json
Scopes deposit:write
URL parameters
  • Required:
    • id: Deposition identifier
Data parameters

A JSON array of partial deposition file resources with only the id attribute. Example:

[
    {"id": "<file id 1>"},
    {"id": "<file id 2>"},
    ...
]
Success response
Error response See HTTP status codes (400 and 500 series errors) and error responses.
Example
$ curl -i -X PUT -H "Content-Type: application/json" --data '[{"id":"21fedcba-9876-5432-1fed-cba987654321"}, {"id":"12345678-9abc-def1-2345-6789abcdef12"}]' https://zenodo.org/api/deposit/depositions/1234/files?access_token=ACCESS_TOKEN
import json
import requests

url = "https://zenodo.org/api/deposit/depositions/1234/files?access_token=ACCESS_TOKEN"
headers = {"Content-Type": "application/json"}
data = [{'id': '21fedcba-9876-5432-1fed-cba987654321'}, {'id': '12345678-9abc-def1-2345-6789abcdef12'}]

r = requests.put(url, data=json.dumps(data), headers=headers)
Description Retrieve a single deposition file.
URL https://zenodo.org/api/deposit/depositions/:id/files/:file_id
Method GET
URL parameters
  • Required:
    • id: Deposition identifier
    • file_id: Deposition file identifier
Success response
Error response See HTTP status codes (400 and 500 series errors) and error responses.
Example
$ curl -i https://zenodo.org/api/deposit/depositions/1234/files/12345678-9abc-def1-2345-6789abcdef12?access_token=ACCESS_TOKEN
import requests

r = requests.get("https://zenodo.org/api/deposit/depositions/1234/files/12345678-9abc-def1-2345-6789abcdef12?access_token=ACCESS_TOKEN")
Description Update a deposition file resource. Currently the only use is renaming an already uploaded file. If you one to replace the actual file, please delete the file and upload a new file.
URL https://zenodo.org/api/deposit/depositions/:id/files/:file_id
Method PUT
Request headers Content-Type: application/json
Scopes deposit:write
URL parameters
  • Required:
    • id: Deposition identifier
    • file_id: Deposition file identifier
Data parameters

A partial deposition file resources with only the filename attributes. Example:

{
    "filename": "<new name>"
}
Success response
Error response See HTTP status codes (400 and 500 series errors) and error responses.
Example
$ curl -i -X PUT -H "Content-Type: application/json" --data '{"filename": "someothername.csv"}' https://zenodo.org/api/deposit/depositions/1234/files/21fedcba-9876-5432-1fed-cba987654321?access_token=ACCESS_TOKEN
import json
import requests

url = "https://zenodo.org/api/deposit/depositions/1234/files/21fedcba-9876-5432-1fed-cba987654321?access_token=ACCESS_TOKEN"
headers = {"Content-Type": "application/json"}
data = {"filename": "someothername.csv"}

r = requests.put(url, data=json.dumps(data), headers=headers)
Description Delete an existing deposition file resource. Note, only deposition files for unpublished depositions may be deleted.
URL https://zenodo.org/api/deposit/depositions/:id/files/:file_id
Method DELETE
Scopes deposit:write
URL parameters
  • Required:
    • id: Deposition identifier
    • file_id: Deposition file identifier
Success response
  • Code: 204 No Content
  • Body: Empty.
Error response
  • 404 Not found: Deposition file does not exist.
  • 403 Forbidden: Deleting an already published deposition.

See also HTTP status codes (400 and 500 series errors) and error responses.

Example
$ curl -i -X DELETE https://zenodo.org/api/deposit/depositions/1234/files/21fedcba-9876-5432-1fed-cba987654321?access_token=ACCESS_TOKEN
import requests

r = requests.delete("https://zenodo.org/api/deposit/depositions/1234/files/21fedcba-9876-5432-1fed-cba987654321?access_token=ACCESS_TOKEN")

Deposition actions

Description Publish a deposition. Note, once a deposition is published, you can no longer delete it.
URL https://zenodo.org/api/deposit/depositions/:id/actions/publish
Method POST
Request headers None
Scopes deposit:actions
URL parameters
  • Required:
    • id: Deposition identifier
Success response
Error response See HTTP status codes (400 and 500 series errors) and error responses.
Example
$ curl -i -X POST https://zenodo.org/api/deposit/depositions/1234/actions/publish?access_token=ACCESS_TOKEN
import requests

r = requests.post("https://zenodo.org/api/deposit/depositions/1234/actions/publish?access_token=ACCESS_TOKEN")
Description Unlock already submitted deposition for editing.
URL https://zenodo.org/api/deposit/depositions/:id/actions/edit
Method POST
Request headers None
Scopes deposit:actions
URL parameters
  • Required:
    • id: Deposition identifier
Success response
Error response
  • 400 Bad Request: Deposition state does not allow for editing (e.g. depositions in state inprogress).
  • 409 Conflict: Deposition is in the process of being integrated, please wait 5 minutes before trying again.
See HTTP status codes (400 and 500 series errors) and error responses.
Example
$ curl -i -X POST https://zenodo.org/api/deposit/depositions/1234/actions/edit?access_token=ACCESS_TOKEN
import requests

r = requests.post("https://zenodo.org/api/deposit/depositions/1234/actions/edit?access_token=ACCESS_TOKEN")
Description Discard changes in the current editing session.
URL https://zenodo.org/api/deposit/depositions/:id/actions/discard
Method POST
Request headers None
Scopes deposit:actions
URL parameters
  • Required:
    • id: Deposition identifier
Success response
Error response
  • 400 Bad Request: Deposition is not being edited.
See HTTP status codes (400 and 500 series errors) and error responses.
Example
$ curl -i -X POST https://zenodo.org/api/deposit/depositions/1234/actions/discard?access_token=ACCESS_TOKEN
import requests

r = requests.post("https://zenodo.org/api/deposit/depositions/1234/actions/discard?access_token=ACCESS_TOKEN")

Representations

The following section documents all the object attributes for the above documented resources.

Attribute Type Editable Description
created Timestamp No Creation time of deposition (in ISO8601 format).
doi String No Digital Object Identifier (DOI). When you publish your deposition, we register a DOI in DataCite for your upload, unless you manually provided us with one. This field is only present for published depositions.
doi_url URL No Persistent link to your published deposition. This field is only present for published depositions.
files Array Yes A list of deposition files resources.
id Integer No Deposition identifier
metadata Object Yes A deposition metadata resource
modified Timestamp No Last modification time of deposition (in ISO8601 format).
owner Integer No User identifier of the owner of the deposition.
record_id Integer No Record identifier. This field is only present for published depositions.
record_url URL No URL to public version of record for this deposition. This field is only present for published depositions.
state String No One of the values:
  • "inprogress": Deposition metadata can be updated. If deposition is also unsubmitted (see submitted) files can be updated as well.
  • "done": Deposition has been published.
  • "error": Deposition is in an error state - contact our support.
  • submitted Bool No True of deposition has been published, False otherwise.
    title String No Title of deposition (automatically set from metadata). Defaults to empty string.
    Attribute Type Required Description
    upload_type String Yes Controlled vocabulary:
    • publication: Publication
    • poster: Poster
    • presentation: Presentation
    • dataset: Dataset
    • image: Image
    • video: Video/Audio
    • software: Software
    publication_type String Yes, if upload_type is "publication". Controlled vocabulary:
    • book: Book
    • section: Book section
    • conferencepaper: Conference paper
    • article: Journal article
    • patent: Patent
    • preprint: Preprint
    • report: Report
    • softwaredocumentation: Software documentation
    • thesis: Thesis
    • technicalnote: Technical note
    • workingpaper: Working paper
    • other: Other
    image_type String Yes, if upload_type is "image". Controlled vocabulary:
    • figure: Figure
    • plot: Plot
    • drawing: Drawing
    • diagram: Diagram
    • photo: Photo
    • other: Other
    publication_date String Yes Date of publication in ISO8601 format (YYYY-MM-DD). Defaults to current date.
    title String Yes Title of deposition.
    creators Array of objects Yes

    The creators/authors of the deposition. Each array element is an object with the attributes:

    • name: Name of creator in the format Family name, Given names
    • affiliation: Affiliation of creator (optional).
    • orcid: ORCID identifier of creator (optional).
    • gnd: GND identifier of creator (optional).

    Example:

    [{'name':'Doe, John', 'affiliation': 'Zenodo'},
    {'name':'Smith, Jane', 'affiliation': 'Zenodo', 'orcid': '0000-0002-1694-233X'},
    {'name': 'Kowalski, Jack', 'affiliation': 'Zenodo', 'gnd': '170118215'}]
    description String Yes Abstract or description for deposition. Following HTML tags are allowed: a, p, br, blockquote, strong, b, u, i, em, ul, ol, li, sub, sup, div, strike.
    access_right String Yes Controlled vocabulary:
    • open: Open Access
    • embargoed: Embargoed Access
    • restricted: Restricted Access
    • closed: Closed Access
    Defaults to open.
    license String Yes, if access_right is "open" or "embargoed".

    Controlled vocabulary (see vocabulary here). The selected license applies to all files in this deposition, but not to the metadata which is licensed under Creative Commons Zero. Further information about licenses is available at Open Definition Licenses Service.

    Defaults to cc-by for non-datasets and cc-zero for datasets.

    embargo_date Yes, if access_right is "embargoed". Date in ISO8601 format (YYYY-MM-DD) when the deposited files will be made automatically made publicly available by the system. Defaults to current date.
    access_conditions String Yes, if access_right is "restricted". Specify the conditions under which you grant users access to the files in your upload. User requesting access will be asked to justify how they fulfil the conditions. Based on the justification, you decide who to grant/deny access. You are not allowed to charge users for granting access to data hosted on Zenodo. Following HTML tags are allowed: a, p, br, blockquote, strong, b, u, i, em, ul, ol, li, sub, sup, div, strike.
    doi String No Digital Object Identifier. Did a publisher already assign a DOI to your deposited files? If not, leave the field empty and we will register a new DOI for you when you publish. A DOI allow others to easily and unambiguously cite your deposition.
    prereserve_doi Object/Bool No Set to true, to reserve a Digital Object Identifier (DOI). The DOI is automatically generated by our system and cannot be changed. Also, The DOI is not registered with DataCite until you publish your deposition, and thus cannot be used before then. Reserving a DOI is useful, if you need to include it in the files you upload, or if you need to provide a dataset DOI to your publisher but not yet publish your dataset. The response from the REST API will include the reserved DOI.
    keywords Array of strings No

    Free form keywords for this deposition. Example:

    ["Keyword 1", "Keyword 2"]
    notes String No Additional notes. No HTML allowed.
    related_identifiers Array of objects No

    Persistent identifiers of related publications and datasets. Supported identifiers include: DOI, Handle, ARK, PURL, ISSN, ISBN, PubMed ID, PubMed Central ID, ADS Bibliographic Code, arXiv, Life Science Identifiers (LSID), EAN-13, ISTC, URNs and URLs. Each array element is an object with the attributes:

    • identifier: The persistent identifier
    • relation: Relationship. Controlled vocabulary (isCitedBy, cites, isSupplementTo, isSupplementedBy, isNewVersionOf, isPreviousVersionOf, isPartOf, hasPart, compiles, isCompiledBy, isIdenticalTo, isAlternateIdentifier).

    Example:

    [
      {'relation': 'isSupplementTo', 'identifier':'10.1234/foo'},
      {'relation': 'cites', 'identifier':'https://doi.org/10.1234/bar'}
    ]

    Note the identifier type (e.g. DOI) is automatically detected, and used to validate and normalize the identifier into a standard form.

    contributors Array of objects No

    The contributors of the deposition (e.g. editors, data curators, etc.). Each array element is an object with the attributes:

    • name: Name of creator in the format Family name, Given names
    • type: Contributor type. Controlled vocabulary (ContactPerson,DataCollector,DataCurator,DataManager,Editor,Researcher,RightsHolder,Sponsor,Other).
    • affiliation: Affiliation of creator (optional).
    • orcid: ORCID identifier of creator (optional).
    • gnd: GND identifier of creator (optional).

    Example:

    [{'name':'Doe, John', 'affiliation': 'Zenodo', 'type': 'Editor' }, ...]
    references Array of strings No

    List of references.

    Example:

    [
        "Doe J (2014). Title. Publisher. DOI",
        "Smith J (2014). Title. Publisher. DOI"
    ]
    communities Array of objects No

    List of communities you wish the deposition to appear. The owner of the community will be notified, and can either accept or reject your request. Each array element is an object with the attributes:

    • identifier: Community identifier

    Example:

    [{'identifier':'ecfunded'}]
    grants Array of objects No

    List of European Commission FP7 grants which have funded the research for this deposition. Each array element is an object with the attributes:

    • id: FP7 grant number.

    Example:

    [{'id':'283595'}]
    journal_title String No Journal title, if deposition is a published article.
    journal_volume String No Journal volume, if deposition is a published article.
    journal_issue String No Journal issue, if deposition is a published article.
    journal_pages String No Journal pages, if deposition is a published article.
    conference_title String No Title of conference (e.g. 20th International Conference on Computing in High Energy and Nuclear Physics).
    conference_acronym String No Acronym of conference (e.g. CHEP'13).
    conference_dates String No Dates of conference (e.g. 14-18 October 2013). Conference title or acronym must also be specified if this field is specified.
    conference_place String No Place of conference in the format city, country (e.g. Amsterdam, The Netherlands). Conference title or acronym must also be specified if this field is specified.
    conference_url String No URL of conference (e.g. http://www.chep2013.org/).
    conference_session String No Number of session within the conference (e.g. VI).
    conference_session_part String No Number of part within a session (e.g. 1).
    imprint_publisher String No Publisher of a book/report/chapter
    imprint_isbn String No ISBN of a book/report
    imprint_place String No Place of publication of a book/report/chapter in the format city, country.
    partof_title String No Title of book for chapters
    partof_pages String No Pages numbers of book
    thesis_supervisors Array of objects No Supervisors of the thesis. Same format as for creators.
    thesis_university String No Awarding university of thesis.
    subjects Array of objects No

    Specify subjects from a taxonomy or controlled vocabulary. Each term must be uniquely identified (e.g. a URL). For free form text, use the keywords field. Each array element is an object with the attributes:

    • term: Term from taxonomy or controlled vocabulary.
    • identifier: Unique identifier for term.
    • scheme: Persistent identifier scheme for id (automatically detected).
    Example:
    [{"term": "Astronomy",
     "identifier": "http://id.loc.gov/authorities/subjects/sh85009003",
     "scheme": "url"}]

    Attribute Type Editable Description
    id String No Deposition file identifier
    filename String Yes Name of file
    filesize Integer No Size of files in bytes
    checksum String No MD5 checksum of file, computed by our system. This allows you to check the integrity of the uploaded file.

    Changes

    2015-10-06

    Added new optional field contributors to deposition metadata.

    Added new optional field subjects to deposition metadata.

    Added new optional subfield gnd to creators in deposition metadata.

    2014-12-20

    Added new relationship isAlternateIdentifier in subfield relation to related_identifiers in deposition metadata.

    2014-12-10

    Added new relationships hasPart, isPartOf & isIdenticalTo in subfield relation to related_identifiers in deposition metadata.

    2014-11-20

    Added new optional subfield orcid to creators in deposition metadata.

    2014-10-21

    Added new optional fields conference_session and conference_session_part to deposition metadata.

    2014-09-09

    Added new optional field references to deposition metadata.

    2014-06-13

    Authentication changed from API keys to OAuth 2.0. API key authentication is deprecated and will be phased out in October, 2014. Please use personal access tokens instead of API keys.

    2013-12-18

    REST API version 1.0 final release

    • Deposition actions moved from deposit/depositions/:id/action to deposit/depositions/:id/actions
    • Added edit and discard deposition action resources.
    • Deposition resource representation:
      • state: Controlled vocabulary changed.
      • submitted: Data type changed from Timestamp to Bool.
      2013-11-13

      REST API initial release candidate

      OAI-PMH API use OAI-PMH to harvest Zenodo


      Zenodo allows you to harvest our entire repository via the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH). OAI-PMH is a widely used protocol for harvesting metadata and most popular repository software provide support for this protocol.

      All metadata is licensed under Creative Commons Zero, while the data files may be either open access and subject to a license described in the metadata or closed access and not available for download.

      Base URL

      https://zenodo.org/oai2d
      

      Metadata formats

      Metadata for each record is available in several formats. The available formats include:
      oai_datacite3

      OAI DataCite — This metadata format has been specifically established for the dissemination of DataCite records using OAI-PMH. In addition to the original DataCite v3.0 metadata, this format contains several other elements describing the version of the metadata, whether it is of reference quality, and the registering datacentre. For more information about this format and its schema please see the DataCite OAI schema web site.

      Recommended We recommend you harvest using this metadata format. The format contains the most complete metadata and is our primary supported format.

      See example

      oai_datacite

      OAI DataCite — This metadata format has been specifically established for the dissemination of DataCite records using OAI-PMH. In addition to the original DataCite metadata, this format contains several other elements describing the version of the metadata, whether it is of reference quality, and the registering datacentre. For more information about this format and its schema please see the DataCite OAI schema web site.

      See example

      datacite3

      DataCite v3.0 — This metadata format contains only the original DataCite metadata without additions or alterations. The schema for this format does not exist and metadata will not validate against it. Please note that this format is not OAI-PMH version 2.0 compliant.

      See example

      datacite

      DataCite v2.2 — This metadata format contains only the original DataCite metadata without additions or alterations. The schema for this format does not exist and metadata will not validate against it. Please note that this format is not OAI-PMH version 2.0 compliant.

      Heads up! We will be upgrading to DataCite Metadata Schema v3.0 and discontinue support for DataCite v2.2, hence please ensure your OAI-PMH client are capable of reading both versions. There are only few backwards incompatible changes between v3.0 and v2.2.

      See example

      oai_dc

      Dublin Core — only minimal metadata is included in this format, and is primarily provided for clients which does not support oai_datacite.

      See example

      Sets

      We support both harvesting of the entire repository as well as selective harvesting of communities.

      user-zenodo

      All of Zenodo

      See example

      user-<identifier>

      Community sets — allows selective harvesting of specific communities. Replace <identifier> with the community identifier. Alternatively each community provides a direct harvesting API link on their front-page, which includes the correct community identifier.

      See example

      If you need selective harvesting and your use case is not supported by above sets, please contact us and we may possible set a specific set for you.

      Update schedule

      Sets are updated once an hour.

      Rate limit

      The OAI-PMH API is rated limited to one request per 2 seconds. We would be grateful if you notify us that you are harvesting us and in which context. It allows us to take your use case into consideration for future developments.

      Changes

      2014-03-10

      Added metadata formats datacite3 and oai_datacite3 to support DataCite v3.0.

      2013-05-08

      Initial release of OAI-PMH API