REST API

Introduction

The Zenodo REST API currently supports:

• Deposit — upload and publishing of research outputs (identical tofunctionality available in the user interface).
• Records — search published records.
• Files — download/upload of files.

Check out theQuickstart guide for an example on how toprogrammatically upload and publish your research outputs.

The following REST APIs are currently in testing before we launch them inbeta with full documentation:

• Communities - search communities.
• Funders — search for funders.
• Grants — search for grants.
• Licenses — search for licenses.

You can have a sneak peek at the APIs in test from our root endpoint:https://zenodo.org/api/

Quickstart - Upload

This short guide will give a quick overview of how to upload and publish onZenodo, and will be using either:

1. Python together with theRequests package.
2. Javascript together with theaxios package.

#Install 'requests' module for pythonpip install requests#Install 'axios' module for nodejsnpm install axios

• First, make sure you have theRequests moduleinstalled for python oraxios for nodeJS:

python# Python 3.6.5# [GCC 4.8.1] on linux2# Type "help", "copyright", "credits" or "license" for more information.

node// Welcome to Node.js v14.19.0.// Type ".help" for more information.

• Next, fire up a command prompt:

importrequests

constaxios=require('axios');

• Import the module to handle requests:

importrequestsr=requests.get("https://zenodo.org/api/deposit/depositions")r.status_code# 401r.json()

constaxios=require('axios');axios.get("https://zenodo.org/api/deposit/depositions").then(response=>{console.log(response);}).catch(error=>{console.log(error.response.data);});

{"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}

• We will try to access the API without an authentication token:

• All API access requires an access token, socreate one.

ACCESS_TOKEN='ChangeMe'r=requests.get('https://zenodo.org/api/deposit/depositions',params={'access_token':ACCESS_TOKEN})r.status_code# 200r.json()# []

constACCESS_TOKEN='ChangeMe'constrequestParams={params:{'access_token':ACCESS_TOKEN}}axios.get("https://zenodo.org/api/deposit/depositions",requestParams).then(response=>{console.log(response.status);// > 200console.log(response.data);// > []}).catch(error=>{console.log(error.response.data);});

• Let’s try again (replaceACCESS_TOKEN with your newly created personalaccess token):

headers={"Content-Type":"application/json"}params={'access_token':ACCESS_TOKEN}r=requests.post('https://sandbox.zenodo.org/api/deposit/depositions',params=params,json={},'''                   Headers are not necessary here since "requests" automatically                   adds "Content-Type: application/json", because we're using                   the "json=" keyword argument                   headers=headers,                    '''headers=headers)r.status_code# 201r.json()

constrequestParams={params:{'access_token':ACCESS_TOKEN},headers:{"Content-Type":"application/json"}}axios.post("https://zenodo.org/api/deposit/depositions",requestParams).then(response=>{console.log(response.status);// 201console.log(response.data);}).catch(error=>{console.log(error.response.data);});

{"conceptrecid":"542200","created":"2020-05-19T11:58:41.606998+00:00","files":[],"id":542201,"links":{"bucket":"https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b","discard":"https://zenodo.org/api/deposit/depositions/542201/actions/discard","edit":"https://zenodo.org/api/deposit/depositions/542201/actions/edit","files":"https://zenodo.org/api/deposit/depositions/542201/files","html":"https://zenodo.org/deposit/542201","latest_draft":"https://zenodo.org/api/deposit/depositions/542201","latest_draft_html":"https://zenodo.org/deposit/542201","publish":"https://zenodo.org/api/deposit/depositions/542201/actions/publish","self":"https://zenodo.org/api/deposit/depositions/542201"},"metadata":{"prereserve_doi":{"doi":"10.5072/zenodo.542201","recid":542201}},"modified":"2020-05-19T11:58:41.607012+00:00","owner":12345,"record_id":542201,"state":"unsubmitted","submitted":false,"title":""}

bucket_url=r.json()["links"]["bucket"]

curl https://zenodo.org/api/deposit/depositions/222761?access_token=$ACCESS_TOKEN{ ..."links":{"bucket":"https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b",    ...,},...}

''' This will stream the file located in '/path/to/your/file.dat' and store it in our bucket.The uploaded file will be named according to the last argument in the upload URL,'file.dat' in our case. '''$curl --upload-file /path/to/your/file.dat https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b/file.dat?access_token=$ACCES_TOKEN{ ...}

''' New API '''filename="my-file.zip"path="/path/to/%s"%filename''' The target URL is a combination of the bucket link with the desired filenameseperated by a slash.'''withopen(path,"rb")asfp:r=requests.put("%s/%s"%(bucket_url,filename),data=fp,params=params,)r.json()

constfs=require('fs');constaxios=require('axios');constfilePath='<FILE_PATH>';// Replace with file pathconstbucketURL='<BUCKET_URL>';// Replace with bucket urlconstfileName='<FILE_NAME>';// Replace with file nameconsttoken='TOKEN';// Replace with token value// Create a formconstform=newFormData();// Read file as a streamconststream=fs.createReadStream(filePath);form.append('file',stream);// Create requestleturl=`${bucketURL}/${fileName}`;letparams={'access_token':token}letheaders={'Content-type':'application/zip'}constrequestConfig={data:{name:fileName,...form},headers:headers,params:params}axios.put(url,requestConfig).then(response=>{console.log(response.data);}).catch(error=>{console.log(error.response.data);});

{"key":"my-file.zip","mimetype":"application/zip","checksum":"md5:2942bfabb3d05332b66eb128e0842cff","version_id":"38a724d3-40f1-4b27-b236-ed2e43200f85","size":13264,"created":"2020-02-26T14:20:53.805734+00:00","updated":"2020-02-26T14:20:53.811817+00:00","links":{"self":"https://zenodo.org/api/files/44cc40bc-50fd-4107-b347-00838c79f4c1/dummy_example.pdf","version":"https://zenodo.org/api/files/44cc40bc-50fd-4107-b347-00838c79f4c1/dummy_example.pdf?versionId=38a724d3-40f1-4b27-b236-ed2e43200f85","uploads":"https://zenodo.org/api/files/44cc40bc-50fd-4107-b347-00838c79f4c1/dummy_example.pdf?uploads"},"is_head":true,"delete_marker":false}

'''Old APIGet the deposition id from the previous response'''deposition_id=r.json()['id']data={'name':'myfirstfile.csv'}files={'file':open('/path/to/myfirstfile.csv','rb')}r=requests.post('https://zenodo.org/api/deposit/depositions/%s/files'%deposition_id,params={'access_token':ACCESS_TOKEN},data=data,files=files)r.status_code# 201r.json()

// Old API documentation not available for javascript / NodeJS

{"checksum":"2b70e04bb31f2656ce967dc07103297f","name":"myfirstfile.csv","id":"eb78d50b-ecd4-407a-9520-dfc7a9d1ab2c","filesize":"27"}

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'%deposition_id,params={'access_token':ACCESS_TOKEN},data=json.dumps(data),headers=headers)r.status_code# 200

// Old API documentation not available for javascript / NodeJS

r=requests.post('https://zenodo.org/api/deposit/depositions/%s/actions/publish'%deposition_id,params={'access_token':ACCESS_TOKEN})r.status_code# 202

// Old API documentation not available for javascript / NodeJS

We provide a sandbox environment where you can test your API integrationduring development. The sandbox environment is available athttps://sandbox.zenodo.org.

Please note the following:

• The sandbox environment can becleaned at anytime.
• The sandbox environment requires a separate registration and separate access token from the ones used onhttps://zenodo.org.
• The sandbox environment will issue test DOIs using the 10.5072 prefixinstead of Zenodo’s normal prefix (10.5281).

Versioning

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

Authentication

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

Creating a personal access token

1. Register for a Zenodo account if you don’talready have one.
2. Go to yourApplications,tocreate a new token.
3. Select the OAuth scopes you need (for the quick start tutorial you needdeposit:write anddeposit:actions).

GET /api/deposit/depositions?access_token=<ACCESS_TOKEN>

GET /api/deposit/depositionsAuthorization: Bearer <ACCESS_TOKEN>

AllPOST andPUT request bodies must be JSON encoded, and must have contenttype ofapplication/json unless specified otherwise in the specific resource(e.g. in the case of file uploads). The API will return a415 error (seeHTTPstatus codes anderror responses) if the wrongcontent type is provided.

Responses

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

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

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

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

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

Timestamps are in UTC and formatted according toISO8601:

HTTP status codes

We use the following HTTP status codes to indicate success or failure of arequest.

Errors

Error responses for 400 series errors (e.g. 400, 401, 403, …) are returned asa JSON object with two attributesmessage andstatus (HTTP status code), andpossibly an attributeerrors with a list of more detailed errors.

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

For more complex errors, we include the attributeerrors, a JSON array ofobjects, each with the attributesmessage (with a human-readable explanationof the error), and possiblyfield (with the “path” to field that containsthe error).

Example of an error message with detailed errors:

{"message":"Validation error","status":400,"errors":[{"field":"metadata.access_right","message":"Not a valid choice"},{"field":"metadata.creators.0.name","message":"Name is required."},{"field":"non_existent","message":"Unknown field name."}]}

Entities

Depositions

Representation

The Deposition resource is used for uploading and editing records on Zenodo.

Deposit

Deposit metadata

importrequestsresponse=requests.get('/api/deposit/depositions',params={'q':'my title','access_token':ACCESS_TOKEN})print(response.json())

curl -i /api/deposit/depositions/?access_token=ACCESS_TOKEN

• Code:200 OK
• Body: an array ofdeposition resources.

Error Response

SeeHTTP status codes (400 and 500 series errors) anderror responses.

Create

Create a new deposition resource.

curl -i -H"Content-Type: application/json" -X POST     --data'{}' /api/deposit/depositions/?access_token=ACCESS_TOKEN# orcurl -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"}]}}' /api/deposit/depositions/?access_token=ACCESS_TOKEN

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

HTTP Request

POST /api/deposit/depositions

Request headers

Content-Type: application/json

Data

An empty JSON object{} or adeposition metadataresource. Example:{"metadata": {"upload_type": "presentation" } }

Scopes

deposit:write

Success Response

• Code:201 Created
• Body: adeposition resource.

Error Response

SeeHTTP status codes (400 and 500 series errors) anderror responses.

Retrieve

Retrieve a single deposition resource.

curl -i /api/deposit/depositions/1234?access_token=ACCESS_TOKEN

importrequestsr=requests.get("/api/deposit/depositions/1234?access_token=ACCESS_TOKEN")

HTTP Request

GET /api/deposit/depositions/:id

Success response

• Code:200 OK
• Body: adeposition resource.

Error response

SeeHTTP status codes (400 and 500 series errors) anderror responses. |

Update

Update an existing deposition resource.

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

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

HTTP Request

PUT /api/deposit/depositions/:id

Request headers

Content-Type: application/json

Scopes

deposit:write

{"metadata":{"upload_type":"presentation","...":"..."}}

Data parameters

Adeposition metadata resource.

Success response

• Code:200 OK
• Body: adeposition resource.

Error response

SeeHTTP status codes (400 and 500 series errors) anderror responses.

Delete

Delete an existing deposition resource. Note, only unpublished depositions maybe deleted.

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

importrequestsr=requests.delete('https://zenodo.org/api/deposit/depositions/1234',params={'access_token':ACCESS_TOKEN})

HTTP Request

DELETE /api/deposit/depositions/:id

Scopes

deposit:write

Success Response

• Code:201 Created
• Body: Empty.

Error Response

• 404 Not found: Deposition does not exist.
• 403 Forbidden: Deleting an already published deposition.

See alsoHTTP status codes (400 and 500 series errors) anderror responses.

Deposition files

curl -i https://zenodo.org/api/deposit/depositions/1234/files?access_token=ACCESS_TOKEN

importrequestsr=requests.get('https://zenodo.org/api/deposit/depositions/1234/files',params={'access_token':ACCESS_TOKEN})

• Code:200 OK
• Body: an array ofdeposition file resources.

Error response

SeeHTTP status codes (400 and 500 series errors) anderror responses.

Create

Upload a new file.

curl -i https://zenodo.org/api/deposit/depositions/1234/files?access_token=ACCESS_TOKEN     -Fname=myfirstfile.csv     -Ffile=@path/to/local_file.csv

importjsonimportrequestsurl='https://zenodo.org/api/deposit/depositions/1234/files?access_token=ACCESS_TOKEN'data={'name':'myfirstfile.csv'}files={'file':open('path/to/local_file.csv','rb')}r=requests.post(url,data=data,files=files)

HTTP Request

POST /api/deposit/depositions/:id/files

Request headers

Content-Type: multipart/form-data

Scopes

deposit:write

Success response

• Code:201 Created
• Body: adeposition file resource.

Error response

SeeHTTP status codes (400 and 500 series errors) anderror responses.

Sort

Sort the files for a deposition. By default, the first file is shown in the filepreview.

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

importjsonimportrequestsurl='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)

HTTP Request

PUT /api/deposit/depositions/:id/files

Request headers

Content-Type: application/json

Scopes

deposit:write

Data

A JSON array of partialdeposition file resources with onlytheid attribute. Example:

[{"id":"<file_id_1>"},{"id":"<file_id_2>"},"..."]

Success response

• Code:200 OK
• Body: an array ofdeposition file resources.

Error response

SeeHTTP status codes (400 and 500 series errors) anderror responses.

Retrieve

Retrieve a single deposition file.

curl -i https://zenodo.org/api/deposit/depositions/1234/files/12345678-9abc-def1-2345-6789abcdef12?access_token=ACCESS_TOKEN

importrequestsr=requests.get('https://zenodo.org/api/deposit/depositions/1234/files/12345678-9abc-def1-2345-6789abcdef12',params={'access_token':ACCESS_TOKEN})

HTTP Request

GET /api/deposit/depositions/:id/files/:file_id

Success Response

• Code:200 OK
• Body: adeposition file resource.

Error response

SeeHTTP status codes (400 and 500 series errors) anderror responses.

Update

Update a deposition file resource. Currently the only use is renaming an alreadyuploaded file. If you one to replace the actual file, please delete the file andupload a new file.

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

importjsonimportrequestsurl='https://zenodo.org/api/deposit/depositions/1234/files/21fedcba-9876-5432-1fed-cba987654321?access_token=ACCESS_TOKEN'headers={"Content-Type":"application/json"}data={"name":"someothername.csv"}r=requests.put(url,data=json.dumps(data),headers=headers)

HTTP Request

PUT /api/deposit/depositions/:id/files/:file_id

Request headers

Content-Type: application/json

Scopes

deposit:write

Data

A partialdeposition file resources with only thefilename attributes. Example:

{"name":"<new_file_name>"}

Success response

• Code:200 OK
• Body: adeposition file resource.

Error response

SeeHTTP status codes (400 and 500 series errors) anderror responses.

Delete

Delete an existing deposition file resource. Note, only deposition files forunpublished depositions may be deleted.

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

importrequestsr=requests.delete('https://zenodo.org/api/deposit/depositions/1234/files/21fedcba-9876-5432-1fed-cba987654321',params={'access_token':ACCESS_TOKEN})

HTTP Request

DELETE /api/deposit/depositions/:id/files/:file_id

Scopes

deposit:write

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 alsoHTTP status codes (400 and 500 series errors) anderror responses.

Deposition actions

Publish

Publish a deposition. Note, once a deposition is published, you can no longerdelete it.

curl -i -X POST https://zenodo.org/api/deposit/depositions/1234/actions/publish?access_token=ACCESS_TOKEN

importrequestsr=requests.post('https://zenodo.org/api/deposit/depositions/1234/actions/publish',params={'access_token':ACCESS_TOKEN})

HTTP Request

POST /api/deposit/depositions/:id/actions/publish

Scopes

deposit:actions

Success response

• Code:202 Accepted
• Body: adeposition resource.

Error response

SeeHTTP status codes (400 and 500 series errors) anderror responses.

Edit

Unlock already submitted deposition for editing.

curl -i -X POST https://zenodo.org/api/deposit/depositions/1234/actions/edit?access_token=ACCESS_TOKEN

importrequestsr=requests.post('https://zenodo.org/api/deposit/depositions/1234/actions/edit',params={'access_token':ACCESS_TOKEN})

HTTP Request

POST /api/deposit/depositions/:id/actions/edit

Scopes

deposit:actions

Success response

• Code:201 Created
• Body: adeposition resource.

Error response

• 400 Bad Request: Deposition state does not allow for editing (e.g.depositions in stateinprogress).
• 409 Conflict: Deposition is in the process of being integrated, please wait5 minutes before trying again.

SeeHTTP status codes (400 and 500 series errors) anderror responses.

Discard

Discard changes in the current editing session.

curl -i -X POST https://zenodo.org/api/deposit/depositions/1234/actions/discard?access_token=ACCESS_TOKEN

importrequestsr=requests.post('https://zenodo.org/api/deposit/depositions/1234/actions/discard',params={'access_token':ACCESS_TOKEN})

HTTP Request

POST /api/deposit/depositions/:id/actions/discard

Scopes

deposit:actions

Success response

• Code:201 Created
• Body: adeposition resource.

Error response

• 400 Bad Request: Deposition is not being edited.

SeeHTTP status codes (400 and 500 series errors) anderror responses.

New version

Create a new version of a deposition.

This action will create a new deposit, which will be a snapshot of the current resouce, inheriting the metadata as well as snapshot of files.The new version deposit will have a state similar to a new, unpublished deposit, most importantly its files will be modifiable as for a new deposit.

Only one unpublished new version deposit can be available at any moment, i.e.: calling new version action multiple times will have no effect, as long as the resulting new version deposit from the first call is not published or deleted.

NOTES: - The response body of this action is NOT the new version deposit, but the original resource.The new version deposition can be accessed through the"latest_draft" under"links" in the response body.- Theid used to create this new version has to be theid of the latest version. It is not possible to use the global id that references all the versions.

curl -i -X POST https://zenodo.org/api/deposit/depositions/1234/actions/newversion?access_token=ACCESS_TOKEN

importrequestsr=requests.post('https://zenodo.org/api/deposit/depositions/1234/actions/newversion',params={'access_token':ACCESS_TOKEN})

HTTP Request

POST /api/deposit/depositions/:id/actions/newversion

Scopes

deposit:actions

Success response

• Code:201 Created
• Body: adeposition resource.

Error response

SeeHTTP status codes (400 and 500 series errors) anderror responses.

Records

Representation

The Records resource is used to search through published records.

List

List all open access records.

importrequestsresponse=requests.get('https://zenodo.org/api/records',params={'q':'my title','access_token':ACCESS_TOKEN})print(response.json())

curl -i /api/records/?access_token=ACCESS_TOKEN

HTTP Request

GET /api/records/

Query arguments

Header

The response format of the search can be requested by specifying it in the header.

Success Response

• Code:200 OK
• Body: an array ofrecord resources.

Error Response

SeeHTTP status codes (400 and 500 series errors) anderror responses.

Search guide

Advanced search queries can as well be performed on Zenodo website through the search box. This is documented in thesearch guide

Retrieve

Retrieve a single record.

curl -i https://zenodo.org/api/records/1234

importrequestsr=requests.get("https://zenodo.org/api/records/1234)

HTTP Request

GET https://zenodo.org/api/records/:id

Again, the output format of the search can be specified in theheader

Success response

• Code:200 OK
• Body: arecord.

Error response

SeeHTTP status codes (400 and 500 series errors) anderror responses. |

Licenses

Representation

The License resource is used for serving the license metadata that can beapplied to uploaded content on Zenodo.

License

License metadata

List

Search through licenses.

importrequestsresponse=requests.get('/api/licenses/')print(response.json())

curl /api/licenses/

HTTP Request

GET /api/licenses/

Query arguments

Success Response

• Code:200 OK
• Body: an array oflicense resources.

Error response

SeeHTTP status codes (400 and 500 series errors) anderror responses. |

Retrieve

Retrieve a single license resource.

importrequestsr=requests.get("/api/licenses/cc-by-nc-4.0")

curl /api/licenses/cc-by-nc-4.0

HTTP Request

GET /api/licenses/:id

Success response

• Code:200 OK
• Body: alicense resource.

Error response

SeeHTTP status codes (400 and 500 series errors) anderror responses. |

Changes

2017-10-04

• Added new optional fieldversion to deposition metadata.
• Added new optional fieldlanguage to deposition metadata.

2017-06-15

• Added support for DOI versioning as part of deposit actions.

2016-09-12

• Added support for search, pagination, sorting and filtering.
• Improved speed significantly.

2015-10-06

• Added new optional fieldcontributors to deposition metadata.
• Added new optional fieldsubjects to deposition metadata.
• Added new optional subfieldgnd tocreators in deposition metadata.

2014-12-20

• Added new relationshipisAlternateIdentifier in subfieldrelation torelated_identifiers in deposition metadata.

2014-12-10

• Added new relationshipshasPart,isPartOf &isIdenticalTo in subfieldrelation torelated_identifiers in deposition metadata.

2014-11-20

• Added new optional subfieldorcid tocreators in deposition metadata.

2014-10-21

• Added new optional fieldsconference_session andconference_session_partto deposition metadata.

2014-09-09

• Added new optional fieldreferences to deposition metadata.

2014-06-13

• Authentication changed from API keys to OAuth 2.0. API key authentication isdeprecated and will be phased out in October, 2014. Please usepersonalaccess tokens instead of API keys.

2013-12-18

REST API version 1.0 final release:

• Deposition actions moved fromdeposit/depositions/:id/action todeposit/depositions/:id/actions
• Addededit anddiscard 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

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

All metadata is licensed underCreative CommonsZero, while the data files may be either openaccess and subject to a license described in the metadata or closed access andnot available for download.

Base URL

Our OAI-PMH base endpoint is athttps://zenodo.org/oai2d.

Installing prerequisites for our example

For this example, we are going to be using Sickle since it simplifies our workflow and supports XML parsing.

# Install the Sickle package using pippipinstallSickle

'''Import Sickle and initialize the client by passing the base URL'''fromsickleimportSicklesickle=Sickle('https://zenodo.org/oai2d')

Get information about the OAI-PMH API

To get some general information about the OAI-PMH capabilities we can use theIdentify verb.

'''Get information on the OAI-PMH API by using "Identify"'''info=sickle.Identify()info.granularity# 'YYYY-MM-DDThh:mm:ssZ'info.earliestDatestamp# '2014-02-03T14:41:33Z'

Resumption tokens

Resumption tokens are only valid for2 minutes. In case a token expired, you will receive a422 Unprocessable Entity HTTP error.

The OAI-PMH API is rated limited like the REST API - i.e. you will receivea429 Too Many Requests HTTP error if you exceed the limit.For more information please take a look at therate limiting documentation.

Metadata formats

To list the available records metadata formats we can useListMetadataFormats.

'''Metadata for each record is available in several formats'''metadataFormats=sickle.ListMetadataFormats()list(metadataFormats)# [<MetadataFormat marcxml>, <MetadataFormat oai_datacite4>, ...]

Available metadata formats

oai_datacite

OAI DataCite (latest schema version) — This metadata format has beenspecifically established for the dissemination of DataCite records usingOAI-PMH. In addition to the original DataCite metadata, this format containsseveral other elements describing the version of the metadata, whether it is ofreference quality, and the registering datacentre. For more information aboutthis format and its schema please see theDataCite OAI schema website.

This metadata format will always deliver metadata according to the latestavailable DataCite schema version.

See example

See example

oai_dc

Dublin Core — only minimal metadata is included in this format. The format is exported according to theOpenAIRE Guidelines.

See example

dcat

DCAT — export format based on theDCAT Application Profile for data portals in Europe (DCAT-AP). The format is produced from the DataCite export format using theDataCite-to-DCAT-AP XSLT.This is the only OAI-PMH metadata format that currently exposes direct links to each record’s files content, via thedcat:Distribution elements.

See example

marc21

MARC21 — export format primarily supported for legacy reasons. Please considerusing one of the other export formats as we may discontinue support for MARC21.

See example

Sets

We support both harvesting of theentire repository as well asselectiveharvesting of communities.

Entire repository

To harvest the entire repository, entirely skip theset parameter (you still need to pass the requiredmetadataPrefix parameter).

See example

''' Harvest the entire repository '''records=sickle.ListRecords(metadataPrefix='oai_dc')record=records.next()# <Record oai:zenodo.org:3442216>

Selective harvesting

user-<identifier>

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

See example

''' Fetch a couple of records from the OAI Set of the "cfa" community '''records=sickle.ListRecords(metadataPrefix='oai_dc',set='user-cfa')record=records.next()''' To inspect on what sets a record is in '''record.header.setSpecs# ['openaire_data', 'user-cfa']

Harvesting with a different metadata format

There is also the possibility of using different metadata formats. For that, we only need to replace themetadataPrefix argument.

See example

''' Community harvest using "oai_datacite" metadata format '''records=sickle.ListRecords(metadataPrefix='oai_datacite',set='user-cfa')record=records.next()''' Retrieving metadata from the record '''record.metadata# {#    "title": ["Computing and Using Metrics in ADS"],#    "creatorName": ["Henneken, Edwin"],#    "identifier": ["10.5281/zenodo.10897"],#    ...# }

Harvesting with multiple filters

Using multiple filters to harvest records enables a higher level of granularity, allowing us to retrieve specific groups of records.

See example

''' Selecting harvesting using "from" '''records=sickle.ListRecords(**{'metadataPrefix':'oai_dc','set':'user-cfa','from':'2019-01-01',})records.next()# <Record oai:zenodo.org:7661>records.next()# <Record oai:zenodo.org:6738>

Other questions on harvesting

If you need selective harvesting and your use case is not supported by abovesets, you cancontact us and we can trycreate a specific set for you.

Update schedule

Most updates are available immediately, some few updates are only reflected in the OAI sets once an hour.

GitHub

Add metadata to your GitHub repository release

{"creators":[{"orcid":"0000-0002-1825-0097","affiliation":"Feline reasearch institute","name":"Field, Gar"},{"orcid":"0000-0002-1825-0097","affiliation":"Feline reasearch institute","name":"Cat, Felix"}],"license":"Apache-2.0","title":"Red-Dot: ML-powered laser vector detection","related_identifiers":[{"scheme":"doi","identifier":"10.1234/software.paper.5678","relation":"isDocumentedBy","resource_type":"publication-article"}],"keywords":["Cats","Laser","Behavior"],"communities":[{"identifier":"software-cats"}],"grants":[{"id":"777541"}]}

We automatically extract metadata about your release from GitHub APIs. For example, the authors are determined from the repository’s contributor statistics. To overwrite some of the default metadata that would come from a regular GitHub release you can include a.zenodo.json file at the root of your GitHub repository.

The contents of the.zenodo.json file are based on ourdeposit metadata documentation and can be structurally validated using ourlegacy deposit JSON Schema.

In the example shown, we add metadata regarding:

• software authorship and ORCiDs, via thecreators field
• Apache-2.0 licensing, via thelicense field
• a custom title, via thetitle field
• a related identifier to the software paper, via therelated_identifiers field
• keywords, via thekeywords field
• Zenodo communities, via thecommunities field
• funding information, via thegrants field

How to verify your “.zenodo.json” file?

After creating your.zenodo.json file you should validate it to make sure that it contains valid JSON. You can use a tool like theJSON Formatter & Validator, or load it via your favorite programming language.

Rate Limiting

For our content and services to be available to everyone we have to make sure that our resources are being distributed fairly. To achieve this, we have rate-limiting measures in place which limit the number of requests users can perform in a time window. Depending on the complexity and load of each request, different endpoints have different limits configured.

When you are making requests to any of our endpoints, you can inspect the following HTTP response headers for more information of your current rate-limit status: