CINXE.COM

<!doctype html> <html> <head><script type="text/javascript" src="/_static/js/bundle-playback.js?v=HxkREWBo" charset="utf-8"></script> <script type="text/javascript" src="/_static/js/wombat.js?v=txqj7nKC" charset="utf-8"></script> <script>window.RufflePlayer=window.RufflePlayer||{};window.RufflePlayer.config={"autoplay":"on","unmuteOverlay":"hidden"};</script> <script type="text/javascript" src="/_static/js/ruffle/ruffle.js"></script> <script type="text/javascript"> __wm.init("https://web.archive.org/web"); __wm.wombat("https://developers.zenodo.org/","20210812203808","https://web.archive.org/","web","/_static/", "1628800688"); </script> <link rel="stylesheet" type="text/css" href="/_static/css/banner-styles.css?v=S1zqJCYt" /> <link rel="stylesheet" type="text/css" href="/_static/css/iconochive.css?v=3PDvdIFv" />  <meta charset="utf-8"> <meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible"> <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1"> <title>Developers | Zenodo</title> <style> .highlight table td { padding: 5px; } .highlight table pre { margin: 0; } .highlight, .highlight .w { color: #f8f8f2; background-color: #272822; } .highlight .err { color: #272822; background-color: #f92672; } .highlight .c, .highlight .cd, .highlight .cm, .highlight .c1, .highlight .cs { color: #75715e; } .highlight .cp { color: #f4bf75; } .highlight .nt { color: #f4bf75; } .highlight .o, .highlight .ow { color: #f8f8f2; } .highlight .p, .highlight .pi { color: #f8f8f2; } .highlight .gi { color: #a6e22e; } .highlight .gd { color: #f92672; } .highlight .gh { color: #66d9ef; background-color: #272822; font-weight: bold; } .highlight .k, .highlight .kn, .highlight .kp, .highlight .kr, .highlight .kv { color: #ae81ff; } .highlight .kc { color: #fd971f; } .highlight .kt { color: #fd971f; } .highlight .kd { color: #fd971f; } .highlight .s, .highlight .sb, .highlight .sc, .highlight .sd, .highlight .s2, .highlight .sh, .highlight .sx, .highlight .s1 { color: #a6e22e; } .highlight .sr { color: #a1efe4; } .highlight .si { color: #cc6633; } .highlight .se { color: #cc6633; } .highlight .nn { color: #f4bf75; } .highlight .nc { color: #f4bf75; } .highlight .no { color: #f4bf75; } .highlight .na { color: #66d9ef; } .highlight .m, .highlight .mf, .highlight .mh, .highlight .mi, .highlight .il, .highlight .mo, .highlight .mb, .highlight .mx { color: #a6e22e; } .highlight .ss { color: #a6e22e; } </style> <link href="/web/20210812203808cs_/https://developers.zenodo.org/stylesheets/screen.css" rel="stylesheet" media="screen"/> <link href="/web/20210812203808cs_/https://developers.zenodo.org/stylesheets/print.css" rel="stylesheet" media="print"/> <script src="/web/20210812203808js_/https://developers.zenodo.org/javascripts/all.js"></script> <link href="https://web.archive.org/web/20210812203808cs_/https://fonts.googleapis.com/css?family=Roboto:300,400,500,700,100,italic" rel="stylesheet"> </head> <body class="index" data-languages="["python","shell"]"> <div class="header"> <a class="logo-container" href="https://web.archive.org/web/20210812203808/https://zenodo.org/"> <img src="/web/20210812203808im_/https://developers.zenodo.org/images/zenodo.svg" alt="Zenodo"/> </a> <a href="https://web.archive.org/web/20210812203808/http://developers.zenodo.org/"><div class="header-title">Developers</div></a> <ul class="header-menu">  <li><a href="https://web.archive.org/web/20210812203808/http://about.zenodo.org/">About</a></li> <li><a href="https://web.archive.org/web/20210812203808/http://blog.zenodo.org/">Blog</a></li> <li><a href="https://web.archive.org/web/20210812203808/http://help.zenodo.org/">Help</a></li> <li><a class="active" href="https://web.archive.org/web/20210812203808/http://developers.zenodo.org/">Developers</a></li> </ul> </div> <a href="#" id="nav-button"> NAV <img src="/web/20210812203808im_/https://developers.zenodo.org/images/navbar.png" alt="Navbar"/> </a> <div class="tocify-wrapper"> <div class="lang-selector"> <a href="#" data-language-name="python">Python</a> <a href="#" data-language-name="shell">cURL</a> </div> <div class="search"> <input type="text" class="search" id="input-search" placeholder="Search"> </div> <ul class="search-results"></ul> <div id="toc"> </div> <ul class="toc-footer"> <li><a href="https://web.archive.org/web/20210812203808/https://zenodo.org/privacy-policy">Privacy policy</a></li> <li><a href="https://web.archive.org/web/20210812203808/https://zenodo.org/terms">Terms of Use</a></li> <li><a href="https://web.archive.org/web/20210812203808/https://zenodo.org/contact">Contact</a></li> </ul> </div> <div class="page-wrapper"> <div class="page_content"> <div class="dark-box"></div> <div class="content"> <h1 id="rest-api">REST API</h1> <h2 id="introduction">Introduction</h2> The Zenodo REST API currently supports: <ul> <li>Deposit — upload and publishing of research outputs (identical to functionality available in the user interface).</li> <li>Records — search published records.</li> <li>Files — download/upload of files.</li> </ul> Check out the <a href="#quickstart-upload">Quickstart</a> guide for an example on how to programmatically upload and publish your research outputs. The following REST APIs are currently in testing before we launch them in beta with full documentation: <ul> <li>Communities - search communities.</li> <li>Funders — search for funders.</li> <li>Grants — search for grants.</li> <li>Licenses — search for licenses.</li> </ul> You can have a sneak peek at the APIs in test from our root endpoint: <code class="prettyprint">https://zenodo.org/api/</code> <h2 id="quickstart-upload">Quickstart - Upload</h2> This short guide will give a quick overview of how to upload and publish on Zenodo, and will be using Python together with the <a href="https://web.archive.org/web/20210812203808/http://www.python-requests.org/en/latest/user/install/">Requests</a> package. <pre class="highlight shell_session"><code>$ pip install requests </code></pre> <ul> <li>First, make sure you have the <a href="https://web.archive.org/web/20210812203808/http://www.python-requests.org/en/latest/user/install/">Requests</a> module installed:</li> </ul> <div class="align-columns"></div> <pre class="highlight shell_session"><code>$ python Python 3.6.5 [GCC 4.8.1] on linux2 Type "help", "copyright", "credits" or "license" for more information. </code></pre> <ul> <li>Next, fire up a Python command prompt:</li> </ul> <div class="align-columns"></div> <pre class="highlight python"><code>import requests </code></pre> <ul> <li>Import the <code class="prettyprint">requests</code> module:</li> </ul> <div class="align-columns"></div> <pre class="highlight python"><code>>>> import requests >>> r = requests.get("https://zenodo.org/api/deposit/depositions") >>> r.status_code 401 >>> r.json() </code></pre><pre class="highlight json"><code>{ "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 } </code></pre> <ul> <li>We will try to access the API without an authentication token:</li> </ul> <div class="align-columns"></div> <ul> <li>All API access requires an access token, so <a href="https://web.archive.org/web/20210812203808/https://zenodo.org/account/settings/applications/tokens/new/">create</a> one.</li> </ul> <div class="align-columns"></div> <pre class="highlight python"><code>>>> ACCESS_TOKEN = 'ChangeMe' >>> r = requests.get('https://zenodo.org/api/deposit/depositions', ... params={'access_token': ACCESS_TOKEN}) >>> r.status_code 200 >>> r.json() [] </code></pre> <ul> <li>Let’s try again (replace <code class="prettyprint">ACCESS_TOKEN</code> with your newly created personal access token):</li> </ul> <aside class="notice"> Note, if you already uploaded something, the output will be different. </aside> <div class="align-columns"></div> <pre class="highlight python"><code>>>> 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 201 >>> r.json() </code></pre><pre class="highlight json"><code>{ "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": "" } </code></pre> <ul> <li>Next, let’s create a new empty upload:</li> </ul> <div class="align-columns"></div> <ul> <li>Now, let’s upload a new file. We have recently released a new API, which is significantly more perfomant and supports much larger file sizes. While the older API supports 100MB per file, the new one has no size limitation.</li> </ul> <div class="align-columns"></div> <pre class="highlight python"><code>bucket_url = r.json()["links"]["bucket"] </code></pre><pre class="highlight shell"><code>$ curl https://zenodo.org/api/deposit/depositions/222761?access_token=$ACCESS_TOKEN { ... "links": { "bucket": "https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b", ..., }, ... } </code></pre> <ul> <li>To use the new files API we will do a PUT request to the <code class="prettyprint">bucket</code> link. The bucket is a folder-like object storing the files of our record. Our bucket URL will look like this: <code class="prettyprint">https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b</code> and can be found under the <code class="prettyprint">links</code> key in our records metadata.</li> </ul> <pre class="highlight shell"><code># 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 { ... } </code></pre><pre class="highlight python"><code># New API filename = "my-file.zip" path = "/path/to/%s" % filename # The target URL is a combination of the bucket link with the desired filename # seperated by a slash. with open(path, "rb") as fp: r = requests.put( "%s/%s" % (bucket_url, filename), data=fp, params=params, ) r.json() </code></pre><pre class="highlight json"><code>{ "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 } </code></pre> <div class="align-columns"></div> <pre class="highlight python"><code># Old API >>> # Get 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 201 >>> r.json() </code></pre><pre class="highlight json"><code>{ "checksum": "2b70e04bb31f2656ce967dc07103297f", "name": "myfirstfile.csv", "id": "eb78d50b-ecd4-407a-9520-dfc7a9d1ab2c", "filesize": "27" } </code></pre> <ul> <li>Here are the instructions for the old files API:</li> </ul> <div class="align-columns"></div> <pre class="highlight python"><code>>>> 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 </code></pre> <ul> <li>Last thing missing, is just to add some metadata:</li> </ul> <div class="align-columns"></div> <pre class="highlight python"><code>>>> r = requests.post('https://zenodo.org/api/deposit/depositions/%s/actions/publish' % deposition_id, params={'access_token': ACCESS_TOKEN} ) >>> r.status_code 202 </code></pre> <ul> <li>And we’re ready to publish:</li> </ul> <aside class="warning"> Don’t execute this last step - it will put your test upload straight online. </aside> <h2 id="testing">Testing</h2> We provide a sandbox environment where you can test your API integration during development. The sandbox environment is available at <a href="https://web.archive.org/web/20210812203808/https://sandbox.zenodo.org/">http://sandbox.zenodo.org</a>. 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). <h2 id="versioning">Versioning</h2> 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. <a href="#changes">Changes</a> to the API are documented on this page, and advance notification is given on our <a href="https://web.archive.org/web/20210812203808/https://twitter.com/zenodo_org">Twitter account</a>. <h2 id="authentication">Authentication</h2> All API requests must be authenticated and over HTTPS. Any request over plain HTTP will fail. We support authentication with via OAuth 2.0. <h3 id="creating-a-personal-access-token">Creating a personal access token</h3> <ol> <li><a href="https://web.archive.org/web/20210812203808/https://zenodo.org/signup">Register</a> for a Zenodo account if you don’t already have one.</li> <li>Go to your <a href="https://web.archive.org/web/20210812203808/https://zenodo.org/account/settings/applications/">Applications</a>, to <a href="https://web.archive.org/web/20210812203808/https://zenodo.org/account/settings/applications/tokens/new/">create a new token</a>.</li> <li>Select the OAuth scopes you need (for the quick start tutorial you need <code class="prettyprint">deposit:write</code> and <code class="prettyprint">deposit:actions</code>).</li> </ol> <aside class="warning"> Do not share your personal access token with anyone else, and only use it over HTTPS. </aside> <h3 id="using-access-tokens">Using access tokens</h3> An access token must be included in all requests as either: <pre class="highlight plaintext"><code>GET /api/deposit/depositions?access_token=<ACCESS_TOKEN> </code></pre> <ul> <li>an URL parameter (named <code class="prettyprint">access_token</code>):</li> </ul> <div class="align-columns"></div> <pre class="highlight plaintext"><code>GET /api/deposit/depositions Authorization: Bearer <ACCESS_TOKEN> </code></pre> <ul> <li>or as HTTP request header (<code class="prettyprint">Authorization</code>):</li> </ul> <div class="align-columns"></div> <h3 id="scopes">Scopes</h3> Scopes assigns permissions to your access token to limit access to data and actions in Zenodo. The following scopes exist: <table><thead> <tr> <th style="text-align: left">Name</th> <th style="text-align: left">Description</th> </tr> </thead><tbody> <tr> <td style="text-align: left"><code class="prettyprint">deposit:write</code></td> <td style="text-align: left">Grants write access to depositions, but does not allow publishing the upload.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">deposit:actions</code></td> <td style="text-align: left">Grants access to publish, edit and discard edits for depositions.</td> </tr> </tbody></table> <h2 id="requests">Requests</h2> The base URL of the API is <code class="prettyprint">https://zenodo.org/api/</code>. All <code class="prettyprint">POST</code> and <code class="prettyprint">PUT</code> request bodies must be JSON encoded, and must have content type of <code class="prettyprint">application/json</code> unless specified otherwise in the specific resource (e.g. in the case of file uploads). The API will return a <code class="prettyprint">415</code> error (see <a href="#http-status-codes">HTTP status codes</a> and <a href="#errors">error responses</a>) if the wrong content type is provided. <h2 id="responses">Responses</h2> <pre class="highlight json"><code>{ "field1": "value", "...": "..." } </code></pre> All response bodies are JSON encoded (UTF-8 encoded). A single resource is represented as a JSON object: <div class="align-columns"></div> <pre class="highlight json"><code>[ { "field1": "value", "...": "..." } "..." ] </code></pre> A collection of resources is represented as a JSON array of objects: <div class="align-columns"></div> <pre class="highlight plaintext"><code>YYYY-MM-DDTHH:MM:SS+00:00 </code></pre> Timestamps are in UTC and formatted according to <a href="https://web.archive.org/web/20210812203808/http://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a>: <h2 id="http-status-codes">HTTP status codes</h2> We use the following HTTP status codes to indicate success or failure of a request. <table><thead> <tr> <th style="text-align: left">Code</th> <th style="text-align: left">Name</th> <th style="text-align: left">Description</th> </tr> </thead><tbody> <tr> <td style="text-align: left"><code class="prettyprint">200</code></td> <td style="text-align: left">OK</td> <td style="text-align: left">Request succeeded. Response included. Usually sent for GET/PUT/PATCH requests.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">201</code></td> <td style="text-align: left">Created</td> <td style="text-align: left">Request succeeded. Response included. Usually sent for POST requests.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">202</code></td> <td style="text-align: left">Accepted</td> <td style="text-align: left">Request succeeded. Response included. Usually sent for POST requests, where background processing is needed to fulfill the request.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">204</code></td> <td style="text-align: left">No Content</td> <td style="text-align: left">Request succeeded. No response included. Usually sent for DELETE requests.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">400</code></td> <td style="text-align: left">Bad Request</td> <td style="text-align: left">Request failed. <a href="#errors">Error response</a> included.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">401</code></td> <td style="text-align: left">Unauthorized</td> <td style="text-align: left">Request failed, due to an invalid access token. <a href="#errors">Error response</a> included.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">403</code></td> <td style="text-align: left">Forbidden</td> <td style="text-align: left">Request failed, due to missing authorization (e.g. deleting an already submitted upload or missing scopes for your access token). <a href="#errors">Error response</a> included.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">404</code></td> <td style="text-align: left">Not Found</td> <td style="text-align: left">Request failed, due to the resource not being found. <a href="#errors">Error response</a> included.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">405</code></td> <td style="text-align: left">Method Not Allowed</td> <td style="text-align: left">Request failed, due to unsupported HTTP method. <a href="#errors">Error response</a> included.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">409</code></td> <td style="text-align: left">Conflict</td> <td style="text-align: left">Request failed, due to the current state of the resource (e.g. edit a deopsition which is not fully integrated). <a href="#errors">Error response</a> included.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">415</code></td> <td style="text-align: left">Unsupported Media Type</td> <td style="text-align: left">Request failed, due to missing or invalid request header <code class="prettyprint">Content-Type</code>. <a href="#errors">Error response</a> included.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">429</code></td> <td style="text-align: left">Too Many Requests</td> <td style="text-align: left">Request failed, due to rate limiting. <a href="#errors">Error response</a> included.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">500</code></td> <td style="text-align: left">Internal Server Error</td> <td style="text-align: left">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.</td> </tr> </tbody></table> <h2 id="errors">Errors</h2> Error responses for 400 series errors (e.g. 400, 401, 403, …) are returned as a JSON object with two attributes <code class="prettyprint">message</code> and <code class="prettyprint">status</code> (HTTP status code), and possibly an attribute <code class="prettyprint">errors</code> with a list of more detailed errors. <div class="align-columns"></div> <pre class="highlight json"><code>{ "message": "Deposition not found", "status": 404 } </code></pre> Example of a simple error message without further detailed errors: <div class="align-columns"></div> <pre class="highlight json"><code>{ "message": "Validation error", "status": 400, "errors": [ {"code": 10, "message":"Not a valid choice", "field": "access_right"} ] } </code></pre> Example of an error message with additional detailed error messages: The attribute <code class="prettyprint">errors</code> is a JSON array of objects, with the attributes <code class="prettyprint">message</code> and <code class="prettyprint">code</code>, and possibly <code class="prettyprint">field</code> for validation errors. <h1 id="entities">Entities</h1> <h2 id="depositions">Depositions</h2> <h3 id="representation">Representation</h3> The Deposition resource is used for uploading and editing records on Zenodo. <h4 id="deposit">Deposit</h4> <table><thead> <tr> <th style="text-align: left">Field</th> <th style="text-align: left">Description</th> </tr> </thead><tbody> <tr> <td style="text-align: left"><code class="prettyprint">created</code>timestamp</td> <td style="text-align: left">Creation time of deposition (in ISO8601 format).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">doi</code>string</td> <td style="text-align: left">Digital Object Identifier (DOI). When you publish your deposition, we register a DOI in <a href="https://web.archive.org/web/20210812203808/http://www.datacite.org/">DataCite</a> for your upload, unless you manually provided us with one. This field is only present for published depositions.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">doi_url</code>url</td> <td style="text-align: left">Persistent link to your published deposition. This field is only present for published depositions.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">files</code>array</td> <td style="text-align: left">A list of <a href="#deposition-file">deposition files</a> resources.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">id</code>integer</td> <td style="text-align: left">Deposition identifier</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">metadata</code>object</td> <td style="text-align: left">A <a href="#deposit-metadata">deposition metadata</a> resource</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">modified</code>timestamp</td> <td style="text-align: left">Last modification time of deposition (in ISO8601 format).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">owner</code>integer</td> <td style="text-align: left">User identifier of the owner of the deposition.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">record_id</code>integer</td> <td style="text-align: left">Record identifier. This field is only present for published depositions.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">record_url</code>url</td> <td style="text-align: left">URL to public version of record for this deposition. This field is only present for published depositions.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">state</code>string</td> <td style="text-align: left">One of the values: * <code class="prettyprint">inprogress</code>: Deposition metadata can be updated. If deposition is also unsubmitted (see <code class="prettyprint">submitted</code>) files can be updated as well. * <code class="prettyprint">done</code>: Deposition has been published. * <code class="prettyprint">error</code>: Deposition is in an error state - contact our support.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">submitted</code>bool</td> <td style="text-align: left">True of deposition has been published, False otherwise.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">title</code>string</td> <td style="text-align: left">Title of deposition (automatically set from <code class="prettyprint">metadata</code>). Defaults to empty string.</td> </tr> </tbody></table> <h4 id="deposit-metadata">Deposit metadata</h4> <table><thead> <tr> <th style="text-align: left">Attribute</th> <th style="text-align: left">Required</th> <th style="text-align: left">Description</th> </tr> </thead><tbody> <tr> <td style="text-align: left"><code class="prettyprint">upload_type</code>string</td> <td style="text-align: left">Yes</td> <td style="text-align: left">Controlled vocabulary:* <code class="prettyprint">publication</code>: Publication* <code class="prettyprint">poster</code>: Poster* <code class="prettyprint">presentation</code>: Presentation* <code class="prettyprint">dataset</code>: Dataset* <code class="prettyprint">image</code>: Image* <code class="prettyprint">video</code>: Video/Audio* <code class="prettyprint">software</code>: Software* <code class="prettyprint">lesson</code>: Lesson* <code class="prettyprint">physicalobject</code>: Physical object* <code class="prettyprint">other</code>: Other</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">publication_type</code>string</td> <td style="text-align: left">Yes, if <code class="prettyprint">upload_type</code> is <code class="prettyprint">"publication"</code>.</td> <td style="text-align: left">Controlled vocabulary:* <code class="prettyprint">annotationcollection</code>: Annotation collection* <code class="prettyprint">book</code>: Book* <code class="prettyprint">section</code>: Book section* <code class="prettyprint">conferencepaper</code>: Conference paper* <code class="prettyprint">datamanagementplan</code>: Data management plan* <code class="prettyprint">article</code>: Journal article* <code class="prettyprint">patent</code>: Patent* <code class="prettyprint">preprint</code>: Preprint* <code class="prettyprint">deliverable</code>: Project deliverable* <code class="prettyprint">milestone</code>: Project milestone* <code class="prettyprint">proposal</code>: Proposal* <code class="prettyprint">report</code>: Report* <code class="prettyprint">softwaredocumentation</code>: Software documentation* <code class="prettyprint">taxonomictreatment</code>: Taxonomic treatment* <code class="prettyprint">technicalnote</code>: Technical note* <code class="prettyprint">thesis</code>: Thesis* <code class="prettyprint">workingpaper</code>: Working paper* <code class="prettyprint">other</code>: Other</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">image_type</code>string</td> <td style="text-align: left">Yes, if <code class="prettyprint">upload_type</code> is <code class="prettyprint">"image"</code>.</td> <td style="text-align: left">Controlled vocabulary:* <code class="prettyprint">figure</code>: Figure* <code class="prettyprint">plot</code>: Plot* <code class="prettyprint">drawing</code>: Drawing* <code class="prettyprint">diagram</code>: Diagram* <code class="prettyprint">photo</code>: Photo* <code class="prettyprint">other</code>: Other</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">publication_date</code>string</td> <td style="text-align: left">Yes</td> <td style="text-align: left">Date of publication in ISO8601 format (<code class="prettyprint">YYYY-MM-DD</code>). Defaults to current date.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">title</code>string</td> <td style="text-align: left">Yes</td> <td style="text-align: left">Title of deposition.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">creators</code>array of objects</td> <td style="text-align: left">Yes</td> <td style="text-align: left">The creators/authors of the deposition. Each array element is an object with the attributes:* <code class="prettyprint">name</code>: Name of creator in the format Family name, Given names* <code class="prettyprint">affiliation</code>: Affiliation of creator (optional).* <code class="prettyprint">orcid</code>: ORCID identifier of creator (optional).* <code class="prettyprint">gnd</code>: GND identifier of creator (optional).Example: <code class="prettyprint">[{'name':'Doe, John', 'affiliation': 'Zenodo'}, {'name':'Smith, Jane', 'affiliation': 'Zenodo', 'orcid': '0000-0002-1694-233X'}, {'name': 'Kowalski, Jack', 'affiliation': 'Zenodo', 'gnd': '170118215'}]</code></td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">description</code>string (allows HTML)</td> <td style="text-align: left">Yes</td> <td style="text-align: left">Abstract or description for deposition.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">access_right</code>string</td> <td style="text-align: left">Yes</td> <td style="text-align: left">Controlled vocabulary:* <code class="prettyprint">open</code>: Open Access* <code class="prettyprint">embargoed</code>: Embargoed Access* <code class="prettyprint">restricted</code>: Restricted Access* <code class="prettyprint">closed</code>: Closed Access Defaults to <code class="prettyprint">open</code>.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">license</code>string</td> <td style="text-align: left">Yes, if <code class="prettyprint">access_right</code> is <code class="prettyprint">"open"</code> or <code class="prettyprint">"embargoed"</code>.</td> <td style="text-align: left">Controlled vocabulary:The selected license applies to all files in this deposition, but not to the metadata which is licensed under <a href="https://web.archive.org/web/20210812203808/http://about.zenodo.org/terms/">Creative Commons Zero</a>. You can find the available license IDs via our <a href="#licenses"><code class="prettyprint">/api/licenses</code> endpoint</a>. Defaults to <code class="prettyprint">cc-zero</code> for datasets and <code class="prettyprint">cc-by</code> for everything else.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">embargo_date</code>date</td> <td style="text-align: left">Yes, if <code class="prettyprint">access_right</code> is <code class="prettyprint">"embargoed"</code>.</td> <td style="text-align: left">When the deposited files will be made automatically made publicly available by the system. Defaults to current date.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">access_conditions</code>string (allows HTML)</td> <td style="text-align: left">Yes, if <code class="prettyprint">access_right</code> is <code class="prettyprint">"restricted"</code>.</td> <td style="text-align: left">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.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">doi</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">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.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">prereserve_doi</code>object/bool</td> <td style="text-align: left">No</td> <td style="text-align: left">Set to <code class="prettyprint">true</code>, 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 <a href="https://web.archive.org/web/20210812203808/http://www.datacite.org/">DataCite</a> 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.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">keywords</code>array of strings</td> <td style="text-align: left">No</td> <td style="text-align: left">Free form keywords for this deposition.Example: <code class="prettyprint">["Keyword 1", "Keyword 2"]</code></td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">notes</code>string (allows HTML)</td> <td style="text-align: left">No</td> <td style="text-align: left">Additional notes.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">related_identifiers</code>array of objects</td> <td style="text-align: left">No</td> <td style="text-align: left">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:* <code class="prettyprint">identifier</code>: The persistent identifier* <code class="prettyprint">relation</code>: Relationship. Controlled vocabulary (<code class="prettyprint">isCitedBy</code>, <code class="prettyprint">cites</code>, <code class="prettyprint">isSupplementTo</code>, <code class="prettyprint">isSupplementedBy</code>, <code class="prettyprint">isContinuedBy</code>, <code class="prettyprint">continues</code>, <code class="prettyprint">isDescribedBy</code>, <code class="prettyprint">describes</code>, <code class="prettyprint">hasMetadata</code>, <code class="prettyprint">isMetadataFor</code>, <code class="prettyprint">isNewVersionOf</code>, <code class="prettyprint">isPreviousVersionOf</code>, <code class="prettyprint">isPartOf</code>, <code class="prettyprint">hasPart</code>, <code class="prettyprint">isReferencedBy</code>, <code class="prettyprint">references</code>, <code class="prettyprint">isDocumentedBy</code>, <code class="prettyprint">documents</code>, <code class="prettyprint">isCompiledBy</code>, <code class="prettyprint">compiles</code>, <code class="prettyprint">isVariantFormOf</code>, <code class="prettyprint">isOriginalFormof</code>, <code class="prettyprint">isIdenticalTo</code>, <code class="prettyprint">isAlternateIdentifier</code>, <code class="prettyprint">isReviewedBy</code>, <code class="prettyprint">reviews</code>, <code class="prettyprint">isDerivedFrom</code>, <code class="prettyprint">isSourceOf</code>, <code class="prettyprint">requires</code>, <code class="prettyprint">isRequiredBy</code>, <code class="prettyprint">isObsoletedBy</code>, <code class="prettyprint">obsoletes</code>).* <code class="prettyprint">resource_type</code>: Type of the related resource (based on the <code class="prettyprint">upload_type</code>, <code class="prettyprint">publication_type</code>, and <code class="prettyprint">image_type</code> fields).Example: <code class="prettyprint">[{'relation': 'isSupplementTo', 'identifier':'10.1234/foo'}, {'relation': 'cites', 'identifier':'https://doi.org/10.1234/bar', 'resource_type': 'image-diagram'}]</code>. Note the identifier type (e.g. DOI) is automatically detected, and used to validate and normalize the identifier into a standard form.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">contributors</code>array of objects</td> <td style="text-align: left">No</td> <td style="text-align: left">The contributors of the deposition (e.g. editors, data curators, etc.). Each array element is an object with the attributes:* <code class="prettyprint">name</code>: Name of creator in the format Family name, Given names* <code class="prettyprint">type</code>: Contributor type. Controlled vocabulary (<code class="prettyprint">ContactPerson</code>, <code class="prettyprint">DataCollector</code>, <code class="prettyprint">DataCurator</code>, <code class="prettyprint">DataManager</code>,<code class="prettyprint">Distributor</code>, <code class="prettyprint">Editor</code>, <code class="prettyprint">Funder</code>, <code class="prettyprint">HostingInstitution</code>, <code class="prettyprint">Producer</code>, <code class="prettyprint">ProjectLeader</code>, <code class="prettyprint">ProjectManager</code>, <code class="prettyprint">ProjectMember</code>, <code class="prettyprint">RegistrationAgency</code>, <code class="prettyprint">RegistrationAuthority</code>, <code class="prettyprint">RelatedPerson</code>, <code class="prettyprint">Researcher</code>, <code class="prettyprint">ResearchGroup</code>, <code class="prettyprint">RightsHolder</code>,<code class="prettyprint">Supervisor</code>, <code class="prettyprint">Sponsor</code>, <code class="prettyprint">WorkPackageLeader</code>, <code class="prettyprint">Other</code>)* <code class="prettyprint">affiliation</code>: Affiliation of creator (optional).* <code class="prettyprint">orcid</code>: ORCID identifier of creator (optional).* <code class="prettyprint">gnd</code>: GND identifier of creator (optional).Example: <code class="prettyprint">[{'name':'Doe, John', 'affiliation': 'Zenodo', 'type': 'Editor' }, ...]</code></td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">references</code>array of strings</td> <td style="text-align: left">No</td> <td style="text-align: left">List of references.Example: <code class="prettyprint">["Doe J (2014). Title. Publisher. DOI", "Smith J (2014). Title. Publisher. DOI"]</code></td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">communities</code>array of objects</td> <td style="text-align: left">No</td> <td style="text-align: left">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:* <code class="prettyprint">identifier</code>: Community identifierExample: <code class="prettyprint">[{'identifier':'ecfunded'}]</code></td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">grants</code>array of objects</td> <td style="text-align: left">No</td> <td style="text-align: left">List of OpenAIRE-supported grants, which have funded the research for this deposition. Each array element is an object with the attributes:* <code class="prettyprint">id</code>: grant ID.Example: <code class="prettyprint">[{'id':'283595'}]</code> (European Commission grants only)or funder DOI-prefixed: <code class="prettyprint">[{'id': '10.13039/501100000780::283595'}]</code> (All grants, recommended) Accepted funder DOI prefixes: Australian Research Council: <code class="prettyprint">10.13039/501100000923</code> Austrian Science Fund: <code class="prettyprint">10.13039/501100002428</code> European Commission: <code class="prettyprint">10.13039/501100000780</code> European Environment Agency: <code class="prettyprint">10.13039/501100000806</code> Academy of Finland: <code class="prettyprint">10.13039/501100002341</code> Hrvatska Zaklada za Znanost: <code class="prettyprint">10.13039/501100004488</code> Fundação para a Ciência e a Tecnologia: <code class="prettyprint">10.13039/501100001871</code> Ministarstvo Prosvete, Nauke i Tehnološkog Razvoja: <code class="prettyprint">10.13039/501100004564</code> Ministarstvo Znanosti, Obrazovanja i Sporta: <code class="prettyprint">10.13039/501100006588</code> National Health and Medical Research Council: <code class="prettyprint">10.13039/501100000925</code> National Institutes of Health: <code class="prettyprint">10.13039/100000002</code> National Science Foundation: <code class="prettyprint">10.13039/100000001</code> Nederlandse Organisatie voor Wetenschappelijk Onderzoek: <code class="prettyprint">10.13039/501100003246</code> Research Councils: <code class="prettyprint">10.13039/501100000690</code> Schweizerischer Nationalfonds zur Förderung der wissenschaftlichen Forschung: <code class="prettyprint">10.13039/501100001711</code> Science Foundation Ireland: <code class="prettyprint">10.13039/501100001602</code> Wellcome Trust: <code class="prettyprint">10.13039/100004440</code></td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">journal_title</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Journal title, if deposition is a published article.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">journal_volume</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Journal volume, if deposition is a published article.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">journal_issue</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Journal issue, if deposition is a published article.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">journal_pages</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Journal pages, if deposition is a published article.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">conference_title</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Title of conference (e.g. 20th International Conference on Computing in High Energy and Nuclear Physics).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">conference_acronym</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Acronym of conference (e.g. CHEP'13).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">conference_dates</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Dates of conference (e.g. 14-18 October 2013). Conference title or acronym must also be specified if this field is specified.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">conference_place</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">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.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">conference_url</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">URL of conference (e.g. http://www.chep2013.org/).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">conference_session</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Number of session within the conference (e.g. VI).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">conference_session_part</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Number of part within a session (e.g. 1).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">imprint_publisher</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Publisher of a book/report/chapter</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">imprint_isbn</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">ISBN of a book/report</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">imprint_place</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Place of publication of a book/report/chapter in the format city, country.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">partof_title</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Title of book for chapters</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">partof_pages</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Pages numbers of book</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">thesis_supervisors</code>array of objects</td> <td style="text-align: left">No</td> <td style="text-align: left">Supervisors of the thesis. Same format as for <code class="prettyprint">creators</code>.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">thesis_university</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Awarding university of thesis.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">subjects</code>array of objects</td> <td style="text-align: left">No</td> <td style="text-align: left">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:* <code class="prettyprint">term</code>: Term from taxonomy or controlled vocabulary.* <code class="prettyprint">identifier</code>: Unique identifier for term.* <code class="prettyprint">scheme</code>: Persistent identifier scheme for id (automatically detected).Example: <code class="prettyprint">[{"term": "Astronomy", "identifier": "http://id.loc.gov/authorities/subjects/sh85009003", "scheme": "url"}]</code></td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">version</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Version of the resource. Any string will be accepted, however the suggested format is a semantically versioned tag (see more details on semantic versioning at <a href="https://web.archive.org/web/20210812203808/http://semver.org/">semver.org</a>)Example: <code class="prettyprint">2.1.5</code></td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">language</code>string</td> <td style="text-align: left">No</td> <td style="text-align: left">Specify the main language of the record as ISO 639-2 or 639-3 code, see <a href="https://web.archive.org/web/20210812203808/https://www.loc.gov/standards/iso639-2/php/code_list.php">Library of Congress ISO 639 codes list</a>.Example: <code class="prettyprint">eng</code></td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">locations</code>array of objects</td> <td style="text-align: left">No</td> <td style="text-align: left">List of locations* <code class="prettyprint">lat (double):</code> latitude * <code class="prettyprint">lon (double):</code> longitude* <code class="prettyprint">place (string):</code> place’s name (required)* <code class="prettyprint">description (string):</code> place’s description (optional)Example: <code class="prettyprint">[{"lat": 34.02577, "lon": -118.7804, "place": "Los Angeles"}, {"place": "Mt.Fuji, Japan", "description": "Sample found 100ft from the foot of the mountain."}]</code></td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">dates</code>array of objects</td> <td style="text-align: left">No</td> <td style="text-align: left">List of date intervals* <code class="prettyprint">start (ISO date string):</code> start date (*) * <code class="prettyprint">end (ISO date string):</code> end date (*)* <code class="prettyprint">type (Collected, Valid, Withdrawn):</code> The interval’s type (required)* <code class="prettyprint">description (string):</code> The interval’s description (optional)(*) Note that you have to specify at least a start or end date. For an exact date, use the same value for both <code class="prettyprint">start</code> and <code class="prettyprint">end</code>.Example: <code class="prettyprint">[{"start": "2018-03-21", "end": "2018-03-25", "type": "Collected", "description": "Specimen A5 collection period."}]</code></td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">method</code>string (allows HTML)</td> <td style="text-align: left">No</td> <td style="text-align: left">The methodology employed for the study or research.</td> </tr> </tbody></table> <aside class="notice"> For string fields that allow HTML (e.g. <code>description</code>, <code>notes</code>), for security reasons, only the following tags are accepted: <code>a</code>, <code>abbr</code>, <code>acronym</code>, <code>b</code>, <code>blockquote</code>, <code>br</code>, <code>code</code>, <code>div</code>, <code>em</code>, <code>i</code>, <code>li</code>, <code>ol</code>, <code>p</code>, <code>pre</code>, <code>span</code>, <code>strike</code>, <code>strong</code>, <code>sub</code>, <code>sup</code>, <code>u</code>, <code>ul</code>. </aside> <h3 id="list">List</h3> List all depositions for the currently authenticated user. <pre class="highlight python"><code>import requests response = requests.get('/api/deposit/depositions', params={'q': 'my title', 'access_token': ACCESS_TOKEN}) print(response.json()) </code></pre><pre class="highlight shell"><code>curl -i /api/deposit/depositions/?access_token=ACCESS_TOKEN </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">GET /api/deposit/depositions</code> <h4 id="query-arguments">Query arguments</h4> <table><thead> <tr> <th style="text-align: left">Parameter</th> <th style="text-align: left">Required</th> <th style="text-align: left">Description</th> </tr> </thead><tbody> <tr> <td style="text-align: left"><code class="prettyprint">q</code>string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Search query (using Elasticsearch query string syntax).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">status</code>string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Filter result based on deposit status (either <code class="prettyprint">draft</code> or <code class="prettyprint">published</code>)</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">sort</code>string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Sort order (<code class="prettyprint">bestmatch</code> or <code class="prettyprint">mostrecent</code>). Prefix with minus to change form ascending to descending (e.g. <code class="prettyprint">-mostrecent</code>).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">page</code>integer</td> <td style="text-align: left">optional</td> <td style="text-align: left">Page number for pagination.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">size</code>integer</td> <td style="text-align: left">optional</td> <td style="text-align: left">Number of results to return per page.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">all_versions</code>integer/string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Show (<code class="prettyprint">true</code> or <code class="prettyprint">1</code>) or hide (<code class="prettyprint">false</code> or <code class="prettyprint">0</code>) all versions of deposits.</td> </tr> </tbody></table> <h4 id="success-response">Success Response</h4> <ul> <li>Code: <code class="prettyprint">200 OK</code></li> <li>Body: an array of <a href="#deposit">deposition</a> resources.</li> </ul> <h4 id="error-response">Error Response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h3 id="create">Create</h3> Create a new deposition resource. <pre class="highlight shell"><code>curl -i -H "Content-Type: application/json" -X POST --data '{}' /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"}]}}' /api/deposit/depositions/?access_token=ACCESS_TOKEN </code></pre><pre class="highlight python"><code>import json import requests url = "/api/deposit/depositions/?access_token=ACCESS_TOKEN" headers = {"Content-Type": "application/json"} r = requests.post(url, data="{}", headers=headers) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">POST /api/deposit/depositions</code> <h4 id="request-headers">Request headers</h4> <code class="prettyprint">Content-Type: application/json</code> <h4 id="data">Data</h4> An empty JSON object <code class="prettyprint">{}</code> or a <a href="#deposit-metadata">deposition metadata</a> resource. Example: <code class="prettyprint">{"metadata": {"upload_type": "presentation" } }</code> <h4 id="scopes">Scopes</h4> <code class="prettyprint">deposit:write</code> <h4 id="success-response">Success Response</h4> <ul> <li>Code: <code class="prettyprint">201 Created</code></li> <li>Body: a <a href="#deposit">deposition</a> resource.</li> </ul> <h4 id="error-response">Error Response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h3 id="retrieve">Retrieve</h3> Retrieve a single deposition resource. <pre class="highlight shell"><code>curl -i /api/deposit/depositions/1234?access_token=ACCESS_TOKEN </code></pre><pre class="highlight python"><code>import requests r = requests.get("/api/deposit/depositions/1234?access_token=ACCESS_TOKEN") </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">GET /api/deposit/depositions/:id</code> <h4 id="success-response">Success response</h4> <ul> <li>Code: <code class="prettyprint">200 OK</code></li> <li>Body: a <a href="#deposit">deposition</a> resource.</li> </ul> <h4 id="error-response">Error response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. | <h3 id="update">Update</h3> Update an existing deposition resource. <pre class="highlight shell"><code>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 </code></pre><pre class="highlight python"><code>import json import requests data = { "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) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">PUT /api/deposit/depositions/:id</code> <h4 id="request-headers">Request headers</h4> <code class="prettyprint">Content-Type: application/json</code> <h4 id="scopes">Scopes</h4> <code class="prettyprint">deposit:write</code> <div class="align-columns"></div> <pre class="highlight json"><code>{ "metadata": { "upload_type": "presentation", "...": "..." } } </code></pre> <h4 id="data-parameters">Data parameters</h4> A <a href="#deposit-metadata">deposition metadata</a> resource. <h4 id="success-response">Success response</h4> <ul> <li>Code: <code class="prettyprint">200 OK</code></li> <li>Body: a <a href="#deposit">deposition</a> resource.</li> </ul> <h4 id="error-response">Error response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h3 id="delete">Delete</h3> Delete an existing deposition resource. Note, only unpublished depositions may be deleted. <pre class="highlight shell"><code>curl -i https://zenodo.org/api/deposit/depositions/1234?access_token=ACCESS_TOKEN -X DELETE </code></pre><pre class="highlight python"><code>import requests r = requests.delete('https://zenodo.org/api/deposit/depositions/1234', params={'access_token': ACCESS_TOKEN}) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">DELETE /api/deposit/depositions/:id</code> <h4 id="scopes">Scopes</h4> <code class="prettyprint">deposit:write</code> <h4 id="success-response">Success Response</h4> <ul> <li>Code: <code class="prettyprint">201 Created</code></li> <li>Body: Empty.</li> </ul> <h4 id="error-response">Error Response</h4> <ul> <li><code class="prettyprint">404 Not found</code>: Deposition does not exist.</li> <li><code class="prettyprint">403 Forbidden</code>: Deleting an already published deposition.</li> </ul> See also <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h2 id="deposition-files">Deposition files</h2> <aside class="notice"> Heads up! We will be launching a new file API which is significant more performant than the current API and which supports much larger file sizes. The current API supports 100MB per file, the new supports 50GB per file. </aside> <h3 id="representation">Representation</h3> The Deposition file resource is used for uploading and editing files of a deposition on Zenodo. <h4 id="deposition-file">Deposition File</h4> <table><thead> <tr> <th style="text-align: left">Attribute</th> <th style="text-align: left">Description</th> </tr> </thead><tbody> <tr> <td style="text-align: left"><code class="prettyprint">id</code>string</td> <td style="text-align: left">Deposition file identifier</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">filename</code>string</td> <td style="text-align: left">Name of file</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">filesize</code>integer</td> <td style="text-align: left">Size of file in bytes</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">checksum</code>string</td> <td style="text-align: left">MD5 checksum of file, computed by our system. This allows you to check the integrity of the uploaded file.</td> </tr> </tbody></table> <h3 id="list">List</h3> List all deposition files for a given deposition. <pre class="highlight shell"><code>curl -i https://zenodo.org/api/deposit/depositions/1234/files?access_token=ACCESS_TOKEN </code></pre><pre class="highlight python"><code>import requests r = requests.get('https://zenodo.org/api/deposit/depositions/1234/files', params={'access_token': ACCESS_TOKEN}) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">GET /api/deposit/depositions/:id/files</code> <h4 id="success-response">Success response</h4> <ul> <li>Code: <code class="prettyprint">200 OK</code></li> <li>Body: an array of <a href="#deposition-file">deposition file</a> resources.</li> </ul> <h4 id="error-response">Error response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h3 id="create">Create</h3> Upload a new file. <pre class="highlight shell"><code>curl -i https://zenodo.org/api/deposit/depositions/1234/files?access_token=ACCESS_TOKEN -F name=myfirstfile.csv -F file=@path/to/local_file.csv </code></pre><pre class="highlight python"><code>import json import requests url = '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) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">POST /api/deposit/depositions/:id/files</code> <h4 id="request-headers">Request headers</h4> <code class="prettyprint">Content-Type: multipart/form-data</code> <h4 id="scopes">Scopes</h4> <code class="prettyprint">deposit:write</code> <h4 id="success-response">Success response</h4> <ul> <li>Code: <code class="prettyprint">201 Created</code></li> <li>Body: a <a href="#deposition-file">deposition file</a> resource.</li> </ul> <h4 id="error-response">Error response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h3 id="sort">Sort</h3> Sort the files for a deposition. By default, the first file is shown in the file preview. <pre class="highlight shell"><code>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"}]' </code></pre><pre class="highlight python"><code>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) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">PUT /api/deposit/depositions/:id/files</code> <h4 id="request-headers">Request headers</h4> <code class="prettyprint">Content-Type: application/json</code> <h4 id="scopes">Scopes</h4> <code class="prettyprint">deposit:write</code> <h4 id="data">Data</h4> A JSON array of partial <a href="#deposition-file">deposition file</a> resources with only the <code class="prettyprint">id</code> attribute. Example: <pre class="highlight json"><code>[ {"id": "<file_id_1>"}, {"id": "<file_id_2>"}, "..." ] </code></pre> <h4 id="success-response">Success response</h4> <ul> <li>Code: <code class="prettyprint">200 OK</code></li> <li>Body: an array of <a href="#deposition-file">deposition file</a> resources.</li> </ul> <h4 id="error-response">Error response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h3 id="retrieve">Retrieve</h3> Retrieve a single deposition file. <pre class="highlight shell"><code>curl -i https://zenodo.org/api/deposit/depositions/1234/files/12345678-9abc-def1-2345-6789abcdef12?access_token=ACCESS_TOKEN </code></pre><pre class="highlight python"><code>import requests r = requests.get('https://zenodo.org/api/deposit/depositions/1234/files/12345678-9abc-def1-2345-6789abcdef12', params={'access_token': ACCESS_TOKEN}) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">GET /api/deposit/depositions/:id/files/:file_id</code> <h4 id="success-response">Success Response</h4> <ul> <li>Code: <code class="prettyprint">200 OK</code></li> <li>Body: a <a href="#deposition-file">deposition file</a> resource.</li> </ul> <h4 id="error-response">Error response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h3 id="update">Update</h3> 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. <pre class="highlight shell"><code>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"}' </code></pre><pre class="highlight python"><code>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 = {"name": "someothername.csv"} r = requests.put(url, data=json.dumps(data), headers=headers) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">PUT /api/deposit/depositions/:id/files/:file_id</code> <h4 id="request-headers">Request headers</h4> <code class="prettyprint">Content-Type: application/json</code> <h4 id="scopes">Scopes</h4> <code class="prettyprint">deposit:write</code> <h4 id="data">Data</h4> A partial <a href="#deposition-file">deposition file</a> resources with only the <code class="prettyprint">filename</code> attributes. Example: <pre class="highlight json"><code>{ "name": "<new_file_name>" } </code></pre> <h4 id="success-response">Success response</h4> <ul> <li>Code: <code class="prettyprint">200 OK</code></li> <li>Body: a <a href="#deposition-file">deposition file</a> resource.</li> </ul> <h4 id="error-response">Error response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h3 id="delete">Delete</h3> Delete an existing deposition file resource. Note, only deposition files for unpublished depositions may be deleted. <pre class="highlight shell"><code>curl -i -X DELETE https://zenodo.org/api/deposit/depositions/1234/files/21fedcba-9876-5432-1fed-cba987654321?access_token=ACCESS_TOKEN </code></pre><pre class="highlight python"><code>import requests r = requests.delete('https://zenodo.org/api/deposit/depositions/1234/files/21fedcba-9876-5432-1fed-cba987654321', params={'access_token': ACCESS_TOKEN}) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">DELETE /api/deposit/depositions/:id/files/:file_id</code> <h4 id="scopes">Scopes</h4> <code class="prettyprint">deposit:write</code> <h4 id="success-response">Success response</h4> <ul> <li>Code: <code class="prettyprint">204 No Content</code></li> <li>Body: Empty.</li> </ul> <h4 id="error-response">Error response</h4> <ul> <li><code class="prettyprint">404 Not found</code>: Deposition file does not exist.</li> <li><code class="prettyprint">403 Forbidden</code>: Deleting an already published deposition.</li> </ul> See also <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h2 id="deposition-actions">Deposition actions</h2> <h3 id="publish">Publish</h3> Publish a deposition. Note, once a deposition is published, you can no longer delete it. <pre class="highlight shell"><code>curl -i -X POST https://zenodo.org/api/deposit/depositions/1234/actions/publish?access_token=ACCESS_TOKEN </code></pre><pre class="highlight python"><code>import requests r = requests.post('https://zenodo.org/api/deposit/depositions/1234/actions/publish', params={'access_token': ACCESS_TOKEN}) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">POST /api/deposit/depositions/:id/actions/publish</code> <h4 id="scopes">Scopes</h4> <code class="prettyprint">deposit:actions</code> <h4 id="success-response">Success response</h4> <ul> <li>Code: <code class="prettyprint">202 Accepted</code></li> <li>Body: a <a href="#deposit">deposition</a> resource.</li> </ul> <h4 id="error-response">Error response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h3 id="edit">Edit</h3> Unlock already submitted deposition for editing. <pre class="highlight shell"><code>curl -i -X POST https://zenodo.org/api/deposit/depositions/1234/actions/edit?access_token=ACCESS_TOKEN </code></pre><pre class="highlight python"><code>import requests r = requests.post('https://zenodo.org/api/deposit/depositions/1234/actions/edit', params={'access_token': ACCESS_TOKEN}) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">POST /api/deposit/depositions/:id/actions/edit</code> <h4 id="scopes">Scopes</h4> <code class="prettyprint">deposit:actions</code> <h4 id="success-response">Success response</h4> <ul> <li>Code: <code class="prettyprint">201 Created</code></li> <li>Body: a <a href="#deposit">deposition</a> resource.</li> </ul> <h4 id="error-response">Error response</h4> <ul> <li><code class="prettyprint">400 Bad Request</code>: Deposition state does not allow for editing (e.g. depositions in state <code class="prettyprint">inprogress</code>).</li> <li><code class="prettyprint">409 Conflict</code>: Deposition is in the process of being integrated, please wait 5 minutes before trying again.</li> </ul> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h3 id="discard">Discard</h3> Discard changes in the current editing session. <pre class="highlight shell"><code>curl -i -X POST https://zenodo.org/api/deposit/depositions/1234/actions/discard?access_token=ACCESS_TOKEN </code></pre><pre class="highlight python"><code>import requests r = requests.post('https://zenodo.org/api/deposit/depositions/1234/actions/discard', params={'access_token': ACCESS_TOKEN}) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">POST /api/deposit/depositions/:id/actions/discard</code> <h4 id="scopes">Scopes</h4> <code class="prettyprint">deposit:actions</code> <h4 id="success-response">Success response</h4> <ul> <li>Code: <code class="prettyprint">201 Created</code></li> <li>Body: a <a href="#deposit">deposition</a> resource.</li> </ul> <h4 id="error-response">Error response</h4> <ul> <li><code class="prettyprint">400 Bad Request</code>: Deposition is not being edited.</li> </ul> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h3 id="new-version">New version</h3> 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 <code class="prettyprint">"latest_draft"</code> under <code class="prettyprint">"links"</code> in the response body. - The <code class="prettyprint">id</code> used to create this new version has to be the <code class="prettyprint">id</code> of the latest version. It is not possible to use the global id that references all the versions. <pre class="highlight shell"><code>curl -i -X POST https://zenodo.org/api/deposit/depositions/1234/actions/newversion?access_token=ACCESS_TOKEN </code></pre><pre class="highlight python"><code>import requests r = requests.post('https://zenodo.org/api/deposit/depositions/1234/actions/newversion', params={'access_token': ACCESS_TOKEN}) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">POST /api/deposit/depositions/:id/actions/newversion</code> <h4 id="scopes">Scopes</h4> <code class="prettyprint">deposit:actions</code> <h4 id="success-response">Success response</h4> <ul> <li>Code: <code class="prettyprint">201 Created</code></li> <li>Body: a <a href="#deposit">deposition</a> resource.</li> </ul> <h4 id="error-response">Error response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h2 id="records">Records</h2> <h3 id="representation">Representation</h3> The Records resource is used to search through published records. <h3 id="list">List</h3> List all open access records. <pre class="highlight python"><code>import requests response = requests.get('https://zenodo.org/api/records', params={'q': 'my title', 'access_token': ACCESS_TOKEN}) print(response.json()) </code></pre><pre class="highlight shell"><code>curl -i /api/records/?access_token=ACCESS_TOKEN </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">GET /api/records/</code> <h4 id="query-arguments">Query arguments</h4> <table><thead> <tr> <th style="text-align: left">Parameter</th> <th style="text-align: left">Required</th> <th style="text-align: left">Description</th> </tr> </thead><tbody> <tr> <td style="text-align: left"><code class="prettyprint">q</code>string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Search query (using Elasticsearch query string syntax).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">status</code>string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Filter result based on the deposit status (either <code class="prettyprint">draft</code> or <code class="prettyprint">published</code>)</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">sort</code>string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Sort order (<code class="prettyprint">bestmatch</code> or <code class="prettyprint">mostrecent</code>). Prefix with minus to change form ascending to descending (e.g. <code class="prettyprint">-mostrecent</code>).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">page</code>integer</td> <td style="text-align: left">optional</td> <td style="text-align: left">Page number for pagination.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">size</code>integer</td> <td style="text-align: left">optional</td> <td style="text-align: left">Number of results to return per page.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">all_versions</code>integer/string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Show (<code class="prettyprint">true</code> or <code class="prettyprint">1</code>) or hide (<code class="prettyprint">false</code> or <code class="prettyprint">0</code>) all versions of records.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">communities</code> string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Return records that are part of the specified communities. (Use of <code class="prettyprint">community identifier</code>)</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">type</code> string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Return records of the specified type. (<code class="prettyprint">Publication</code>, <code class="prettyprint">Poster</code>, <code class="prettyprint">Presentation</code>…)</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">subtype</code> string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Return records of the specified subtype. (<code class="prettyprint">Journal article</code>, <code class="prettyprint">Preprint</code>, <code class="prettyprint">Proposal</code>…)</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">bounds</code> string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Return records filtered by a geolocation bounding box. (Format <code class="prettyprint">bounds=143.37158,-38.99357,146.90918,-37.35269</code>)</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">custom</code> string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Return records containing the specified custom keywords. (Format <code class="prettyprint">custom=[field_name]:field_value</code>)</td> </tr> </tbody></table> <h4 id="header">Header</h4> The response format of the search can be requested by specifying it in the header. <table><thead> <tr> <th style="text-align: left">Accept</th> <th style="text-align: left">Description</th> </tr> </thead><tbody> <tr> <td style="text-align: left"><code class="prettyprint">application/json</code></td> <td style="text-align: left">JSON</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">application/vnd.zenodo.v1+json</code></td> <td style="text-align: left">Zenodo</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">application/marcxml+xml</code></td> <td style="text-align: left">Marc XML</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">application/x-bibtex</code></td> <td style="text-align: left">Bibtex</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">application/x-datacite+xml</code></td> <td style="text-align: left">Datacite XML</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">application/x-dc+xml</code></td> <td style="text-align: left">Dublin Core</td> </tr> </tbody></table> <h4 id="success-response">Success Response</h4> <ul> <li>Code: <code class="prettyprint">200 OK</code></li> <li>Body: an array of <a href="#records">record</a> resources.</li> </ul> <h4 id="error-response">Error Response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. <h4 id="search-guide">Search guide</h4> Advanced search queries can as well be performed on Zenodo website through the search box. This is documented in the <a href="https://web.archive.org/web/20210812203808/https://help.zenodo.org/guides/search/">search guide</a> <h3 id="retrieve">Retrieve</h3> Retrieve a single record. <pre class="highlight shell"><code>curl -i https://zenodo.org/api/records/1234 </code></pre><pre class="highlight python"><code>import requests r = requests.get("https://zenodo.org/api/records/1234) </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">GET https://zenodo.org/api/records/:id</code> Again, the output format of the search can be specified in the <a href="#header">header</a> <h4 id="success-response">Success response</h4> <ul> <li>Code: <code class="prettyprint">200 OK</code></li> <li>Body: a <a href="#records">record</a>.</li> </ul> <h4 id="error-response">Error response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. | <h2 id="licenses">Licenses</h2> <h3 id="representation">Representation</h3> The License resource is used for serving the license metadata that can be applied to uploaded content on Zenodo. <h4 id="license">License</h4> <table><thead> <tr> <th style="text-align: left">Field</th> <th style="text-align: left">Description</th> </tr> </thead><tbody> <tr> <td style="text-align: left"><code class="prettyprint">created</code>timestamp</td> <td style="text-align: left">Creation time of the license (in ISO8601 format).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">updated</code>timestamp</td> <td style="text-align: left">Last modification time of deposition (in ISO8601 format).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">metadata</code>object</td> <td style="text-align: left">The <a href="#license-metadata">license metadata</a> resource</td> </tr> </tbody></table> <h4 id="license-metadata">License metadata</h4> <table><thead> <tr> <th style="text-align: left">Attribute</th> <th style="text-align: left">Description</th> </tr> </thead><tbody> <tr> <td style="text-align: left"><code class="prettyprint">id</code>string</td> <td style="text-align: left">Identifier for the license.Example: <code class="prettyprint">cc-by-nc-4.0</code></td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">title</code>string</td> <td style="text-align: left">The name of the licenseExample: GNU Lesser General Public License v3.0</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">url</code>string</td> <td style="text-align: left">URL of the licenseExample: <a href="https://web.archive.org/web/20210812203808/http://www.opensource.org/licenses/MIT">http://www.opensource.org/licenses/MIT</a></td> </tr> </tbody></table> <h3 id="list">List</h3> Search through licenses. <pre class="highlight python"><code>import requests response = requests.get('/api/licenses/') print(response.json()) </code></pre><pre class="highlight shell"><code>curl /api/licenses/ </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">GET /api/licenses/</code> <h4 id="query-arguments">Query arguments</h4> <table><thead> <tr> <th style="text-align: left">Parameter</th> <th style="text-align: left">Required</th> <th style="text-align: left">Description</th> </tr> </thead><tbody> <tr> <td style="text-align: left"><code class="prettyprint">q</code>string</td> <td style="text-align: left">optional</td> <td style="text-align: left">Search query (using Elasticsearch query string syntax).</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">page</code>integer</td> <td style="text-align: left">optional</td> <td style="text-align: left">Page number for pagination.</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">size</code>integer</td> <td style="text-align: left">optional</td> <td style="text-align: left">Number of results to return per page.</td> </tr> </tbody></table> <h4 id="success-response">Success Response</h4> <ul> <li>Code: <code class="prettyprint">200 OK</code></li> <li>Body: an array of <a href="#license">license</a> resources.</li> </ul> <h4 id="error-response">Error response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. | <h3 id="retrieve">Retrieve</h3> Retrieve a single license resource. <pre class="highlight python"><code>import requests r = requests.get("/api/licenses/cc-by-nc-4.0") </code></pre><pre class="highlight shell"><code>curl /api/licenses/cc-by-nc-4.0 </code></pre> <h4 id="http-request">HTTP Request</h4> <code class="prettyprint">GET /api/licenses/:id</code> <h4 id="success-response">Success response</h4> <ul> <li>Code: <code class="prettyprint">200 OK</code></li> <li>Body: a <a href="#license">license</a> resource.</li> </ul> <h4 id="error-response">Error response</h4> See <a href="#http-status-codes">HTTP status codes</a> (400 and 500 series errors) and <a href="#errors">error responses</a>. | <h2 id="changes">Changes</h2> 2017-10-04 <ul> <li>Added new optional field <code class="prettyprint">version</code> to deposition metadata.</li> <li>Added new optional field <code class="prettyprint">language</code> to deposition metadata.</li> </ul> 2017-06-15 <ul> <li>Added support for DOI versioning as part of deposit actions.</li> </ul> 2016-09-12 <ul> <li>Added support for search, pagination, sorting and filtering.</li> <li>Improved speed significantly.</li> </ul> 2015-10-06 <ul> <li>Added new optional field <code class="prettyprint">contributors</code> to deposition metadata.</li> <li>Added new optional field <code class="prettyprint">subjects</code> to deposition metadata.</li> <li>Added new optional subfield <code class="prettyprint">gnd</code> to <code class="prettyprint">creators</code> in deposition metadata.</li> </ul> 2014-12-20 <ul> <li>Added new relationship <code class="prettyprint">isAlternateIdentifier</code> in subfield <code class="prettyprint">relation</code> to <code class="prettyprint">related_identifiers</code> in deposition metadata.</li> </ul> 2014-12-10 <ul> <li>Added new relationships <code class="prettyprint">hasPart</code>, <code class="prettyprint">isPartOf</code> & <code class="prettyprint">isIdenticalTo</code> in subfield <code class="prettyprint">relation</code> to <code class="prettyprint">related_identifiers</code> in deposition metadata.</li> </ul> 2014-11-20 <ul> <li>Added new optional subfield <code class="prettyprint">orcid</code> to <code class="prettyprint">creators</code> in deposition metadata.</li> </ul> 2014-10-21 <ul> <li>Added new optional fields <code class="prettyprint">conference_session</code> and <code class="prettyprint">conference_session_part</code> to deposition metadata.</li> </ul> 2014-09-09 <ul> <li>Added new optional field <code class="prettyprint">references</code> to deposition metadata.</li> </ul> 2014-06-13 <ul> <li>Authentication changed from API keys to OAuth 2.0. API key authentication is deprecated and will be phased out in October, 2014. Please use <a href="#creating-a-personal-access-token">personal access tokens</a> instead of API keys.</li> </ul> 2013-12-18 REST API version 1.0 final release: <ul> <li>Deposition actions moved from <code class="prettyprint">deposit/depositions/:id/action</code> to <code class="prettyprint">deposit/depositions/:id/actions</code></li> <li>Added <code class="prettyprint">edit</code> and <code class="prettyprint">discard</code> deposition action resources.</li> <li>Deposition resource representation: <ul> <li><code class="prettyprint">state</code>: Controlled vocabulary changed.</li> <li><code class="prettyprint">submitted</code>: Data type changed from Timestamp to Bool.</li> </ul></li> </ul> 2013-11-13 REST API initial release candidate. <h1 id="oai-pmh">OAI-PMH</h1> Zenodo allows you to harvest our entire repository via the Open Archives Initiative Protocol for Metadata Harvesting (<a href="https://web.archive.org/web/20210812203808/http://www.openarchives.org/pmh/">OAI- PMH</a>). 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 <a href="https://web.archive.org/web/20210812203808/http://about.zenodo.org/terms">Creative Commons Zero</a>, 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. <h2 id="base-url">Base URL</h2> <code class="prettyprint">https://zenodo.org/oai2d</code> <h2 id="resumption-tokens">Resumption tokens</h2> Resumption tokens are only valid for 2 minutes. In case a token expired, you will receive a <code class="prettyprint">422 Unprocessable Entity</code> HTTP error. <aside class="notice"> This means that you must execute the next HTTP request using the resumption token within those two minutes. We recommend that you offload any post processing of the harvested record to a background queue. </aside> <h2 id="rate-limit">Rate limit</h2> The OAI-PMH API is rated limited like the REST API - i.e. you will receive a <code class="prettyprint">429 Too Many Requests</code> HTTP error if you exceed the limit. <h2 id="metadata-formats">Metadata formats</h2> Metadata for each record is available in several formats. The available formats include: <code class="prettyprint">oai_datacite</code> OAI DataCite (latest schema version) — 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 <a href="https://web.archive.org/web/20210812203808/http://oai.datacite.org/">DataCite OAI schema</a> website. This metadata format will always deliver metadata according to the latest available DataCite schema version. <a href="https://web.archive.org/web/20210812203808/https://zenodo.org/oai2d?verb=ListRecords&metadataPrefix=oai_datacite&set=openaire_data">See example</a> <aside class="notice"> To get the raw XML output of the example above, view the page’s source using the web browser’s “view source” option. </aside> <aside class="success"> We recommend you harvest using the “oai_datacite” metadata format. The format contains the most complete metadata and is our primary supported export format. </aside> <code class="prettyprint">oai_datacite3</code> 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 <a href="https://web.archive.org/web/20210812203808/http://oai.datacite.org/">DataCite OAI schema</a> web site. <aside class="notice"> Heads up! We will be upgrading to <a href="https://web.archive.org/web/20210812203808/http://schema.datacite.org/meta/kernel-4/index.html">DataCite Metadata Schema v4.0</a> and discontinue support for DataCite v3.0 by end February 2018, hence please ensure your OAI-PMH client are capable of reading both versions. There are only few backwards incompatible changes between v4.0 and v3.0. </aside> <a href="https://web.archive.org/web/20210812203808/https://zenodo.org/oai2d?verb=ListRecords&metadataPrefix=oai_datacite3&set=openaire_data">See example</a> <code class="prettyprint">datacite</code> DataCite (latest version) — This metadata format contains only the original DataCite metadata without additions or alterations according to the latest DataCite schema. Please note that this format is not OAI-PMH version 2.0 compliant. <a href="https://web.archive.org/web/20210812203808/https://zenodo.org/oai2d?verb=ListRecords&metadataPrefix=datacite&set=openaire_data">See example</a> <code class="prettyprint">datacite3</code> 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. <aside class="notice"> Heads up! We will discontinue support for DataCite v3.0 by end February 2018. </aside> <a href="https://web.archive.org/web/20210812203808/https://zenodo.org/oai2d?verb=ListRecords&metadataPrefix=datacite3&set=openaire_data">See example</a> <code class="prettyprint">oai_dc</code> Dublin Core — only minimal metadata is included in this format. The format is exported according to the <a href="http;//guidelines.openaire.eu">OpenAIRE Guidelines</a>. <a href="https://web.archive.org/web/20210812203808/https://zenodo.org/oai2d?verb=ListRecords&metadataPrefix=oai_dc&set=openaire">See example</a> <code class="prettyprint">marc21</code> MARC21 — export format primarily supported for legacy reasons. Please consider using one of the other export formats as we may discontinue support for MARC21. <a href="https://web.archive.org/web/20210812203808/https://zenodo.org/oai2d?verb=ListRecords&metadataPrefix=marc21&set=openaire">See example</a> <h2 id="sets">Sets</h2> We support both harvesting of the entire repository as well as selective harvesting of communities. Entire repository In order to harvest the entire repository you make an OAI-PMH request without passing any set specification. <a href="https://web.archive.org/web/20210812203808/https://zenodo.org/oai2d?verb=ListRecords&metadataPrefix=oai_datacite">See example</a> <code class="prettyprint">user-<identifier></code> Community sets — allows selective harvesting of specific communities. Replace <code class="prettyprint"><identifier></code> with the community identifier. Alternatively each community provides a direct harvesting API link on their front-page, which includes the correct community identifier. <a href="https://web.archive.org/web/20210812203808/https://zenodo.org/oai2d?verb=ListRecords&metadataPrefix=oai_datacite&set=user-cfa">See example</a> If you need selective harvesting and your use case is not supported by above sets, please <a href="https://web.archive.org/web/20210812203808/http://about.zenodo.org/contact/">contact us</a> and we may possible create a specific set for you. <h2 id="update-schedule">Update schedule</h2> Most updates are available immediately, some few updates are only reflected in the OAI sets once an hour. <h2 id="changes">Changes</h2> 2016-09-12 <ul> <li>Deprecated metadata formats <code class="prettyprint">datacite3</code> and <code class="prettyprint">oai_datacite3</code>. End of life is February 2018.</li> <li>Removed rate limit of 0.5 requests/second.</li> <li>Changed resumption token expiry to two minutes due to major update of our underlying repository software.</li> </ul> 2014-03-10 <ul> <li>Added metadata formats <code class="prettyprint">datacite3</code> and <code class="prettyprint">oai_datacite3</code> to support DataCite v3.0.</li> </ul> 2013-05-08 Initial release of OAI-PMH API. <h1 id="github">GitHub</h1> <h2 id="add-metadata-to-your-github-repository-release">Add metadata to your GitHub repository release</h2> 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 <code class="prettyprint">.zenodo.json</code> file at the root of your GitHub repository. The contents of the <code class="prettyprint">.zenodo.json</code> file are based on our <a href="https://web.archive.org/web/20210812203808/https://developers.zenodo.org/#deposit-metadata">deposit metadata documentation</a> and can be structurally validated by our <a href="https://web.archive.org/web/20210812203808/https://zenodo.org/schemas/deposits/records/legacyrecord.json">deposit JSON Schema</a>. In the example shown, we add metadata regarding: <ul> <li>software authorship and ORCiDs, via the <code class="prettyprint">creators</code> field</li> <li>Apache-2.0 licensing, via the <code class="prettyprint">license</code> field</li> <li>a custom title, via the <code class="prettyprint">title</code> field</li> <li>a related identifier to the software paper, via the <code class="prettyprint">related_identifiers</code> field</li> <li>keywords, via the <code class="prettyprint">keywords</code> field</li> <li>Zenodo communities, via the <code class="prettyprint">communities</code> field</li> <li>funding information, via the <code class="prettyprint">grants</code> field</li> </ul> <pre class="highlight python"><code>{ "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": { "type": "publication", "subtype": "article" } } ], "keywords": ["Cats", "Laser", "Behavior"], "communities": [ {"identifier": "software-cats"} ], "grants": [{"id":"777541"}] } </code></pre> <h2 id="how-to-verify-your-quot-zenodo-json-quot-file">How to verify your “.zenodo.json” file?</h2> After creating your <code class="prettyprint">.zenodo.json</code> file you should validate it to make sure that it contains valid JSON. You can use a tool like the <a href="https://web.archive.org/web/20210812203808/https://jsonformatter.curiousconcept.com/">JSON Formatter & Validator</a>, or load it via your favorite programming language. <h1 id="rate-limiting">Rate Limiting</h1> 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. <table><thead> <tr> <th style="text-align: left">Pages</th> <th style="text-align: left">Limitations</th> </tr> </thead><tbody> <tr> <td style="text-align: left">Global limit for guest users</td> <td style="text-align: left">60 requests per minute, 2000 requests per hour</td> </tr> <tr> <td style="text-align: left">Global limit for <a href="#authentication">authenticated users</a></td> <td style="text-align: left">100 requests per minute, 5000 requests per hour</td> </tr> <tr> <td style="text-align: left">OAI-PMH API harvesting</td> <td style="text-align: left">120 requests per minute</td> </tr> <tr> <td style="text-align: left">Thumbnails for image records</td> <td style="text-align: left">20 requests per minute</td> </tr> </tbody></table> 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: <table><thead> <tr> <th style="text-align: left">HTTP header</th> <th style="text-align: left">Description</th> </tr> </thead><tbody> <tr> <td style="text-align: left"><code class="prettyprint">X-RateLimit-Limit</code></td> <td style="text-align: left">Current rate-limit policy, i.e. maximum number of requests per minute</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">X-RateLimit-Remaining</code></td> <td style="text-align: left">Number of requests remaining in the current rate limit</td> </tr> <tr> <td style="text-align: left"><code class="prettyprint">X-RateLimit-Reset</code></td> <td style="text-align: left">Reset time of the current rate limit</td> </tr> </tbody></table> </div> <div class="dark-box"> <div class="lang-selector"> <a href="#" data-language-name="python">Python</a> <a href="#" data-language-name="shell">cURL</a> </div> </div> </div> </div> </body> </html>