Zenodo Skill

Zenodo Skill

Interact with the Zenodo REST API to deposit, publish, version, and search research artifacts. Zenodo issues a citable DOI for every published record.

When to use

Setup

Two environments — pick one and stick with it during a session:

| Env | Base URL | Token page | |---|---|---| | Production | https://zenodo.org/api | https://zenodo.org/account/settings/applications/tokens/new/ | | Sandbox (testing) | https://sandbox.zenodo.org/api | https://sandbox.zenodo.org/account/settings/applications/tokens/new/ |

Sandbox accounts/tokens are separate from production. Always test new workflows in sandbox first — published production records cannot be deleted.

Required token scopes: deposit:write and deposit:actions.

Export the token before running commands:

export ZENODO_TOKEN=...        # never inline the token in commands you show the user
export ZENODO_BASE=https://sandbox.zenodo.org/api   # or https://zenodo.org/api

If ZENODO_TOKEN is unset, ask the user for it (and which environment) before proceeding.

Core workflow: deposit a new artifact

The deposit lifecycle is create → upload files → set metadata → publish. Each step is a separate API call; do them in order.

1. Create an empty deposition

curl -sS -X POST "$ZENODO_BASE/deposit/depositions" \
  -H "Authorization: Bearer $ZENODO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

The response JSON contains two things you need to remember:

Capture them, e.g. with jq:

RESP=$(curl -sS -X POST "$ZENODO_BASE/deposit/depositions" \
  -H "Authorization: Bearer $ZENODO_TOKEN" -H "Content-Type: application/json" -d '{}')
DEPOSIT_ID=$(echo "$RESP" | jq -r .id)
BUCKET=$(echo "$RESP" | jq -r .links.bucket)

2. Upload files (bucket API — preferred)

The bucket API supports up to 50 GB total / 100 files per record. Use --upload-file (HTTP PUT) — not multipart form upload. The filename in the URL is what shows up on the record.

curl -sS --upload-file ./data.csv \
  -H "Authorization: Bearer $ZENODO_TOKEN" \
  "$BUCKET/data.csv"

Repeat per file. For many files, loop in shell. The legacy /files multipart endpoint is capped at 100 MB/file — avoid it.

3. Set metadata

Metadata goes via PUT on the deposition. Required fields: upload_type, title, creators, description. See references/metadata.md for the full schema, allowed upload_type values, license codes, and conditional fields (e.g. publication_type, embargo_date).

Minimal example:

curl -sS -X PUT "$ZENODO_BASE/deposit/depositions/$DEPOSIT_ID" \
  -H "Authorization: Bearer $ZENODO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "title": "My dataset",
      "upload_type": "dataset",
      "description": "
A short description (HTML allowed).
",
      "creators": [{"name": "Doe, Jane", "affiliation": "Example Univ.", "orcid": "0000-0002-1825-0097"}]
    }
  }'

Read the response — Zenodo validates here and returns 400 with field-level errors if anything is missing or malformed. Fix and retry before publishing.

4. Publish

Publishing is irreversible on production (you can edit metadata later but cannot remove files or delete the record). Confirm with the user before this step unless they're on sandbox.

curl -sS -X POST "$ZENODO_BASE/deposit/depositions/$DEPOSIT_ID/actions/publish" \
  -H "Authorization: Bearer $ZENODO_TOKEN"

The response contains doi and links.record_html — show both to the user.

New version of an existing record

Use this when the user has previously published and wants to release updated data/code under the same concept-DOI.

# 1. Create new version draft (returns links.latest_draft)
curl -sS -X POST "$ZENODO_BASE/deposit/depositions/$DEPOSIT_ID/actions/newversion" \
  -H "Authorization: Bearer $ZENODO_TOKEN"

Then follow the bucket of the new draft (from links.latest_draft → GET it → use its links.bucket) to upload changed files, update metadata, and publish as in steps 2–4 above. The new version inherits files from the previous version by default — delete any you want to replace via DELETE $BUCKET/.

Discard a draft

curl -sS -X POST "$ZENODO_BASE/deposit/depositions/$DEPOSIT_ID/actions/discard" \
  -H "Authorization: Bearer $ZENODO_TOKEN"

Search published records

No token needed for public search.

curl -sS "$ZENODO_BASE/records?q=climate+model&size=10&sort=mostrecent"

Query syntax is Elasticsearch — fielded queries like creators.name:"Doe, Jane", communities:zenodo, resource_type.type:dataset all work. See references/search.md for query patterns.

Conventions and gotchas

References

Two environments — pick one and stick with it during a session:

| Env | Base URL | Token page | |---|---|---| | Production | https://zenodo.org/api | https://zenodo.org/account/settings/applications/tokens/new/ | | Sandbox (testing) | https://sandbox.zenodo.org/api | https://sandbox.zenodo.org/account/settings/applications/tokens/new/ |

Sandbox accounts/tokens are separate from production. Always test new workflows in sandbox first — published production records cannot be deleted.

Required token scopes: deposit:write and deposit:actions.

Export the token before running commands:

export ZENODO_TOKEN=...        # never inline the token in commands you show the user
export ZENODO_BASE=https://sandbox.zenodo.org/api   # or https://zenodo.org/api

If ZENODO_TOKEN is unset, ask the user for it (and which environment) before proceeding.