aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--fatcat-openapi3.yml7083
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"
+
+
+