swagger: '2.0'
info:
title: fatcat auth releases API
version: 0.5.0
description: 'Fatcat is a scalable, versioned, API-oriented catalog of bibliographic
entities and file metadata.
<!-- STARTLONGDESCRIPTION -->
These API reference documents, along with client software libraries, are
generated automatically from an OpenAPI 2.0 ("Swagger") definition file.
## Introduction
A higher-level introduction to the API, as well as a description of the
fatcat data model, are available in ["The Fatcat Guide"](https://guide.fatcat.wiki/).
The guide also includes a [Cookbook](https://guide.fatcat.wiki/cookbook.html)
section demonstrating end-to-end tasks like creating entities as part of
editgroups, or safely merging duplicate entities.
### Expectations and Best Practices
A test/staging QA API instance of fatcat is available at
<https://api.qa.fatcat.wiki/v0>. The database backing this instance is
separate from the production interface, and is periodically rebuilt from
snapshots of the full production database, meaning that edits on the QA
server will *NOT* persist, and that semantics like the changelog index
monotonically increasing *MAY* be broken. Developers are expexcted to test
their scripts and tools against the QA instance before running against
production.
NOTE: as of Spring 2021, the QA server is temporarily unavailable.
Fatcat is made available as a gratis (no cost) and libre (freedom
preserving) service to the public, with limited funding and resources. We
welcome new and unforeseen uses and contributions, but may need to impose
restrictions (like rate-limits) to keep the service functional for other
users, and in extreme cases reserve the option to block accounts and IP
ranges if necessary to keep the service operational.
The Internet Archive owns and operates it''s own server equipment and data
centers, and operations are optimized for low-cost, not high-availability.
Users and partners should expect some downtime on the fatcat API, on the
order of hours a month.
Periodic metadata exports are available for batch processing, and database
snapshots can be used to create locally-hosted mirrors of the service for
more intensive and reliable querying.
### Other Nitty Gritties
Cross-origin requests are allowed for the API service, to enable third
parties to build in-browser applications.
A metadata search service is available at <https://search.fatcat.wiki>.
The API is currently the raw elasticsearch API, with only GET (read)
requests allowed. This public service is experimental and may be removed or
limited in the future.
## Authentication
The API allows basic read-only "GET" HTTP requests with no authentication.
Proposing changes to the metadata, or other mutating requests ("PUT",
"POST", "DELETE") all require authentication, and some operations require
additional account permissions.
End-user account creation and login happens through the web interface. From
a logged-in editor profile page, you can generate a API token. Tokens are
"macaroons", similar to JWT tokens, and are used for all API
authentication. The web interface includes macaroons in browser cookies and
passes them through to the API to authenticate editor actions.
<!-- ReDoc-Inject: <security-definitions> -->
<!-- ENDLONGDESCRIPTION -->
'
termsOfService: https://guide.fatcat.wiki/policies.html
contact:
name: Internet Archive Web Group
email: webservices@archive.org
url: https://fatcat.wiki
x-logo:
url: https://fatcat.wiki/static/paper_man_confused.gif
altText: Confused Papers Man (Logo)
backgroundColor: '#FFFFFF'
host: api.fatcat.wiki
basePath: /v0
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: releases
x-displayName: Releases
description: '**Release** entities represent specific published versions of a research # TAGLINE
work, such as a pre-print, a journal article, a book (or chapter), or a # TAGLINE
scholarly blog post. Releases are always grouped together under Works; # TAGLINE
they may be published in a specific Container; they may have known # TAGLINE
Creators; and there may exist known File/Fileset/WebCapture digital copies # TAGLINE
of the release. # TAGLINE
See the "Catalog Style Guide" section of the guide for details and # TAGLINE
semantics of what should be included in specific entity fields. # TAGLINE
Specifically, the # TAGLINE
[Release Entity Reference](https://guide.fatcat.wiki/entity_release.html). # TAGLINE
'
paths:
/editgroup/{editgroup_id}/release:
parameters:
- name: editgroup_id
in: path
type: string
required: true
post:
operationId: create_release
tags:
- releases
description: 'Create a single Release entity as part of an existing editgroup. If the
`work_id` field is not set, a work entity will be created automatically
and this field set pointing to the new work.
Editgroup must be mutable (aka, not accepted) and editor must have
permission (aka, have created the editgrou p or have `admin` role).
'
parameters:
- name: entity
in: body
required: true
schema:
$ref: '#/definitions/release_entity'
security:
- Bearer: []
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
401:
description: Not Authorized
schema:
$ref: '#/definitions/error_response'
headers:
WWW_Authenticate:
type: string
403:
description: Forbidden
schema:
$ref: '#/definitions/error_response'
201:
description: Created Entity
schema:
$ref: '#/definitions/entity_edit'
/editgroup/auto/release/batch:
post:
operationId: create_release_auto_batch
tags:
- releases
description: 'Create a set of Release entities as part of a new editgroup, and
accept that editgroup in the same atomic request.
This method is mostly useful for bulk import of new entities by
carefully written bots. This method is more efficient than creating an
editgroup, several entities, then accepting the editgroup, both in
terms of API requests required and database load. Requires `admin`
role.
'
parameters:
- name: auto_batch
in: body
required: true
schema:
$ref: '#/definitions/release_auto_batch'
security:
- Bearer: []
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
401:
description: Not Authorized
schema:
$ref: '#/definitions/error_response'
headers:
WWW_Authenticate:
type: string
403:
description: Forbidden
schema:
$ref: '#/definitions/error_response'
201:
description: Created Editgroup
schema:
$ref: '#/definitions/editgroup'
/release/{ident}:
parameters:
- name: ident
in: path
type: string
required: true
get:
operationId: get_release
tags:
- releases
description: 'Fetches a single Release entity from the catalog.
'
parameters:
- name: expand
in: query
type: string
required: false
description: 'List of sub-entities to expand in response. For releases, ''files'',
''filesets, ''webcaptures'', ''container'', and ''creators'' are valid.
'
- name: hide
in: query
type: string
required: false
description: 'List of entity fields to elide in response (for efficiency). For
releases, ''abstracts'', ''refs'', and ''contribs'' are valid.
'
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
200:
description: Found Entity
schema:
$ref: '#/definitions/release_entity'
/editgroup/{editgroup_id}/release/{ident}:
parameters:
- name: editgroup_id
in: path
type: string
required: true
- name: ident
in: path
type: string
required: true
put:
operationId: update_release
tags:
- releases
description: 'Updates an existing entity as part of a specific (existing) editgroup.
The editgroup must be open for updates (aka, not accepted/merged), and
the editor making the request must have permissions (aka, must have
created the editgroup or have `admin` role).
This method can also be used to update an existing entity edit as part
of an editgroup. For example, if an entity was created in this
editgroup, an editor could make changes to the new entity''s metadata
before merging.
'
parameters:
- name: entity
in: body
required: true
schema:
$ref: '#/definitions/release_entity'
security:
- Bearer: []
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
401:
description: Not Authorized
schema:
$ref: '#/definitions/error_response'
headers:
WWW_Authenticate:
type: string
403:
description: Forbidden
schema:
$ref: '#/definitions/error_response'
200:
description: Updated Entity
schema:
$ref: '#/definitions/entity_edit'
delete:
operationId: delete_release
tags:
- releases
description: 'Creates a new "deletion" edit for a specific entity as part of an
existing editgroup.
This is not the method to use to remove an edit from an editgroup; for
that use `delete_release_edit`.
'
security:
- Bearer: []
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
401:
description: Not Authorized
schema:
$ref: '#/definitions/error_response'
headers:
WWW_Authenticate:
type: string
403:
description: Forbidden
schema:
$ref: '#/definitions/error_response'
200:
description: Deleted Entity
schema:
$ref: '#/definitions/entity_edit'
/release/rev/{rev_id}:
parameters:
- type: string
pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
minLength: 36
maxLength: 36
description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
name: rev_id
in: path
required: true
get:
operationId: get_release_revision
tags:
- releases
description: 'Fetches a specific entity revision. Note that the returned revision
will not be associated with any particular fatcat identifier (even if
one or more identifiers do currently point to this revision). The
revision may even be part of an un-merged editgroup.
Revisions are immutable and can not be deleted or updated.
'
parameters:
- name: expand
in: query
type: string
required: false
description: List of sub-entities to expand in response. See `get_release`, though note that identifier-based exapansions like `file` will always be empty for revisions.
- name: hide
in: query
type: string
required: false
description: List of entity fields to elide in response. See `get_release`.
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
200:
description: Found Entity Revision
schema:
$ref: '#/definitions/release_entity'
/release/{ident}/history:
parameters:
- name: ident
in: path
type: string
required: true
- name: limit
in: query
type: integer
format: int64
required: false
get:
operationId: get_release_history
tags:
- releases
description: 'Fetches the history of accepted edits (changelog entries) for a
specific entity fatcat identifier.
'
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
200:
description: Found Entity History
schema:
type: array
items:
$ref: '#/definitions/entity_history_entry'
/release/{ident}/files:
parameters:
- name: ident
in: path
type: string
required: true
- name: hide
in: query
type: string
required: false
description: List of entity fields to elide in response. See `get_file`.
get:
operationId: get_release_files
tags:
- releases
description: 'Returns the set of File entities that have a `release_id` pointing to
this release entity.
'
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
200:
description: Found
schema:
type: array
items:
$ref: '#/definitions/file_entity'
/release/{ident}/filesets:
parameters:
- name: ident
in: path
type: string
required: true
- name: hide
in: query
type: string
required: false
description: List of entity fields to elide in response. See `get_fileset`.
get:
operationId: get_release_filesets
tags:
- releases
description: 'Returns the set of Fileset entities that have a `release_id` pointing to
this release entity.
'
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
200:
description: Found
schema:
type: array
items:
$ref: '#/definitions/fileset_entity'
/release/{ident}/webcaptures:
parameters:
- name: ident
in: path
type: string
required: true
- name: hide
in: query
type: string
required: false
description: List of entity fields to elide in response. See `get_webcapture`.
get:
operationId: get_release_webcaptures
tags:
- releases
description: 'Returns the set of Web Capture entities that have a `release_id`
pointing to this release entity.
'
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
200:
description: Found
schema:
type: array
items:
$ref: '#/definitions/webcapture_entity'
/release/{ident}/redirects:
parameters:
- name: ident
in: path
type: string
required: true
get:
operationId: get_release_redirects
tags:
- releases
description: 'Returns the set of entity identifiers which currently redirect to this
identifier.
'
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
200:
description: Found Entity Redirects
schema:
type: array
items:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: base32-encoded unique identifier
/release/lookup:
get:
operationId: lookup_release
tags:
- releases
description: 'Looks for an active entity with the given external identifier. If any
such entity is found, returns a single complete entity. If multiple
entities have the same external identifier, this is considered a soft
catalog error, and the behavior of which entity is returned is
undefined.
One (and only one) external identifier should be specified per request.
'
parameters:
- name: doi
in: query
type: string
required: false
- name: wikidata_qid
in: query
type: string
required: false
- name: isbn13
in: query
type: string
required: false
- name: pmid
in: query
type: string
required: false
- name: pmcid
in: query
type: string
required: false
- name: core
in: query
type: string
required: false
- name: arxiv
in: query
type: string
required: false
- name: jstor
in: query
type: string
required: false
- name: ark
in: query
type: string
required: false
- name: mag
in: query
type: string
required: false
- name: doaj
in: query
type: string
required: false
- name: dblp
in: query
type: string
required: false
- name: oai
in: query
type: string
required: false
- name: hdl
in: query
type: string
required: false
- name: expand
in: query
type: string
required: false
description: List of sub-entities to expand in response. See `get_release`.
- name: hide
in: query
type: string
required: false
description: List of sub-entities to elide in response. See `get_release`.
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
200:
description: Found Entity
schema:
$ref: '#/definitions/release_entity'
/release/edit/{edit_id}:
get:
operationId: get_release_edit
tags:
- releases
description: 'Returns the entity edit object with the given identifier. This method
is expected to be used rarely.
'
parameters:
- type: string
pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
minLength: 36
maxLength: 36
description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
name: edit_id
in: path
required: true
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
200:
description: Found Edit
schema:
$ref: '#/definitions/entity_edit'
/editgroup/{editgroup_id}/release/edit/{edit_id}:
parameters:
- name: editgroup_id
in: path
required: true
type: string
- type: string
pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
minLength: 36
maxLength: 36
description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
name: edit_id
in: path
required: true
delete:
operationId: delete_release_edit
tags:
- releases
description: 'Removes a single edit from the specified editgroup. The editgroup must
be mutable (aka, not accepted/merged), and the editor making this
request must have permission (aka, have created the editgroup or hold
the `admin` role).
Not to be confused with the `delete_container` method, which *creates*
a new edit in the given editgroup.
'
security:
- Bearer: []
responses:
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
401:
description: Not Authorized
schema:
$ref: '#/definitions/error_response'
headers:
WWW_Authenticate:
type: string
403:
description: Forbidden
schema:
$ref: '#/definitions/error_response'
200:
description: Deleted Edit
schema:
$ref: '#/definitions/success'
definitions:
release_auto_batch:
type: object
required:
- editgroup
- entity_list
properties:
editgroup:
$ref: '#/definitions/editgroup'
entity_list:
type: array
items:
$ref: '#/definitions/release_entity'
release_ref:
type: object
properties:
index:
type: integer
format: int64
description: 'Zero-indexed sequence number of this reference in the list of
references. Assigned automatically and used internally; don''t confuse
with `key`.
'
target_release_id:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: 'Optional, fatcat identifier of release entity that this reference is
citing.
'
example: q3nouwy3nnbsvo3h5klxsx4a7y
extra:
type: object
additionalProperties: {}
description: 'Additional free-form JSON metadata about this citation. Generally
follows Citation Style Language (CSL) JSON schema. See guide for
details.
'
key:
type: string
example: SMITH2016
description: 'Short string used to indicate this reference from within the release
text; or numbering of references as typeset in the release itself.
Optional; don''t confuse with `index` field.
'
year:
type: integer
format: int64
example: 1972
description: 'Year that the cited work was published in.
'
container_name:
type: string
description: 'Name of the container (eg, journal) that the citation work was
published as part of. May be an acronym or full name.
'
title:
type: string
description: Name of the work being cited.
locator:
type: string
example: p123
description: 'Page number or other indicator of the specific subset of a work being
cited. Not to be confused with the first page (or page range) of an
entire paper or chapter being cited.
'
container_entity:
type: object
properties:
state:
type: string
enum:
- wip
- active
- redirect
- deleted
example: active
ident:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: base32-encoded unique identifier
example: q3nouwy3nnbsvo3h5klxsx4a7y
revision:
type: string
pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
minLength: 36
maxLength: 36
description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
redirect:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: base32-encoded unique identifier
example: q3nouwy3nnbsvo3h5klxsx4a7y
extra:
type: object
description: 'Free-form JSON metadata that will be stored with the other entity
metadata. See guide for (unenforced) schema conventions.
'
additionalProperties: {}
edit_extra:
type: object
description: 'Free-form JSON metadata that will be stored with specific entity edits
(eg, creation/update/delete).
'
additionalProperties: {}
name:
type: string
description: Name of the container (eg, Journal title). Required for entity creation.
example: Journal of Important Results
container_type:
type: string
description: Type of container, eg 'journal' or 'proceedings'. See Guide for list of valid types.
example: journal
publication_status:
type: string
description: Whether the container is active, discontinued, etc
example: active
publisher:
type: string
description: 'Name of the organization or entity responsible for publication. Not
the complete imprint/brand.
'
example: Society of Curious Students
issnl:
type: string
pattern: \d{4}-\d{3}[0-9X]
minLength: 9
maxLength: 9
example: 1234-5678
description: Linking ISSN number (ISSN-L). Should be valid and registered with issn.org
issne:
type: string
pattern: \d{4}-\d{3}[0-9X]
minLength: 9
maxLength: 9
example: 1234-5678
description: Electronic ISSN number (ISSN-E). Should be valid and registered with issn.org
issnp:
type: string
pattern: \d{4}-\d{3}[0-9X]
minLength: 9
maxLength: 9
example: 1234-5678
description: Print ISSN number (ISSN-P). Should be valid and registered with issn.org
wikidata_qid:
type: string
example: Q42812
editor:
type: object
required:
- username
properties:
editor_id:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: 'Fatcat identifier for the editor. Can not be changed.
'
example: q3nouwy3nnbsvo3h5klxsx4a7y
username:
type: string
example: zerocool93
description: 'Username/handle (short slug-like string) to identify this editor. May
be changed at any time by the editor; use the `editor_id` as a
persistend identifier.
'
is_admin:
type: boolean
example: false
description: 'Whether this editor has the `admin` role.
'
is_bot:
type: boolean
example: false
description: 'Whether this editor is a bot (as opposed to a human making manual
edits)
'
is_active:
type: boolean
example: true
description: 'Whether this editor''s account is enabled (if not API tokens and web
logins will not work).
'
webcapture_url:
type: object
required:
- url
- rel
properties:
url:
type: string
format: url
example: https://web.archive.org/web/
description: 'URL/URI pointing to archive of this web resource.
'
rel:
type: string
example: wayback
description: 'Type of archive endpoint. Usually `wayback` (WBM replay of primary
resource), or `warc` (direct URL to a WARC file containing all
resources of the capture). See guide for full list.
'
file_entity:
type: object
properties:
state:
type: string
enum:
- wip
- active
- redirect
- deleted
example: active
ident:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: base32-encoded unique identifier
example: q3nouwy3nnbsvo3h5klxsx4a7y
revision:
type: string
pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
minLength: 36
maxLength: 36
description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
redirect:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: base32-encoded unique identifier
example: q3nouwy3nnbsvo3h5klxsx4a7y
extra:
type: object
description: 'Free-form JSON metadata that will be stored with the other entity
metadata. See guide for (unenforced) schema conventions.
'
additionalProperties: {}
edit_extra:
type: object
description: 'Free-form JSON metadata that will be stored with specific entity edits
(eg, creation/update/delete).
'
additionalProperties: {}
size:
type: integer
example: 1048576
format: int64
description: Size of file in bytes. Non-zero.
md5:
type: string
pattern: '[a-f0-9]{32}'
minLength: 32
maxLength: 32
description: MD5 hash of data, in hex encoding
example: 1b39813549077b2347c0f370c3864b40
sha1:
type: string
pattern: '[a-f0-9]{40}'
minLength: 40
maxLength: 40
description: SHA-1 hash of data, in hex encoding
example: e9dd75237c94b209dc3ccd52722de6931a310ba3
sha256:
type: string
pattern: '[a-f0-9]{64}'
mi
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fatcat/refs/heads/main/openapi/fatcat-releases-api-openapi.yml