diff options
| -rw-r--r-- | fatcat-openapi3.yml | 7083 |
1 files changed, 7083 insertions, 0 deletions
diff --git a/fatcat-openapi3.yml b/fatcat-openapi3.yml new file mode 100644 index 0000000..f8e3ca4 --- /dev/null +++ b/fatcat-openapi3.yml @@ -0,0 +1,7083 @@ +openapi: "3.0.0" +info: + title: fatcat + version: 0.3.1 + description: | + Fatcat is a scalable, versioned, API-oriented catalog of bibliographic + entities and file metadata. + + <!-- STARTLONGDESCRIPTION --> + These API reference documents, along with client software libraries, are + generated automatically from an OpenAPI 2.0 ("Swagger") definition file. + + ## Introduction + + A higher-level introduction to the API, as well as a description of the + fatcat data model, are available in ["The Fatcat Guide"](https://guide.fatcat.wiki/). + The guide also includes a [Cookbook](https://guide.fatcat.wiki/cookbook.html) + section demonstrating end-to-end tasks like creating entities as part of + editgroups, or safely merging duplicate entities. + + ### Expectations and Best Practices + + A test/staging QA API instance of fatcat is available at + <https://api.qa.fatcat.wiki/v0>. The database backing this instance is + separate from the production interface, and is periodically rebuilt from + snapshots of the full production database, meaning that edits on the QA + server will *NOT* persist, and that semantics like the changelog index + monotonically increasing *MAY* be broken. Developers are expexcted to test + their scripts and tools against the QA instance before running against + production. + + 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 <https://search.fatcat.wiki> (and + <https://search.qa.fatcat.wiki>). The API is currently the raw + elasticsearch API, with only GET (read) requests allowed. This public + service is experimental and may be removed or limited in the future. + + ## Authentication + + The API allows basic read-only "GET" HTTP requests with no authentication. + Proposing changes to the metadata, or other mutating requests ("PUT", + "POST", "DELETE") all require authentication, and some operations require + additional account permissions. + + End-user account creation and login happens through the web interface. From + a logged-in editor profile page, you can generate a API token. Tokens are + "macaroons", similar to JWT tokens, and are used for all API + authentication. The web interface includes macaroons in browser cookies and + passes them through to the API to authenticate editor actions. + + <!-- ReDoc-Inject: <security-definitions> --> + <!-- ENDLONGDESCRIPTION --> + + termsOfService: "https://guide.fatcat.wiki/policies.html" + contact: + name: "Internet Archive Web Group" + email: "webservices@archive.org" + url: "https://fatcat.wiki" + x-logo: + url: "https://fatcat.wiki/static/paper_man_confused.gif" + altText: "Confused Papers Man (Logo)" + backgroundColor: "#FFFFFF" + +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 + 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 + 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 + 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: {} + 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 + extra: + type: object + additionalProperties: {} + description: | + Free-form additional metadata about this specific file in the set. + Eg, `mimetype`. See guide for nomative (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. + 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 + 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: 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: 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" + /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" + + + |