OpenAPI Specification
openapi: 3.0.3
info:
title: Zenodo REST Access Records API
description: 'REST API for Zenodo, the free open research data repository operated by CERN and built on InvenioRDM. Provides programmatic access to deposits (draft records), published records, file management, communities, vocabularies, OAI-PMH sets, requests, users, groups, statistics, and audit logs. Every published record receives a DOI for persistent citation. Authenticate with a personal access token passed as a Bearer token.
'
version: 12.0.0
contact:
name: Zenodo Developer Documentation
url: https://developers.zenodo.org/
license:
name: MIT License
url: https://opensource.org/licenses/MIT
x-upstream-spec: https://github.com/inveniosoftware/invenio-openapi
servers:
- url: https://zenodo.org
description: Zenodo production instance
- url: https://sandbox.zenodo.org
description: Zenodo sandbox (testing)
security:
- BearerAuth: []
tags:
- name: Records
description: Record and draft management endpoints
paths:
/api/records:
post:
summary: Create a draft record
tags:
- Records
operationId: createADraftRecord
requestBody:
required: true
content:
application/json:
schema:
type: object
example:
access:
record: public
files: public
files:
enabled: true
metadata:
creators:
- person_or_org:
family_name: Doe
given_name: John
identifiers:
- identifier: 0000-0000-0000-0000
scheme: orcid
name: Doe, John
type: personal
affiliations:
- name: Example Organization
role:
id: other
publication_date: '2020-06-01'
resource_type:
id: dataset
title: Example dataset
responses:
'201':
$ref: '#/components/responses/Created'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
get:
summary: Search records
tags:
- Records
operationId: searchRecords
parameters:
- name: q
in: query
required: false
schema:
type: string
description: Search query using ElasticSearch query string syntax.
- name: sort
in: query
required: false
schema:
type: string
description: 'Sort results. Options: bestmatch, newest, oldest, updated-desc, updated-asc, version, mostviewed, mostdownloaded.
'
example: newest
- name: size
in: query
required: false
schema:
type: string
description: Number of items per page (default 10).
- name: page
in: query
required: false
schema:
type: string
description: Page number.
- name: allversions
in: query
required: false
schema:
type: string
description: Include all versions (default False).
example: 'True'
responses:
'200':
$ref: '#/components/responses/Success'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/api/records/{recordId}:
get:
summary: Get a record by ID
tags:
- Records
operationId: getARecordById
parameters:
- name: recordId
in: path
required: true
schema:
type: string
description: Unique record identifier
responses:
'200':
$ref: '#/components/responses/Success'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
/api/records/{recordId}/communities:
delete:
summary: Remove a record from a community
tags:
- Records
operationId: deleteRecordCommunity
parameters:
- name: recordId
in: path
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/Success'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
/api/records/{recordId}/access/links:
post:
summary: Create an access link
tags:
- Records
operationId: createAnAccessLink
parameters:
- name: recordId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
example:
permission: view
expires_at: '2024-11-06'
responses:
'201':
$ref: '#/components/responses/Created'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
get:
summary: List access links
tags:
- Records
operationId: listAccessLinks
parameters:
- name: recordId
in: path
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/Success'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
/api/records/{recordId}/access/links/{linkId}:
get:
summary: Get an access link by ID
tags:
- Records
operationId: getAnAccessLinkById
parameters:
- name: recordId
in: path
required: true
schema:
type: string
- name: linkId
in: path
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/Success'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
patch:
summary: Update an access link
tags:
- Records
operationId: updateAnAccessLink
parameters:
- name: recordId
in: path
required: true
schema:
type: string
- name: linkId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
example:
permission: edit
expires_at: '2024-11-06'
responses:
'200':
$ref: '#/components/responses/Success'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
delete:
summary: Delete an access link
tags:
- Records
operationId: deleteAnAccessLink
parameters:
- name: recordId
in: path
required: true
schema:
type: string
- name: linkId
in: path
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/Success'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
components:
responses:
Created:
description: Resource created successfully
content:
application/json:
schema:
type: object
Success:
description: Successful response
content:
application/json:
schema:
type: object
Unauthorized:
description: Unauthorized - authentication required
BadRequest:
description: Bad request - invalid input parameters
NotFound:
description: Not found - resource does not exist
Forbidden:
description: Forbidden - insufficient permissions
InternalServerError:
description: Internal server error
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Personal access token issued from the Zenodo account settings