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"