openapi: "3.0.0" info: title: fatcat version: 0.5.0 description: | Fatcat is a scalable, versioned, API-oriented catalog of bibliographic entities and file metadata. 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 . 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. 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 unforseen 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 (and ). 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. 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" servers: - url: https://api.fatcat.wiki/v0 description: Production Server - url: https://api.qa.fatcat.wiki/v0 description: QA Server tags: # TAGLINE - name: containers # TAGLINE x-displayName: "Containers" # TAGLINE description: | # TAGLINE **Container** entities represent publication venues like journals, # TAGLINE conference proceedings, book series, or blogs. They group publications # TAGLINE ("releases"). # 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 [Container Entity Reference](https://guide.fatcat.wiki/entity_container.html). # TAGLINE - name: creators # TAGLINE x-displayName: "Creators" # TAGLINE description: | # TAGLINE **Creator** entities represent individuals (or organizations, or other # TAGLINE agents) who contribute to the creation of specific releases # TAGLINE (publications). # 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 [Creator Entity Reference](https://guide.fatcat.wiki/entity_creator.html). # TAGLINE - name: files # TAGLINE x-displayName: "Files" # TAGLINE description: | # TAGLINE **File** entities represent unique digital files which are full # TAGLINE manifestations of specific releases (publications), such as fulltext PDF # TAGLINE files, JATS XML documents, or video files. File entities also include a # TAGLINE set of locations where they can be found on the public web. # 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 [File Entity Reference](https://guide.fatcat.wiki/entity_file.html). # TAGLINE - name: filesets # TAGLINE x-displayName: "Filesets" # TAGLINE description: | # TAGLINE **Fileset** entities represent sets of digital files, as well as locations # TAGLINE where they can be found on the public web. Filesets most commonly # TAGLINE represent datasets consisting of serveral data and metadata files. # 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 [Fileset Entity Reference](https://guide.fatcat.wiki/entity_fileset.html). # TAGLINE - name: webcaptures # TAGLINE x-displayName: "Webcaptures" # TAGLINE description: | # TAGLINE **Web Capture** entities represent archival snapshots of web pages (or # TAGLINE other web resources), which are usually complete manifestations of a # TAGLINE specific release entity. Web Captures also include a set of locations # TAGLINE (wayback replay instances or WARC files) where the capture can be found. # 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 [Web Capture Entity Reference](https://guide.fatcat.wiki/entity_webcapture.html). # TAGLINE - name: releases # TAGLINE x-displayName: "Releases" # TAGLINE description: | # TAGLINE **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 - name: works # TAGLINE x-displayName: "Works" # TAGLINE description: | # TAGLINE **Work** entities group several Release entities which are different # TAGLINE versions of the same abstract piece of research. For example, three # TAGLINE release entities representing the pre-print, published article, and # TAGLINE retraction stages of the same journal paper would be grouped under a # TAGLINE single work. # 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 [Work Entity Reference](https://guide.fatcat.wiki/entity_work.html). # TAGLINE - name: editgroups # TAGLINE x-displayName: "Editgroups" # TAGLINE description: | # TAGLINE **Editgroups** are sets of changes, each to individual entities in the # TAGLINE catalog. Every edit must be part of an editgroup which is reviewed and # TAGLINE accepted (merged) as a whole. # TAGLINE - name: editors # TAGLINE x-displayName: "Editors" # TAGLINE description: | # TAGLINE **Editors** are human user accounts and bots that make changes to the # TAGLINE Fatcat catalog. # TAGLINE The API allows fetching (and updating) metadata about individual editors, # TAGLINE as well as fetching editor's annotation and edit history. # TAGLINE - name: changelog # TAGLINE x-displayName: "Changelog" # TAGLINE description: | # TAGLINE The **Changelog** is the ordered feed of editgroups which have been # TAGLINE accepted into the catalog. # TAGLINE - name: auth # TAGLINE x-displayName: "Auth Methods" # TAGLINE description: | # TAGLINE Helper methods and internal APIs for editor authentication. # TAGLINE x-tagGroups: # TAGLINE - name: Entities # TAGLINE tags: # TAGLINE - containers # TAGLINE - creators # TAGLINE - files # TAGLINE - filesets # TAGLINE - webcaptures # TAGLINE - releases # TAGLINE - works # TAGLINE - name: Editing # TAGLINE tags: # TAGLINE - editors # TAGLINE - editgroups # TAGLINE - changelog # TAGLINE - name: Other # TAGLINE tags: # TAGLINE - auth # TAGLINE # don't want these to be rust types (at least for now) x-fatcat-ident: &FATCATIDENT type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: "base32-encoded unique identifier" x-fatcat-ident-example: &FATCATIDENTEXAMPLE example: "q3nouwy3nnbsvo3h5klxsx4a7y" x-fatcat-uuid: &FATCATUUID 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)" x-fatcat-uuid-example: &FATCATUUIDEXAMPLE example: "86daea5b-1b6b-432a-bb67-ea97795f80fe" x-issn: &FATCATISSN type: string pattern: "\\d{4}-\\d{3}[0-9X]" minLength: 9 maxLength: 9 x-issn-example: &FATCATISSNEXAMPLE example: "1234-5678" x-orcid: &FATCATORCID type: string pattern: "\\d{4}-\\d{4}-\\d{4}-\\d{3}[\\dX]" minLength: 19 maxLength: 19 description: "ORCiD (https://orcid.org) identifier" x-orcid-example: &FATCATORCIDEXAMPLE example: "0000-0002-1825-0097" x-md5: &FATCATMD5 type: string pattern: "[a-f0-9]{32}" minLength: 32 maxLength: 32 description: "MD5 hash of data, in hex encoding" x-md5-example: &FATCATMD5EXAMPLE example: "1b39813549077b2347c0f370c3864b40" x-sha1: &FATCATSHA1 type: string pattern: "[a-f0-9]{40}" minLength: 40 maxLength: 40 description: "SHA-1 hash of data, in hex encoding" x-sha1-example: &FATCATSHA1EXAMPLE example: "e9dd75237c94b209dc3ccd52722de6931a310ba3" x-sha256: &FATCATSHA256 type: string pattern: "[a-f0-9]{64}" minLength: 64 maxLength: 64 description: "SHA-256 hash of data, in hex encoding" x-sha256-example: &FATCATSHA256EXAMPLE example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452" # Common properties across entities x-entity-props: &ENTITYPROPS state: type: string enum: - wip - active - redirect - deleted example: "active" ident: <<: *FATCATIDENT #<<: *FATCATIDENTEXAMPLE revision: <<: *FATCATUUID #<<: *FATCATUUIDEXAMPLE redirect: <<: *FATCATIDENT #<<: *FATCATIDENTEXAMPLE 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: {} components: requestBodies: work_entity: content: application/json: schema: $ref: "#/components/schemas/work_entity" required: true webcapture_entity: content: application/json: schema: $ref: "#/components/schemas/webcapture_entity" required: true container_entity: content: application/json: schema: $ref: "#/components/schemas/container_entity" required: true creator_entity: content: application/json: schema: $ref: "#/components/schemas/creator_entity" required: true file_entity: content: application/json: schema: $ref: "#/components/schemas/file_entity" required: true fileset_entity: content: application/json: schema: $ref: "#/components/schemas/fileset_entity" required: true release_entity: content: application/json: schema: $ref: "#/components/schemas/release_entity" required: true editgroup: content: application/json: schema: $ref: "#/components/schemas/editgroup" required: true securitySchemes: Bearer: type: http scheme: bearer description: | The only current API authentication mechanism is HTTP bearer authentication using the `Authorization` HTTP header. The header should be formatted as the string "Bearer", then a space, then API token (in the usual base64 string encoding). An example HTTP request would look on the wire like: GET /v0/auth/check HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug= Connection: keep-alive Host: api.qa.fatcat.wiki User-Agent: HTTPie/0.9.8 Headers can be passed on the command line using `http` (HTTPie) like: http get https://api.qa.fatcat.wiki/v0/auth/check Authorization:"Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=" Or with `curl`: curl -H "Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=" https://qa.fatcat.wiki/v0/auth/check schemas: error_response: type: object required: - success - error - message properties: success: type: boolean example: false error: type: string example: unexpected-thing message: type: string example: A really confusing, totally unexpected thing happened success: type: object required: - success - message properties: success: type: boolean example: true message: type: string example: The computers did the thing successfully! 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: description: Linking ISSN number (ISSN-L). Should be valid and registered with issn.org type: string pattern: \d{4}-\d{3}[0-9X] minLength: 9 maxLength: 9 example: 1234-5678 issne: description: Electronic ISSN number (ISSN-E). Should be valid and registered with issn.org type: string pattern: \d{4}-\d{3}[0-9X] minLength: 9 maxLength: 9 example: 1234-5678 issnp: description: Print ISSN number (ISSN-P). Should be valid and registered with issn.org type: string pattern: \d{4}-\d{3}[0-9X] minLength: 9 maxLength: 9 example: 1234-5678 wikidata_qid: type: string example: Q42812 creator_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: {} display_name: type: string example: Grace Hopper description: | Name as should be displayed in web interface or in author lists (not index/sorted). Required for valid entities. given_name: type: string description: | In English commonly the first name, but ordering is context and culture specific. surname: type: string description: | In English commonly the last, or family name, but ordering is context and culture specific. orcid: type: string pattern: \d{4}-\d{4}-\d{4}-\d{3}[\dX] minLength: 19 maxLength: 19 description: ORCiD (https://orcid.org) identifier example: 0000-0002-1825-0097 wikidata_qid: type: string example: Q42812 description: Wikidata entity QID 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}" minLength: 64 maxLength: 64 description: SHA-256 hash of data, in hex encoding example: cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452 urls: type: array items: $ref: "#/components/schemas/file_url" mimetype: type: string example: application/pdf content_scope: type: string example: issue release_ids: type: array items: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: base32-encoded unique identifier example: q3nouwy3nnbsvo3h5klxsx4a7y description: | Set of identifier of release entities this file represents a full manifestation of. Usually a single release, but some files contain content of multiple full releases (eg, an issue of a journal). releases: description: | Full release entities, included in GET responses when `releases` included in `expand` parameter. Ignored if included in PUT or POST requests. type: array items: $ref: "#/components/schemas/release_entity" file_url: type: object required: - url - rel properties: url: type: string format: url example: https://example.edu/~frau/prcding.pdf description: > URL/URI pointing directly to a machine retrievable copy of this exact file. rel: type: string example: web description: | Indicates type of host this URL points to. Eg, "publisher", "repository", "webarchive". See guide for list of acceptable values. fileset_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: {} content_scope: type: string example: issue manifest: type: array items: $ref: "#/components/schemas/fileset_file" urls: type: array items: $ref: "#/components/schemas/fileset_url" release_ids: type: array items: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: base32-encoded unique identifier example: q3nouwy3nnbsvo3h5klxsx4a7y description: | Set of identifier of release entities this fileset represents a full manifestation of. Usually a single release. releases: type: array items: $ref: "#/components/schemas/release_entity" description: | Full release entities, included in GET responses when `releases` included in `expand` parameter. Ignored if included in PUT or POST requests. fileset_url: type: object required: - url - rel properties: url: type: string format: url example: https://example.edu/~frau/prcding.pdf rel: type: string example: webarchive description: | Indicates type of host this URL points to. See guide for list of acceptable values. fileset_file: type: object required: - path - size properties: path: type: string example: img/cat.png description: | Path name of file within this fileset (eg, directory) size: type: integer example: 1048576 format: int64 description: File size in bytes 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}" minLength: 64 maxLength: 64 description: SHA-256 hash of data, in hex encoding example: cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452 mimetype: type: string example: "application/pdf" extra: type: object additionalProperties: {} description: | Free-form additional metadata about this specific file in the set. Eg, `original_url`. See guide for normative (but unenforced) schema fields. webcapture_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: {} cdx: type: array items: $ref: "#/components/schemas/webcapture_cdx_line" archive_urls: type: array items: $ref: "#/components/schemas/webcapture_url" original_url: type: string format: url example: http://asheesh.org description: Base URL of the primary resource this is a capture of timestamp: type: string format: date-time description: | Same format as CDX line timestamp (UTC, etc). Corresponds to the overall capture timestamp. Should generally be the timestamp of capture of the primary resource URL. content_scope: type: string example: landing-page release_ids: type: array items: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: base32-encoded unique identifier example: q3nouwy3nnbsvo3h5klxsx4a7y description: | Set of identifier of release entities this fileset represents a full manifestation of. Usually a single release. releases: type: array items: $ref: "#/components/schemas/release_entity" description: | Full release entities, included in GET responses when `releases` included in `expand` parameter. Ignored if included in PUT or POST requests. webcapture_cdx_line: type: object required: - surt - timestamp - url - sha1 properties: surt: type: string example: org,asheesh)/apus/ch1/node15.html description: | "Sortable URL" format. See guide for details. timestamp: type: string format: date-time example: 2016-09-19T17:20:24Z description: | Date and time of capture, in ISO format. UTC, 'Z'-terminated, second (or better) precision. url: type: string example: http://www.asheesh.org:80/APUS/ch1/node15.html description: | Full URL/URI of resource captured. mimetype: type: string example: text/html description: > Mimetype of the resource at this URL. May be the Content-Type header, or the actually sniffed file type. status_code: type: integer example: 200 format: int64 description: > HTTP status code. Should generally be 200, especially for the primary resource, but may be 3xx (redirect) or even error codes if embedded resources can not be fetched successfully. size: type: integer example: 1048576 format: int64 description: Resource (file) size in bytes 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}" minLength: 64 maxLength: 64 description: SHA-256 hash of data, in hex encoding example: cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452 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. release_entity: type: object required: - ext_ids 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: {} title: type: string description: > Required for valid entities. The title used in citations and for display. Sometimes the English translation of title e even if release content is not English. subtitle: type: string description: > Subtitle of release. In many cases, better to merge with title than include as separate field (unless combined title would be very long). See guide for details. original_title: type: string description: | Title in original language if `title` field has been translated. See guide for details. work_id: type: string example: q3nouwy3nnbsvo3h5klxsx4a7y description: | Identifier of work this release is part of. In creation (POST) requests, a work entity will be created automatically if this field is not set. container: $ref: "#/components/schemas/container_entity" files: type: array items: $ref: "#/components/schemas/file_entity" description: > Complete file entities identified by `file_ids` field. Only included in GET responses when `files` included in `expand` parameter; ignored in PUT or POST requests. filesets: type: array items: $ref: "#/components/schemas/fileset_entity" description: | Complete file entities identified by `filesets_ids` field. Only included in GET responses when `filesets` included in `expand` parameter; ignored in PUT or POST requests. webcaptures: type: array items: $ref: "#/components/schemas/webcapture_entity" description: > Complete webcapture entities identified by `webcapture_ids` field. Only included in GET responses when `webcaptures` included in `expand` parameter; ignored in PUT or POST requests. container_id: type: string example: q3nouwy3nnbsvo3h5klxsx4a7y description: | Used to link this release to a container entity that the release was published as part of. release_type: type: string example: book description: | "Type" or "medium" that this release is published as. See guide for valid values. release_stage: type: string example: preprint description: | The stage of publication of this specific release. See guide for valid values and semantics. release_date: type: string format: date description: | Full date when this release was formally published. ISO format, like `2019-03-05`. See guide for semantics. release_year: type: integer example: 2014 format: int64 description: | Year when this release was formally published. Must match `release_date` if that field is set; this field exists because sometimes only the year is known. withdrawn_status: type: string example: retracted description: | Type of withdrawl or retraction of this release, if applicable. If release has not been withdrawn, should be `null` (aka, not set, not the string "null" or an empty string). withdrawn_date: type: string format: date description: | Full date when this release was formally withdrawn (if applicable). ISO format, like `release_date`. withdrawn_year: type: integer example: 2014 format: int64 description: | Year corresponding with `withdrawn_date` like `release_year`/`release_date`. ext_ids: $ref: "#/components/schemas/release_ext_ids" volume: type: string example: "3" description: | Volume number of container that this release was published in. Often corresponds to the "Nth" year of publication, but can be any string. See guide. issue: type: string example: "12" description: | Issue number of volume/container that this release was published in. Sometimes coresponds to a month number in the year, but can be any string. See guide. pages: type: string example: 340-345 description: | Either a single page number ("first page") or a range of pages separated by a dash ("-"). See guide for details. number: type: string example: RFC1337 description: | For, eg, technical reports, which are published in series or assigned some other institutional or container-specific identifier. version: type: string example: "3" description: | For, eg, updated technical reports or software packages, where the version string may be the only field disambiguating between releases. publisher: type: string example: Elsevier description: | Name, usually English, of the entity or institution responsible for publication of this release. Not necessarily the imprint/brand. See guide. language: type: string example: en description: | Primary language of the content of the full release. Two-letter RFC1766/ISO639-1 language code, with some custom extensions/additions. See guide. license_slug: type: string example: CC-BY description: | Short string (slug) name of license under which release is openly published (if applicable). contribs: type: array items: $ref: "#/components/schemas/release_contrib" refs: type: array items: $ref: "#/components/schemas/release_ref" abstracts: type: array items: $ref: "#/components/schemas/release_abstract" release_ext_ids: type: object properties: doi: type: string example: 10.1234/abcde.789 description: | Digital Object Identifier (DOI), mostly for published papers and datasets. Should be registered and resolvable via https://doi.org/ wikidata_qid: type: string example: Q42812 description: Wikidata entity QID isbn13: type: string description: | ISBN-13, for books. Usually not set for chapters. ISBN-10 should be converted to ISBN-13. pmid: type: string example: "482132" description: PubMed Identifier pmcid: example: PMC7391 type: string description: PubMed Central Identifier core: example: "9234592" type: string description: CORE (https://core.ac.uk) identifier arxiv: type: string description: arXiv (https://arxiv.org) identifier; must include version jstor: type: string description: JSTOR work identifier ark: type: string description: ARK identifier mag: type: string description: Microsoft Academic Graph identifier doaj: type: string description: DOAJ article-level identifier dblp: type: string description: "dblp (https://dblp.uni-trier.de/) paper identifier; eg for conference proceedings" oai: type: string description: "OAI-PMH identifier; only used when an OAI-PMH record is the only authoritative metadata (eg, journal OAI-PMH feeds w/o DOIs)" hdl: type: string description: "Handle identifier. Do not put DOIs in this field" release_abstract: type: object properties: sha1: type: string pattern: "[a-f0-9]{40}" minLength: 40 maxLength: 40 description: SHA-1 hash of data, in hex encoding example: e9dd75237c94b209dc3ccd52722de6931a310ba3 content: type: string example: Some abstract thing goes here description: | Abstract content. May be encoded, as per `mimetype` field, but only string/text content may be included. mimetype: type: string example: application/xml+jats description: > Mimetype of abstract contents. `text/plain` is the default if content isn't encoded. lang: type: string example: en description: > ISO language code of the abstract. Same semantics as release `language` field. work_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: {} entity_history_entry: type: object required: - edit - editgroup - changelog_entry properties: edit: $ref: "#/components/schemas/entity_edit" editgroup: $ref: "#/components/schemas/editgroup" changelog_entry: $ref: "#/components/schemas/changelog_entry" entity_edit: type: object required: - edit_id - ident - editgroup_id properties: edit_id: 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: | Unique UUID for this specific edit object. example: 86daea5b-1b6b-432a-bb67-ea97795f80fe ident: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: | Fatcat identifier of the entity this edit is mutating. 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: | Entity revision that this edit will set the entity to. May be `null` in the case of deletions. example: 86daea5b-1b6b-432a-bb67-ea97795f80fe prev_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: | Revision of entity just before this edit. May be used in the future to prevent edit race conditions. example: 86daea5b-1b6b-432a-bb67-ea97795f80fe redirect_ident: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: | When an edit is to merge entities (redirect one to another), this is the entity fatcat identifier for the target entity. example: q3nouwy3nnbsvo3h5klxsx4a7y editgroup_id: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: | Editgroup identifier that this edit is part of. example: q3nouwy3nnbsvo3h5klxsx4a7y extra: type: object additionalProperties: {} 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 identifer. 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). editgroup: type: object properties: editgroup_id: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: | Fatcat identifier for this editgroup. Assigned on creation. example: q3nouwy3nnbsvo3h5klxsx4a7y editor_id: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: | Fatcat identifer of editor that created this editgroup. example: q3nouwy3nnbsvo3h5klxsx4a7y editor: $ref: "#/components/schemas/editor" changelog_index: type: integer example: 1048576 format: int64 description: | For accepted/merged editgroups, the changelog index that the accept occured at. WARNING: not populated in all contexts that an editgroup could be included in a response. created: type: string format: date-time description: | Timestamp when this editgroup was first created. submitted: type: string format: date-time description: > Timestamp when this editgroup was most recently submitted for review. If withdrawn, or never submitted, will be `null`. description: type: string description: > Comment describing the changes in this editgroup. Can be updated with PUT request. extra: type: object additionalProperties: {} description: | Free-form JSON metadata attached to this editgroup. Eg, metadata provenance, or script user-agent details. See guide for (unenforced) schema norms. annotations: type: array items: $ref: "#/components/schemas/editgroup_annotation" description: | Only included in GET responses, and not in all contexts. Do not include this field in PUT or POST requests. edits: type: object description: | Only included in GET responses, and not in all contexts. Do not include this field in PUT or POST requests. properties: containers: type: array items: $ref: "#/components/schemas/entity_edit" creators: type: array items: $ref: "#/components/schemas/entity_edit" files: type: array items: $ref: "#/components/schemas/entity_edit" filesets: type: array items: $ref: "#/components/schemas/entity_edit" webcaptures: type: array items: $ref: "#/components/schemas/entity_edit" releases: type: array items: $ref: "#/components/schemas/entity_edit" works: type: array items: $ref: "#/components/schemas/entity_edit" editgroup_annotation: type: object properties: annotation_id: 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 editgroup_id: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: | Editgroup that this annotation applies to. Set automatically in creations based on URL parameter. example: q3nouwy3nnbsvo3h5klxsx4a7y editor_id: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: | Defaults to editor created the annotation via POST request. example: q3nouwy3nnbsvo3h5klxsx4a7y editor: $ref: "#/components/schemas/editor" created: type: string format: date-time description: | Timestamp when annotation was first created. comment_markdown: type: string extra: type: object additionalProperties: {} description: | Additional free-form JSON metadata that can be included as part of the annotation (or even as the primary annotation itself). See guide for details. changelog_entry: type: object required: - index - editgroup_id - timestamp properties: index: type: integer format: int64 description: | Monotonically increasing sequence number of this changelog entry. editgroup_id: type: string example: q3nouwy3nnbsvo3h5klxsx4a7y description: | Identifier of editgroup accepted/merged in this changelog entry. timestamp: type: string format: date-time description: | Date and time when the editgroup was accpeted. editgroup: $ref: "#/components/schemas/editgroup" 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. release_contrib: type: object properties: index: type: integer format: int64 example: 0 description: | Internally assigned zero-indexed sequence number of contribution. Authors should come first; this encodes the order of attriubtion. creator_id: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: > If known, indicates the creator entity this contribution was made by. example: q3nouwy3nnbsvo3h5klxsx4a7y creator: $ref: "#/components/schemas/creator_entity" raw_name: type: string example: Jane K. Doe description: | Full name of the contributor as typeset in the release. given_name: type: string example: Jane description: | In English commonly the first name, but ordering is context and culture specific. surname: type: string example: Doe description: > In English commonly the last, or family name, but ordering is context and culture specific. role: type: string example: author description: | Short string (slug) indicating type of contribution (eg, "author", "translator"). See guide for list of accpeted values. raw_affiliation: type: string description: Raw affiliation string as displayed in text extra: type: object additionalProperties: {} description: | Additional free-form JSON metadata about this contributor/contribution. See guide for normative schema. container_auto_batch: type: object required: - editgroup - entity_list properties: editgroup: $ref: "#/components/schemas/editgroup" entity_list: type: array items: $ref: "#/components/schemas/container_entity" creator_auto_batch: type: object required: - editgroup - entity_list properties: editgroup: $ref: "#/components/schemas/editgroup" entity_list: type: array items: $ref: "#/components/schemas/creator_entity" file_auto_batch: type: object required: - editgroup - entity_list properties: editgroup: $ref: "#/components/schemas/editgroup" entity_list: type: array items: $ref: "#/components/schemas/file_entity" fileset_auto_batch: type: object required: - editgroup - entity_list properties: editgroup: $ref: "#/components/schemas/editgroup" entity_list: type: array items: $ref: "#/components/schemas/fileset_entity" webcapture_auto_batch: type: object required: - editgroup - entity_list properties: editgroup: $ref: "#/components/schemas/editgroup" entity_list: type: array items: $ref: "#/components/schemas/webcapture_entity" release_auto_batch: type: object required: - editgroup - entity_list properties: editgroup: $ref: "#/components/schemas/editgroup" entity_list: type: array items: $ref: "#/components/schemas/release_entity" work_auto_batch: type: object required: - editgroup - entity_list properties: editgroup: $ref: "#/components/schemas/editgroup" entity_list: type: array items: $ref: "#/components/schemas/work_entity" auth_oidc: type: object required: - provider - sub - iss - preferred_username properties: provider: type: string example: orcid description: | Fatcat-specific short name (slug) for remote service being used for authentication. sub: type: string description: "`SUB` from OIDC protocol. Usually a URL." example: https://orcid.org iss: type: string description: "`ISS` from OIDC protocol. Usually a stable account username, number, or identifier." example: 0000-0002-8593-9468 preferred_username: type: string description: | What it sounds like; returned by OIDC, and used as a hint when creating new editor accounts. Fatcat usernames are usually this string with the `provider` slug as a suffix, though some munging may occur. example: bnewbold auth_oidc_result: type: object required: - editor - token properties: editor: $ref: "#/components/schemas/editor" token: type: string example: AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug= auth_token_result: type: object required: - token properties: token: type: string example: AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug= x-auth-responses: &AUTHRESPONSES "401": description: Not Authorized # "Authentication information is missing or invalid" schema: $ref: "#/components/schemas/error_response" headers: WWW_Authenticate: type: string "403": description: Forbidden schema: $ref: "#/components/schemas/error_response" x-entity-responses: &ENTITYRESPONSES "400": description: Bad Request schema: $ref: "#/components/schemas/error_response" "404": description: Not Found schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error schema: $ref: "#/components/schemas/error_response" paths: "/editgroup/{editgroup_id}/container": parameters: - name: editgroup_id in: path required: true schema: type: string post: operationId: create_container tags: # TAGLINE - containers # TAGLINE description: | Create a single Container entity as part of an existing editgroup. Editgroup must be mutable (aka, not accepted) and editor must have permission (aka, have created the editgroup or have `admin` role). requestBody: $ref: "#/components/requestBodies/container_entity" security: - Bearer: [] responses: "201": description: Created Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /editgroup/auto/container/batch: post: operationId: create_container_auto_batch tags: # TAGLINE - containers # TAGLINE description: | Create a set of Container 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. requestBody: content: application/json: schema: $ref: "#/components/schemas/container_auto_batch" required: true security: - Bearer: [] responses: "201": description: Created Editgroup content: application/json: schema: $ref: "#/components/schemas/editgroup" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/container/{ident}": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_container tags: # TAGLINE - containers # TAGLINE description: | Fetches a single container entity from the catalog. parameters: - name: expand in: query required: false description: List of sub-entities to expand in response. For containers, none accepted (yet). schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. For containers, none accepted (yet). schema: type: string responses: "200": description: Found Entity content: application/json: schema: $ref: "#/components/schemas/container_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/container/{ident}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: ident in: path required: true schema: type: string put: operationId: update_container tags: # TAGLINE - containers # TAGLINE 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. requestBody: $ref: "#/components/requestBodies/container_entity" security: - Bearer: [] responses: "200": description: Updated Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" delete: operationId: delete_container tags: # TAGLINE - containers # TAGLINE 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_container_edit`. security: - Bearer: [] responses: "200": description: Deleted Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/container/rev/{rev_id}": parameters: - name: rev_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" get: operationId: get_container_revision tags: # TAGLINE - containers # TAGLINE 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 required: false description: List of sub-entities to expand in response. See `get_container`. schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_container`. schema: type: string responses: "200": description: Found Entity Revision content: application/json: schema: $ref: "#/components/schemas/container_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/container/{ident}/history": parameters: - name: ident in: path required: true schema: type: string - name: limit in: query required: false description: Maximum number of changelog entries to return schema: type: integer format: int64 get: tags: # TAGLINE - containers # TAGLINE description: | Fetches the history of accepted edits (changelog entries) for a specific entity fatcat identifier. operationId: get_container_history responses: "200": description: Found Entity History content: application/json: schema: type: array items: $ref: "#/components/schemas/entity_history_entry" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/container/{ident}/redirects": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_container_redirects tags: # TAGLINE - containers # TAGLINE description: | Returns the set of entity identifiers which currently redirect to this identifier. responses: "200": description: Found Entity Redirects content: application/json: schema: type: array items: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: base32-encoded unique identifier "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /container/lookup: get: operationId: lookup_container tags: # TAGLINE - containers # TAGLINE 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: issnl in: query required: false schema: type: string minLength: 9 maxLength: 9 pattern: \d{4}-\d{3}[0-9X] - name: issne in: query required: false schema: type: string minLength: 9 maxLength: 9 pattern: \d{4}-\d{3}[0-9X] - name: issnp in: query required: false schema: type: string minLength: 9 maxLength: 9 pattern: \d{4}-\d{3}[0-9X] - name: issn in: query required: false schema: type: string minLength: 9 maxLength: 9 pattern: \d{4}-\d{3}[0-9X] - name: wikidata_qid in: query required: false schema: type: string - name: expand in: query required: false description: List of sub-entities to expand in response. See `get_container`. schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_container`. schema: type: string responses: "200": description: Found Entity content: application/json: schema: $ref: "#/components/schemas/container_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/container/edit/{edit_id}": get: operationId: get_container_edit tags: # TAGLINE - containers # TAGLINE description: | Returns the entity edit object with the given identifier. This method is expected to be used rarely. parameters: - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" responses: "200": description: Found Edit content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/container/edit/{edit_id}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" delete: operationId: delete_container_edit tags: # TAGLINE - containers # TAGLINE 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: "200": description: Deleted Edit content: application/json: schema: $ref: "#/components/schemas/success" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/creator": parameters: - name: editgroup_id in: path required: true schema: type: string post: operationId: create_creator tags: # TAGLINE - creators # TAGLINE requestBody: $ref: "#/components/requestBodies/creator_entity" security: - Bearer: [] responses: "201": description: Created Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /editgroup/auto/creator/batch: post: operationId: create_creator_auto_batch tags: # TAGLINE - creators # TAGLINE requestBody: content: application/json: schema: $ref: "#/components/schemas/creator_auto_batch" required: true security: - Bearer: [] responses: "201": description: Created Editgroup content: application/json: schema: $ref: "#/components/schemas/editgroup" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/creator/{ident}": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_creator tags: # TAGLINE - creators # TAGLINE parameters: - name: expand in: query required: false description: List of sub-entities to expand in response. For creators, none accepted (yet). schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. For creators, none accepted (yet). schema: type: string responses: "200": description: Found Entity content: application/json: schema: $ref: "#/components/schemas/creator_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/creator/{ident}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: ident in: path required: true schema: type: string put: operationId: update_creator tags: # TAGLINE - creators # TAGLINE requestBody: $ref: "#/components/requestBodies/creator_entity" security: - Bearer: [] responses: "200": description: Updated Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" delete: operationId: delete_creator tags: # TAGLINE - creators # TAGLINE security: - Bearer: [] responses: "200": description: Deleted Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/creator/rev/{rev_id}": parameters: - name: rev_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" get: operationId: get_creator_revision tags: # TAGLINE - creators # TAGLINE parameters: - name: expand in: query required: false description: | List of sub-entities to expand in response. See `get_creator`, though note that identifier-based expansions (like `releases`) will always be empty for revisions. schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_creator`. schema: type: string responses: "200": description: Found Entity Revision content: application/json: schema: $ref: "#/components/schemas/creator_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/creator/{ident}/history": parameters: - name: ident in: path required: true schema: type: string - name: limit in: query required: false schema: type: integer format: int64 get: operationId: get_creator_history tags: # TAGLINE - creators # TAGLINE responses: "200": description: Found Entity History content: application/json: schema: type: array items: $ref: "#/components/schemas/entity_history_entry" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/creator/{ident}/releases": parameters: - name: ident in: path required: true schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_release`. schema: type: string get: operationId: get_creator_releases tags: # TAGLINE - creators # TAGLINE description: | Returns the set of Release entities having a `contrib` entry pointing to the creator entity. responses: "200": description: Found content: application/json: schema: type: array items: $ref: "#/components/schemas/release_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/creator/{ident}/redirects": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_creator_redirects tags: # TAGLINE - creators # TAGLINE responses: "200": description: Found Entity Redirects content: application/json: schema: type: array items: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: base32-encoded unique identifier "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /creator/lookup: get: operationId: lookup_creator tags: # TAGLINE - creators # TAGLINE parameters: - name: orcid in: query required: false description: ORCiD (https://orcid.org) identifier schema: type: string minLength: 19 maxLength: 19 pattern: \d{4}-\d{4}-\d{4}-\d{3}[\dX] - name: wikidata_qid in: query required: false schema: type: string - name: expand in: query required: false description: List of sub-entities to expand in response. See `get_creator`. schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_creator`. schema: type: string responses: "200": description: Found Entity content: application/json: schema: $ref: "#/components/schemas/creator_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/creator/edit/{edit_id}": get: operationId: get_creator_edit tags: # TAGLINE - creators # TAGLINE parameters: - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" responses: "200": description: Found Edit content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/creator/edit/{edit_id}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" delete: operationId: delete_creator_edit tags: # TAGLINE - creators # TAGLINE security: - Bearer: [] responses: "200": description: Deleted Edit content: application/json: schema: $ref: "#/components/schemas/success" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/file": parameters: - name: editgroup_id in: path required: true schema: type: string post: operationId: create_file tags: # TAGLINE - files # TAGLINE requestBody: $ref: "#/components/requestBodies/file_entity" security: - Bearer: [] responses: "201": description: Created Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /editgroup/auto/file/batch: post: operationId: create_file_auto_batch tags: # TAGLINE - files # TAGLINE requestBody: content: application/json: schema: $ref: "#/components/schemas/file_auto_batch" required: true security: - Bearer: [] responses: "201": description: Created Editgroup content: application/json: schema: $ref: "#/components/schemas/editgroup" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/file/{ident}": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_file tags: # TAGLINE - files # TAGLINE parameters: - name: expand in: query required: false description: List of sub-entities to expand in response. For files, `releases` is accepted. schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. For files, none accepted (yet). schema: type: string responses: "200": description: Found Entity content: application/json: schema: $ref: "#/components/schemas/file_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/file/{ident}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: ident in: path required: true schema: type: string put: operationId: update_file tags: # TAGLINE - files # TAGLINE requestBody: $ref: "#/components/requestBodies/file_entity" security: - Bearer: [] responses: "200": description: Updated Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" delete: operationId: delete_file tags: # TAGLINE - files # TAGLINE security: - Bearer: [] responses: "200": description: Deleted Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/file/rev/{rev_id}": parameters: - name: rev_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" get: operationId: get_file_revision tags: # TAGLINE - files # TAGLINE parameters: - name: expand in: query required: false description: List of sub-entities to expand in response. See `get_file`. schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_file`. schema: type: string responses: "200": description: Found Entity Revision content: application/json: schema: $ref: "#/components/schemas/file_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/file/{ident}/history": parameters: - name: ident in: path required: true schema: type: string - name: limit in: query required: false schema: type: integer format: int64 get: operationId: get_file_history tags: # TAGLINE - files # TAGLINE responses: "200": description: Found Entity History content: application/json: schema: type: array items: $ref: "#/components/schemas/entity_history_entry" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/file/{ident}/redirects": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_file_redirects tags: # TAGLINE - files # TAGLINE responses: "200": description: Found Entity Redirects content: application/json: schema: type: array items: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: base32-encoded unique identifier "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /file/lookup: get: operationId: lookup_file tags: # TAGLINE - files # TAGLINE parameters: - name: md5 in: query required: false description: MD5 hash of data, in hex encoding schema: type: string minLength: 32 maxLength: 32 pattern: "[a-f0-9]{32}" - name: sha1 in: query required: false description: SHA-1 hash of data, in hex encoding schema: type: string minLength: 40 maxLength: 40 pattern: "[a-f0-9]{40}" - name: sha256 in: query required: false description: SHA-256 hash of data, in hex encoding schema: type: string minLength: 64 maxLength: 64 pattern: "[a-f0-9]{64}" - name: expand in: query required: false description: List of sub-entities to expand in response. See `get_file`. schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_file`. schema: type: string responses: "200": description: Found Entity content: application/json: schema: $ref: "#/components/schemas/file_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/file/edit/{edit_id}": get: operationId: get_file_edit tags: # TAGLINE - files # TAGLINE parameters: - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" responses: "200": description: Found Edit content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/file/edit/{edit_id}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" delete: operationId: delete_file_edit tags: # TAGLINE - files # TAGLINE security: - Bearer: [] responses: "200": description: Deleted Edit content: application/json: schema: $ref: "#/components/schemas/success" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/fileset": parameters: - name: editgroup_id in: path required: true schema: type: string post: operationId: create_fileset tags: # TAGLINE - filesets # TAGLINE requestBody: $ref: "#/components/requestBodies/fileset_entity" security: - Bearer: [] responses: "201": description: Created Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /editgroup/auto/fileset/batch: post: operationId: create_fileset_auto_batch tags: # TAGLINE - filesets # TAGLINE requestBody: content: application/json: schema: $ref: "#/components/schemas/fileset_auto_batch" required: true security: - Bearer: [] responses: "201": description: Created Editgroup content: application/json: schema: $ref: "#/components/schemas/editgroup" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/fileset/{ident}": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_fileset tags: # TAGLINE - filesets # TAGLINE parameters: - name: expand in: query required: false description: List of sub-entities to expand in response. For filesets, `releases` is accepted. schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. For filesets, 'manifest' is accepted. schema: type: string responses: "200": description: Found Entity content: application/json: schema: $ref: "#/components/schemas/fileset_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/fileset/{ident}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: ident in: path required: true schema: type: string put: operationId: update_fileset tags: # TAGLINE - filesets # TAGLINE requestBody: $ref: "#/components/requestBodies/fileset_entity" security: - Bearer: [] responses: "200": description: Updated Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" delete: operationId: delete_fileset tags: # TAGLINE - filesets # TAGLINE security: - Bearer: [] responses: "200": description: Deleted Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/fileset/rev/{rev_id}": parameters: - name: rev_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" get: operationId: get_fileset_revision tags: # TAGLINE - filesets # TAGLINE parameters: - name: expand in: query required: false description: List of sub-entities to expand in response. See `get_fileset`. schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_fileset`. schema: type: string responses: "200": description: Found Entity Revision content: application/json: schema: $ref: "#/components/schemas/fileset_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/fileset/{ident}/history": parameters: - name: ident in: path required: true schema: type: string - name: limit in: query required: false schema: type: integer format: int64 get: operationId: get_fileset_history tags: # TAGLINE - filesets # TAGLINE responses: "200": description: Found Entity History content: application/json: schema: type: array items: $ref: "#/components/schemas/entity_history_entry" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/fileset/{ident}/redirects": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_fileset_redirects tags: # TAGLINE - filesets # TAGLINE responses: "200": description: Found Entity Redirects content: application/json: schema: type: array items: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: base32-encoded unique identifier "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/fileset/edit/{edit_id}": get: operationId: get_fileset_edit tags: # TAGLINE - filesets # TAGLINE parameters: - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" responses: "200": description: Found Edit content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/fileset/edit/{edit_id}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" delete: operationId: delete_fileset_edit tags: # TAGLINE - filesets # TAGLINE security: - Bearer: [] responses: "200": description: Deleted Edit content: application/json: schema: $ref: "#/components/schemas/success" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/webcapture": parameters: - name: editgroup_id in: path required: true schema: type: string post: operationId: create_webcapture tags: # TAGLINE - webcaptures # TAGLINE requestBody: $ref: "#/components/requestBodies/webcapture_entity" security: - Bearer: [] responses: "201": description: Created Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /editgroup/auto/webcapture/batch: post: operationId: create_webcapture_auto_batch tags: # TAGLINE - webcaptures # TAGLINE requestBody: content: application/json: schema: $ref: "#/components/schemas/webcapture_auto_batch" required: true security: - Bearer: [] responses: "201": description: Created Editgroup content: application/json: schema: $ref: "#/components/schemas/editgroup" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/webcapture/{ident}": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_webcapture tags: # TAGLINE - webcaptures # TAGLINE parameters: - name: expand in: query required: false description: List of sub-entities to expand in response. For webcaptures, `releases` is accepted. schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. For webcaptures, 'cdx' is accepted. schema: type: string responses: "200": description: Found Entity content: application/json: schema: $ref: "#/components/schemas/webcapture_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/webcapture/{ident}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: ident in: path required: true schema: type: string put: operationId: update_webcapture tags: # TAGLINE - webcaptures # TAGLINE requestBody: $ref: "#/components/requestBodies/webcapture_entity" security: - Bearer: [] responses: "200": description: Updated Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" delete: operationId: delete_webcapture tags: # TAGLINE - webcaptures # TAGLINE security: - Bearer: [] responses: "200": description: Deleted Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/webcapture/rev/{rev_id}": parameters: - name: rev_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" get: operationId: get_webcapture_revision tags: # TAGLINE - webcaptures # TAGLINE parameters: - name: expand in: query required: false description: List of sub-entities to expand in response. See `get_webcapture`. schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_webcapture`. schema: type: string responses: "200": description: Found Entity Revision content: application/json: schema: $ref: "#/components/schemas/webcapture_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/webcapture/{ident}/history": parameters: - name: ident in: path required: true schema: type: string - name: limit in: query required: false schema: type: integer format: int64 get: operationId: get_webcapture_history tags: # TAGLINE - webcaptures # TAGLINE responses: "200": description: Found Entity History content: application/json: schema: type: array items: $ref: "#/components/schemas/entity_history_entry" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/webcapture/{ident}/redirects": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_webcapture_redirects tags: # TAGLINE - webcaptures # TAGLINE responses: "200": description: Found Entity Redirects content: application/json: schema: type: array items: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: base32-encoded unique identifier "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/webcapture/edit/{edit_id}": get: operationId: get_webcapture_edit tags: # TAGLINE - webcaptures # TAGLINE parameters: - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" responses: "200": description: Found Edit content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/webcapture/edit/{edit_id}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" delete: operationId: delete_webcapture_edit tags: # TAGLINE - webcaptures # TAGLINE security: - Bearer: [] responses: "200": description: Deleted Edit content: application/json: schema: $ref: "#/components/schemas/success" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/release": parameters: - name: editgroup_id in: path required: true schema: type: string post: operationId: create_release tags: # TAGLINE - releases # TAGLINE 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). requestBody: $ref: "#/components/requestBodies/release_entity" security: - Bearer: [] responses: "201": description: Created Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /editgroup/auto/release/batch: post: operationId: create_release_auto_batch tags: # TAGLINE - releases # TAGLINE 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. requestBody: content: application/json: schema: $ref: "#/components/schemas/release_auto_batch" required: true security: - Bearer: [] responses: "201": description: Created Editgroup content: application/json: schema: $ref: "#/components/schemas/editgroup" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/release/{ident}": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_release tags: # TAGLINE - releases # TAGLINE description: | Fetches a single Release entity from the catalog. parameters: - name: expand in: query required: false description: | List of sub-entities to expand in response. For releases, 'files', 'filesets, 'webcaptures', 'container', and 'creators' are valid. schema: type: string - name: hide in: query required: false description: | List of entity fields to elide in response (for efficiency). For releases, 'abstracts', 'refs', and 'contribs' are valid. schema: type: string responses: "200": description: Found Entity content: application/json: schema: $ref: "#/components/schemas/release_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/release/{ident}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: ident in: path required: true schema: type: string put: operationId: update_release tags: # TAGLINE - releases # TAGLINE 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 requiest 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. requestBody: $ref: "#/components/requestBodies/release_entity" security: - Bearer: [] responses: "200": description: Updated Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" delete: operationId: delete_release tags: # TAGLINE - releases # TAGLINE 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: "200": description: Deleted Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/release/rev/{rev_id}": parameters: - name: rev_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" get: operationId: get_release_revision tags: # TAGLINE - releases # TAGLINE 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 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. schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_release`. schema: type: string responses: "200": description: Found Entity Revision content: application/json: schema: $ref: "#/components/schemas/release_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/release/{ident}/history": parameters: - name: ident in: path required: true schema: type: string - name: limit in: query required: false schema: type: integer format: int64 get: operationId: get_release_history tags: # TAGLINE - releases # TAGLINE description: | Fetches the history of accepted edits (changelog entries) for a specific entity fatcat identifier. responses: "200": description: Found Entity History content: application/json: schema: type: array items: $ref: "#/components/schemas/entity_history_entry" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/release/{ident}/files": parameters: - name: ident in: path required: true schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_file`. schema: type: string get: operationId: get_release_files tags: # TAGLINE - releases # TAGLINE description: | Returns the set of File entities that have a `release_id` pointing to this release entity. responses: "200": description: Found content: application/json: schema: type: array items: $ref: "#/components/schemas/file_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/release/{ident}/filesets": parameters: - name: ident in: path required: true schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_fileset`. schema: type: string get: operationId: get_release_filesets tags: # TAGLINE - releases # TAGLINE description: | Returns the set of Fileset entities that have a `release_id` pointing to this release entity. responses: "200": description: Found content: application/json: schema: type: array items: $ref: "#/components/schemas/fileset_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/release/{ident}/webcaptures": parameters: - name: ident in: path required: true schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_webcapture`. schema: type: string get: operationId: get_release_webcaptures tags: # TAGLINE - releases # TAGLINE description: | Returns the set of Web Capture entities that have a `release_id` pointing to this release entity. responses: "200": description: Found content: application/json: schema: type: array items: $ref: "#/components/schemas/webcapture_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/release/{ident}/redirects": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_release_redirects tags: # TAGLINE - releases # TAGLINE description: | Returns the set of entity identifiers which currently redirect to this identifier. responses: "200": description: Found Entity Redirects content: application/json: schema: type: array items: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: base32-encoded unique identifier "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /release/lookup: get: operationId: lookup_release tags: # TAGLINE - releases # TAGLINE 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 required: false schema: type: string - name: wikidata_qid in: query required: false schema: type: string - name: isbn13 in: query required: false schema: type: string - name: pmid in: query required: false schema: type: string - name: pmcid in: query required: false schema: type: string - name: core in: query required: false schema: type: string - name: arxiv in: query required: false schema: type: string - name: jstor in: query required: false schema: type: string - name: ark in: query required: false schema: type: string - name: mag in: query required: false schema: type: string - name: doaj in: query required: false schema: type: string - name: dblp in: query required: false schema: type: string - name: oai in: query required: false schema: type: string - name: hdl in: query required: false schema: type: string - name: expand in: query required: false description: List of sub-entities to expand in response. See `get_release`. schema: type: string - name: hide in: query required: false description: List of sub-entities to elide in response. See `get_release`. schema: type: string responses: "200": description: Found Entity content: application/json: schema: $ref: "#/components/schemas/release_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/release/edit/{edit_id}": get: operationId: get_release_edit tags: # TAGLINE - releases # TAGLINE description: | Returns the entity edit object with the given identifier. This method is expected to be used rarely. parameters: - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" responses: "200": description: Found Edit content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/release/edit/{edit_id}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" delete: operationId: delete_release_edit tags: # TAGLINE - releases # TAGLINE 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: "200": description: Deleted Edit content: application/json: schema: $ref: "#/components/schemas/success" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/work": parameters: - name: editgroup_id in: path required: true schema: type: string post: operationId: create_work tags: # TAGLINE - works # TAGLINE requestBody: $ref: "#/components/requestBodies/work_entity" security: - Bearer: [] responses: "201": description: Created Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /editgroup/auto/work/batch: post: operationId: create_work_auto_batch tags: # TAGLINE - works # TAGLINE requestBody: content: application/json: schema: $ref: "#/components/schemas/work_auto_batch" required: true security: - Bearer: [] responses: "201": description: Created Editgroup content: application/json: schema: $ref: "#/components/schemas/editgroup" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/work/{ident}": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_work tags: # TAGLINE - works # TAGLINE parameters: - name: expand in: query required: false description: List of sub-entities to expand in response. For works, none accepted (yet). schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. For works, none accepted (yet). schema: type: string responses: "200": description: Found Entity content: application/json: schema: $ref: "#/components/schemas/work_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/work/{ident}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: ident in: path required: true schema: type: string put: operationId: update_work tags: # TAGLINE - works # TAGLINE requestBody: $ref: "#/components/requestBodies/work_entity" security: - Bearer: [] responses: "200": description: Updated Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" delete: operationId: delete_work tags: # TAGLINE - works # TAGLINE security: - Bearer: [] responses: "200": description: Deleted Entity content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/work/rev/{rev_id}": parameters: - name: rev_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" get: operationId: get_work_revision tags: # TAGLINE - works # TAGLINE parameters: - name: expand in: query required: false description: List of sub-entities to expand in response. See `get_work`, though note that identifier-based expansions like `releases` will always be empty for revisions. schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_work`. schema: type: string responses: "200": description: Found Entity Revision content: application/json: schema: $ref: "#/components/schemas/work_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/work/{ident}/history": parameters: - name: ident in: path required: true schema: type: string - name: limit in: query required: false schema: type: integer format: int64 get: operationId: get_work_history tags: # TAGLINE - works # TAGLINE responses: "200": description: Found Entity History content: application/json: schema: type: array items: $ref: "#/components/schemas/entity_history_entry" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/work/{ident}/redirects": parameters: - name: ident in: path required: true schema: type: string get: operationId: get_work_redirects tags: # TAGLINE - works # TAGLINE responses: "200": description: Found Entity Redirects content: application/json: schema: type: array items: type: string pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: base32-encoded unique identifier "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/work/{ident}/releases": parameters: - name: ident in: path required: true schema: type: string - name: hide in: query required: false description: List of entity fields to elide in response. See `get_release`. schema: type: string get: operationId: get_work_releases tags: # TAGLINE - works # TAGLINE description: | Returns the set of release entities that are part of this work (aka, have `work_id` pointing to this work entity). responses: "200": description: Found content: application/json: schema: type: array items: $ref: "#/components/schemas/release_entity" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/work/edit/{edit_id}": get: operationId: get_work_edit tags: # TAGLINE - works # TAGLINE parameters: - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" responses: "200": description: Found Edit content: application/json: schema: $ref: "#/components/schemas/entity_edit" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/work/edit/{edit_id}": parameters: - name: editgroup_id in: path required: true schema: type: string - name: edit_id in: path required: true description: UUID (lower-case, dash-separated, hex-encoded 128-bit) schema: type: string minLength: 36 maxLength: 36 pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" delete: operationId: delete_work_edit tags: # TAGLINE - works # TAGLINE security: - Bearer: [] responses: "200": description: Deleted Edit content: application/json: schema: $ref: "#/components/schemas/success" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editor/{editor_id}": parameters: - name: editor_id in: path required: true schema: type: string get: operationId: get_editor tags: # TAGLINE - editors # TAGLINE description: | Returns an editor object, including metadata such as the username, type, and role of editor. responses: "200": description: Found content: application/json: schema: $ref: "#/components/schemas/editor" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" put: operationId: update_editor tags: # TAGLINE - editors # TAGLINE description: | Allows metadata changes to some editor fields, such as the username. Changes require authentication and permissions. An editor can change their own username; changes to role flags require the `admin` role by the editor making the request. requestBody: content: application/json: schema: $ref: "#/components/schemas/editor" required: true security: - Bearer: [] responses: "200": description: Updated Editor content: application/json: schema: $ref: "#/components/schemas/editor" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editor/{editor_id}/editgroups": parameters: - name: editor_id in: path required: true schema: type: string get: operationId: get_editor_editgroups tags: # TAGLINE - editors # TAGLINE description: | Returns a set of editgroups created by the given editor, regardless of the status (accepted/submitted) of the editgroups. parameters: - name: limit in: query required: false schema: type: integer format: int64 - name: before in: query required: false description: | Return only editgroups created *before* the given timestamp (not inclusive). Editgroups will be sorted by creation time in descending order (most recent first). For use in pagination. schema: type: string format: date-time - name: since in: query required: false description: | Return only editgroups created *after* the given timestamp (not inclusive). Editgroups will be sorted by creation time in ascending order (most recent last). For use in pagination. schema: type: string format: date-time responses: "200": description: Found content: application/json: schema: type: array items: $ref: "#/components/schemas/editgroup" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editor/{editor_id}/annotations": parameters: - name: editor_id in: path required: true description: base32-encoded unique identifier schema: type: string minLength: 26 maxLength: 26 pattern: "[a-zA-Z2-7]{26}" get: operationId: get_editor_annotations tags: # TAGLINE - editors # TAGLINE description: | Fetches a list of annotations made by a particular editor. parameters: - name: limit in: query required: false description: Maximum number (count) of annotations to return in response schema: type: integer format: int64 - name: before in: query required: false description: | Return only annotations made *before* the given timestamp (not inclusive). Annotations will be sorted by creation time in descending order (most recent first). For use in pagination. schema: type: string format: date-time - name: since in: query required: false description: | Return only annotations made *after* the given timestamp (not inclusive). Annotations will be sorted by creation time in ascending order (most recent last). For use in pagination. schema: type: string format: date-time responses: "200": description: Success content: application/json: schema: type: array items: $ref: "#/components/schemas/editgroup_annotation" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /editor/lookup: get: operationId: lookup_editor tags: # TAGLINE - editors # TAGLINE description: | Fetches editor by, eg, username. One (and only one) lookup identifier should be specified per request. parameters: - name: username in: query required: false schema: type: string responses: "200": description: Found content: application/json: schema: $ref: "#/components/schemas/editor" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /editgroup: post: operationId: create_editgroup tags: # TAGLINE - editgroups # TAGLINE description: | Creates a new editgroup. By default the editor making this request will be the author of the editgroup. requestBody: $ref: "#/components/requestBodies/editgroup" security: - Bearer: [] responses: "201": description: Successfully Created content: application/json: schema: $ref: "#/components/schemas/editgroup" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}": parameters: - name: editgroup_id in: path required: true description: base32-encoded unique identifier schema: type: string minLength: 26 maxLength: 26 pattern: "[a-zA-Z2-7]{26}" get: operationId: get_editgroup tags: # TAGLINE - editgroups # TAGLINE description: | Returns a single editgroup object. Unlike some similar methods, this method will return a full/expanded editgroup object, which includes edit lists of each entity type (though will not include the complete entity objects). responses: "200": description: Found content: application/json: schema: $ref: "#/components/schemas/editgroup" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" put: operationId: update_editgroup tags: # TAGLINE - editgroups # TAGLINE description: | Updates metadata for a single editgroup object. Note that only metadata fields such as the `description` or `extra` metadata can be changed with this method; it does not allow adding or removing edits to the editgroup (for that use the individual entity create/update/delete methods). security: - Bearer: [] parameters: - name: submit in: query required: false schema: type: boolean requestBody: $ref: "#/components/requestBodies/editgroup" responses: "200": description: Updated Editgroup content: application/json: schema: $ref: "#/components/schemas/editgroup" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/accept": parameters: - name: editgroup_id in: path required: true description: base32-encoded unique identifier schema: type: string minLength: 26 maxLength: 26 pattern: "[a-zA-Z2-7]{26}" post: operationId: accept_editgroup tags: # TAGLINE - editgroups # TAGLINE description: | Accept ("merge") the given editgroup into the catalog. The editgroup must be open (not already accepted), and the editor making this request must have the `admin` role. security: - Bearer: [] responses: "200": description: Merged Successfully content: application/json: schema: $ref: "#/components/schemas/success" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "409": description: Edit Conflict content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/annotations": parameters: - name: editgroup_id in: path required: true description: base32-encoded unique identifier schema: type: string minLength: 26 maxLength: 26 pattern: "[a-zA-Z2-7]{26}" get: operationId: get_editgroup_annotations tags: # TAGLINE - editgroups # TAGLINE description: Returns a list of annotations made to a specific editgroup. parameters: - name: expand in: query required: false description: "List of sub-entities to expand in response. For editgroup annotations: 'editors'" schema: type: string responses: "200": description: Success content: application/json: schema: type: array items: $ref: "#/components/schemas/editgroup_annotation" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/editgroup/{editgroup_id}/annotation": parameters: - name: editgroup_id in: path required: true description: base32-encoded unique identifier schema: type: string minLength: 26 maxLength: 26 pattern: "[a-zA-Z2-7]{26}" post: operationId: create_editgroup_annotation tags: # TAGLINE - editgroups # TAGLINE description: | Submits a new annotation to the specified editgroup. The editgroup must be open (not already accepted). The annotation will automatically have authorship of the editor making this request. security: - Bearer: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/editgroup_annotation" required: true responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/editgroup_annotation" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /editgroup/reviewable: get: operationId: get_editgroups_reviewable tags: # TAGLINE - editgroups # TAGLINE description: > Returns a set of editgroups which have been submitted but not yet accepted. Query parameters can be used to sort and paginate the list returned. parameters: - name: expand in: query required: false description: "List of sub-entities to expand in response. For editgroups: 'editors'" schema: type: string - name: limit in: query required: false description: Maximum number of reviewable editgroups to return in response schema: type: integer format: int64 - name: before in: query required: false description: | Return only reviewable editgroups submitted *before* the given timestamp (not inclusive). Editgroups will be sorted by submission time in descending order (most recent first). For use in pagination. schema: type: string format: date-time - name: since in: query required: false description: | Return only reviewable editgroups submitted *after* the given timestamp (not inclusive). Editgroups will be sorted by submission time in ascending order (most recent last). For use in pagination. schema: type: string format: date-time responses: "200": description: Found content: application/json: schema: type: array items: $ref: "#/components/schemas/editgroup" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /changelog: parameters: - name: limit in: query required: false description: Maximum count of changelog entries to return in response schema: type: integer format: int64 get: operationId: get_changelog tags: # TAGLINE - changelog # TAGLINE description: | Returns a list of the most recent changelog entries accepted (merged) into the catalog. List is sorted by changelog index in descending order. Note that the accepted timestamp roughly corresponds to order, but not strictly; there exist out-of-order timestamps on the order of several seconds. As a known database issue, it is technically possible for there to be a gap in changelog index numbers (aka, a missing changelog entry). There are no currently known gaps and this is considered a bug that will be addressed. There are millions of entries; to paginate through all of them, use this method to discover the highest existing entry number, then request the entries using `get_changelog_entry` one at a time. responses: "200": description: Success content: application/json: schema: type: array items: $ref: "#/components/schemas/changelog_entry" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/changelog/{index}": parameters: - name: index in: path required: true description: Changelog index of entry to return schema: type: integer format: int64 get: operationId: get_changelog_entry tags: # TAGLINE - changelog # TAGLINE description: | Returns a single changelog entry. As a known database issue, it is technically possible for there to be a gap in changelog index numbers (aka, a missing changelog entry). There are no currently known gaps and this is considered a bug that will be addressed. responses: "200": description: Found Changelog Entry content: application/json: schema: $ref: "#/components/schemas/changelog_entry" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "404": description: Not Found content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /auth/oidc: post: operationId: auth_oidc tags: # TAGLINE - auth # TAGLINE description: | Login or create editor account using OIDC metadata (internal method). This method is used by privileged front-end tools (like the web interface service) to process editor logins using OpenID Connect (OIDC) and/or OAuth. Most accounts (including tool and bot accounts) do not have sufficient privileges to call this method, which requires the `admin` role. The method returns an API token; the HTTP status code indicates whether an existing account was logged in, or a new account was created. security: - Bearer: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/auth_oidc" required: true responses: "200": description: Found content: application/json: schema: $ref: "#/components/schemas/auth_oidc_result" "201": description: Created content: application/json: schema: $ref: "#/components/schemas/auth_oidc_result" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "409": description: Conflict content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" /auth/check: get: operationId: auth_check tags: # TAGLINE - auth # TAGLINE description: | Verify that authentication (API token) is working as expected. The optional `role` parameter can be used to verify that the current account (editor) has permissions for the given role. security: - Bearer: [] parameters: - name: role in: query required: false schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/success" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response" "/auth/token/{editor_id}": parameters: - name: editor_id in: path required: true schema: type: string post: operationId: create_auth_token tags: # TAGLINE - auth # TAGLINE description: | Generate a new auth token for a given editor (internal method). This method is used by the web interface to generate API tokens for users. It can not be called by editors (human or bot) to generate new tokens for themselves, at least at this time. security: # required admin privs - Bearer: [] parameters: - name: duration_seconds in: query required: false description: How long API token should be valid for (in seconds) schema: type: integer responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/auth_token_result" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error_response" "401": description: Not Authorized headers: WWW_Authenticate: schema: type: string content: application/json: schema: $ref: "#/components/schemas/error_response" "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error_response" "500": description: Generic Error content: application/json: schema: $ref: "#/components/schemas/error_response"