---
swagger: "2.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 bulid 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"
schemes: [https]
basePath: /v0
host: api.fatcat.wiki
consumes:
  - application/json
produces:
  - application/json

x-servers:
- url: https://api.fatcat.wiki/v0
  description: "Production Server"
- url: https://api.qa.fatcat.wiki/v0
  description: "QA Server"

securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header
    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

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:
 - name: Entities
   tags:
    - containers
    - creators
    - files
    - filesets
    - webcaptures
    - releases
    - works
 - name: Editing
   tags:
    - editors
    - editgroups
    - changelog
 - name: Other
   tags:
    - auth

# 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: {}

definitions:
  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
    # required for creation: name
    properties:
      <<: *ENTITYPROPS
      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"
        <<: *FATCATISSN
        <<: *FATCATISSNEXAMPLE
      wikidata_qid:
        type: string
        example: "Q42812"
  creator_entity:
    type: object
    # required for creation: display_name
    properties:
      <<: *ENTITYPROPS
      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:
        <<: *FATCATORCID
        <<: *FATCATORCIDEXAMPLE
      wikidata_qid:
        type: string
        example: "Q42812"
        description: "Wikidata entity QID"
  file_entity:
    type: object
    properties:
      <<: *ENTITYPROPS
      size:
        type: integer
        example: 1048576
        format: int64
        description: "Size of file in bytes. Non-zero."
      md5:
        <<: *FATCATMD5
        <<: *FATCATMD5EXAMPLE
      sha1:
        <<: *FATCATSHA1
        <<: *FATCATSHA1EXAMPLE
      sha256:
        <<: *FATCATSHA256
        <<: *FATCATSHA256EXAMPLE
      urls:
        type: array
        items:
          $ref: "#/definitions/file_url"
      mimetype:
        type: string
        example: "application/pdf"
      release_ids:
        type: array
        items:
          <<: *FATCATIDENT
          <<: *FATCATIDENTEXAMPLE
        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: "#/definitions/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:
      <<: *ENTITYPROPS
      manifest:
        # limit of 200 files, at least to start
        type: array
        items:
          $ref: "#/definitions/fileset_file"
      urls:
        type: array
        items:
          $ref: "#/definitions/fileset_url"
      release_ids:
        type: array
        items:
          <<: *FATCATIDENT
          <<: *FATCATIDENTEXAMPLE
        description: |
          Set of identifier of release entities this fileset represents a full
          manifestation of. Usually a single release.
      releases:
        type: array
        items:
          $ref: "#/definitions/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:
        <<: *FATCATMD5
        <<: *FATCATMD5EXAMPLE
      sha1:
        <<: *FATCATSHA1
        <<: *FATCATSHA1EXAMPLE
      sha256:
        <<: *FATCATSHA256
        <<: *FATCATSHA256EXAMPLE
      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:
      <<: *ENTITYPROPS
      cdx:
        # limit of 200 CDX lines, at least to start?
        type: array
        items:
          $ref: "#/definitions/webcapture_cdx_line"
      archive_urls:
        type: array
        items:
          $ref: "#/definitions/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:
          <<: *FATCATIDENT
          <<: *FATCATIDENTEXAMPLE
        description: |
          Set of identifier of release entities this fileset represents a full
          manifestation of. Usually a single release.
      releases:
        type: array
        items:
          $ref: "#/definitions/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
        # NOTE: not format:url to allow alternatives
        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:
        <<: *FATCATSHA1
        <<: *FATCATSHA1EXAMPLE
      sha256:
        <<: *FATCATSHA256
        <<: *FATCATSHA256EXAMPLE
  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 for creation: title
    required:
      - ext_ids
    properties:
      <<: *ENTITYPROPS
      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: "#/definitions/container_entity"
        description: |
          Complete container entity identified by `container_id` field. Only
          included in GET reponses when `container` included in `expand`
          parameter; ignored in PUT or POST requests.
      files:
        type: array
        items:
          $ref: "#/definitions/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: "#/definitions/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: "#/definitions/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: "#/definitions/release_ext_ids"
        description: |
          Set of external identifiers for this release.
      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: "#/definitions/release_contrib"
      refs:
        type: array
        items:
          $ref: "#/definitions/release_ref"
      abstracts:
        type: array
        items:
          $ref: "#/definitions/release_abstract"
  release_ext_ids:
    type: object
    properties:
      doi:
        type: string
        #format: custom
        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
        #format: custom
        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:
        exmaple: "9234592"
        type: string
        #format: custom
        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:
        <<: *FATCATSHA1
        <<: *FATCATSHA1EXAMPLE
      content:
        type: string
        example: "<jats:p>Some abstract thing goes here</jats:p>"
        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:
      <<: *ENTITYPROPS
  entity_history_entry:
    type: object
    required:
      - edit
      - editgroup
      - changelog_entry
    properties:
      edit:
        $ref: "#/definitions/entity_edit"
      editgroup:
        $ref: "#/definitions/editgroup"
      changelog_entry:
        $ref: "#/definitions/changelog_entry"
  entity_edit:
    type: object
    required:
      - edit_id
      - ident
      - editgroup_id
    properties:
      edit_id:
          <<: *FATCATUUID
          <<: *FATCATUUIDEXAMPLE
          description: |
            Unique UUID for this specific edit object.
      ident:
          <<: *FATCATIDENT
          <<: *FATCATIDENTEXAMPLE
          description: |
            Fatcat identifier of the entity this edit is mutating.
      revision:
          <<: *FATCATUUID
          <<: *FATCATUUIDEXAMPLE
          description: |
            Entity revision that this edit will set the entity to. May be
            `null` in the case of deletions.
      prev_revision:
          <<: *FATCATUUID
          <<: *FATCATUUIDEXAMPLE
          description: |
            Revision of entity just before this edit. May be used in the future
            to prevent edit race conditions.
      redirect_ident:
          <<: *FATCATIDENT
          <<: *FATCATIDENTEXAMPLE
          description: |
            When an edit is to merge entities (redirect one to another), this
            is the entity fatcat identifier for the target entity.
      editgroup_id:
          <<: *FATCATIDENT
          <<: *FATCATIDENTEXAMPLE
          description: |
            Editgroup identifier that this edit is part of.
      extra:
          type: object
          additionalProperties: {}
  editor:
    type: object
    required:
      - username
    properties:
      editor_id:
        <<: *FATCATIDENT
        <<: *FATCATIDENTEXAMPLE
        description: |
          Fatcat identifier for the editor. Can not be changed.
      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:
        <<: *FATCATIDENT
        <<: *FATCATIDENTEXAMPLE
        description: |
          Fatcat identifier for this editgroup. Assigned on creation.
      editor_id:
        <<: *FATCATIDENT
        <<: *FATCATIDENTEXAMPLE
        description: |
          Fatcat identifer of editor that created this editgroup.
      editor:
        $ref: "#/definitions/editor"
        description: |
          Complete editor object identified by `container_id` field. Only
          included in GET responses.
      changelog_index: # not returned in all contexts...
        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: "#/definitions/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: "#/definitions/entity_edit"
          creators:
            type: array
            items:
              $ref: "#/definitions/entity_edit"
          files:
            type: array
            items:
              $ref: "#/definitions/entity_edit"
          filesets:
            type: array
            items:
              $ref: "#/definitions/entity_edit"
          webcaptures:
            type: array
            items:
              $ref: "#/definitions/entity_edit"
          releases:
            type: array
            items:
              $ref: "#/definitions/entity_edit"
          works:
            type: array
            items:
              $ref: "#/definitions/entity_edit"
  editgroup_annotation:
    type: object
    properties:
      annotation_id:
        <<: *FATCATUUID
        <<: *FATCATUUIDEXAMPLE
      editgroup_id:
        <<: *FATCATIDENT
        <<: *FATCATIDENTEXAMPLE
        description: |
          Editgroup that this annotation applies to. Set automatically in
          creations based on URL parameter.
      editor_id:
        <<: *FATCATIDENT
        <<: *FATCATIDENTEXAMPLE
        description: |
          Defaults to editor created the annotation via POST request.
      editor:
        $ref: "#/definitions/editor"
        description: |
          Only included in GET responses; ignored in PUT or POST requests.
      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: "#/definitions/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:
        <<: *FATCATIDENT
        <<: *FATCATIDENTEXAMPLE
        description: |
          Optional, fatcat identifier of release entity that this reference is
          citing.
      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:
        <<: *FATCATIDENT
        <<: *FATCATIDENTEXAMPLE
        description: |
          If known, indicates the creator entity this contribution was made by.
      creator:
        $ref: "#/definitions/creator_entity"
        description: |
          Complete creator entity. Only returned in GET responses, and only if
          `contribs` included in the `expand` query parameter.
      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: "#/definitions/editgroup"
      entity_list:
        type: array
        items:
          $ref: "#/definitions/container_entity"
  creator_auto_batch:
    type: object
    required:
      - editgroup
      - entity_list
    properties:
      editgroup:
        $ref: "#/definitions/editgroup"
      entity_list:
        type: array
        items:
          $ref: "#/definitions/creator_entity"
  file_auto_batch:
    type: object
    required:
      - editgroup
      - entity_list
    properties:
      editgroup:
        $ref: "#/definitions/editgroup"
      entity_list:
        type: array
        items:
          $ref: "#/definitions/file_entity"
  fileset_auto_batch:
    type: object
    required:
      - editgroup
      - entity_list
    properties:
      editgroup:
        $ref: "#/definitions/editgroup"
      entity_list:
        type: array
        items:
          $ref: "#/definitions/fileset_entity"
  webcapture_auto_batch:
    type: object
    required:
      - editgroup
      - entity_list
    properties:
      editgroup:
        $ref: "#/definitions/editgroup"
      entity_list:
        type: array
        items:
          $ref: "#/definitions/webcapture_entity"
  release_auto_batch:
    type: object
    required:
      - editgroup
      - entity_list
    properties:
      editgroup:
        $ref: "#/definitions/editgroup"
      entity_list:
        type: array
        items:
          $ref: "#/definitions/release_entity"
  work_auto_batch:
    type: object
    required:
      - editgroup
      - entity_list
    properties:
      editgroup:
        $ref: "#/definitions/editgroup"
      entity_list:
        type: array
        items:
            $ref: "#/definitions/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: "#/definitions/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: "#/definitions/error_response"
    headers:
      WWW_Authenticate:
        type: string
  403:
    description: Forbidden
    schema:
      $ref: "#/definitions/error_response"
x-entity-responses: &ENTITYRESPONSES
  400:
    description: Bad Request
    schema:
      $ref: "#/definitions/error_response"
  404:
    description: Not Found
    schema:
      $ref: "#/definitions/error_response"
  500:
    description: Generic Error
    schema:
      $ref: "#/definitions/error_response"

paths:
  /editgroup/{editgroup_id}/container:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
    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 editgrou p or have `admin` role).
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/container_entity"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /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.
      parameters:
        - name: auto_batch
          in: body
          required: true
          schema:
            $ref: "#/definitions/container_auto_batch"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Editgroup
          schema:
            $ref: "#/definitions/editgroup"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /container/{ident}:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    get:
      operationId: "get_container"
      tags: # TAGLINE
        - containers # TAGLINE
      description: |
        Fetches a single container entity from the catalog.
      parameters:
        - name: expand
          in: query
          type: string
          required: false
          description: "List of sub-entities to expand in response. For containers, none accepted (yet)."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. For containers, none accepted (yet)."
      responses:
        200:
          description: Found Entity
          schema:
            $ref: "#/definitions/container_entity"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/container/{ident}:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
      - name: ident
        in: path
        type: string
        required: true
    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 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.
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/container_entity"
      security:
        - Bearer: []
      responses:
        200:
          description: Updated Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
    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
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /container/rev/{rev_id}:
    parameters:
      - name: rev_id
        in: path
        required: true
        <<: *FATCATUUID
    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
          type: string
          required: false
          description: "List of sub-entities to expand in response. See `get_container`."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. See `get_container`."
      responses:
        200:
          description: Found Entity Revision
          schema:
            $ref: "#/definitions/container_entity"
        <<: *ENTITYRESPONSES
  /container/{ident}/history:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
      - name: limit
        in: query
        type: integer
        format: int64
        required: false
        description: "Maximum number of changelog entries to return"
    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
          schema:
            type: array
            items:
              $ref: "#/definitions/entity_history_entry"
        <<: *ENTITYRESPONSES
  /container/{ident}/redirects:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    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
          schema:
            type: array
            items:
              <<: *FATCATIDENT
        <<: *ENTITYRESPONSES
  /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
          <<: *FATCATISSN
        - name: wikidata_qid
          in: query
          type: string
          required: false
        - name: expand
          in: query
          type: string
          required: false
          description: "List of sub-entities to expand in response. See `get_container`."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. See `get_container`."
      responses:
        200:
          description: Found Entity
          schema:
            $ref: "#/definitions/container_entity"
        <<: *ENTITYRESPONSES
  /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
          <<: *FATCATUUID
      responses:
        200:
          description: Found Edit
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/container/edit/{edit_id}:
    parameters:
      - name: editgroup_id
        in: path
        required: true
        type: string
      - name: edit_id
        in: path
        required: true
        <<: *FATCATUUID
    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
          schema:
            $ref: "#/definitions/success"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES

  /editgroup/{editgroup_id}/creator:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
    post:
      operationId: "create_creator"
      tags: # TAGLINE
        - creators # TAGLINE
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/creator_entity"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /editgroup/auto/creator/batch:
    post:
      operationId: "create_creator_auto_batch"
      tags: # TAGLINE
        - creators # TAGLINE
      parameters:
        - name: auto_batch
          in: body
          required: true
          schema:
            $ref: "#/definitions/creator_auto_batch"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Editgroup
          schema:
            $ref: "#/definitions/editgroup"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /creator/{ident}:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    get:
      operationId: "get_creator"
      tags: # TAGLINE
        - creators # TAGLINE
      parameters:
        - name: expand
          in: query
          type: string
          required: false
          description: "List of sub-entities to expand in response. For creators, none accepted (yet)."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. For creators, none accepted (yet)."
      responses:
        200:
          description: Found Entity
          schema:
            $ref: "#/definitions/creator_entity"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/creator/{ident}:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
      - name: ident
        in: path
        type: string
        required: true
    put:
      operationId: "update_creator"
      tags: # TAGLINE
        - creators # TAGLINE
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/creator_entity"
      security:
        - Bearer: []
      responses:
        200:
          description: Updated Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
    delete:
      operationId: "delete_creator"
      tags: # TAGLINE
        - creators # TAGLINE
      security:
        - Bearer: []
      responses:
        200:
          description: Deleted Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /creator/rev/{rev_id}:
    parameters:
      - name: rev_id
        in: path
        required: true
        <<: *FATCATUUID
    get:
      operationId: "get_creator_revision"
      tags: # TAGLINE
        - creators # TAGLINE
      parameters:
        - name: expand
          in: query
          type: string
          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.
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. See `get_creator`."
      responses:
        200:
          description: Found Entity Revision
          schema:
            $ref: "#/definitions/creator_entity"
        <<: *ENTITYRESPONSES
  /creator/{ident}/history:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
      - name: limit
        in: query
        type: integer
        format: int64
        required: false
    get:
      operationId: "get_creator_history"
      tags: # TAGLINE
        - creators # TAGLINE
      responses:
        200:
          description: Found Entity History
          schema:
            type: array
            items:
              $ref: "#/definitions/entity_history_entry"
        <<: *ENTITYRESPONSES
  /creator/{ident}/releases:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
      - name: hide
        in: query
        type: string
        required: false
        description: "List of entity fields to elide in response. See `get_release`."
    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
          schema:
            type: array
            items:
              $ref: "#/definitions/release_entity"
        <<: *ENTITYRESPONSES
  /creator/{ident}/redirects:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    get:
      operationId: "get_creator_redirects"
      tags: # TAGLINE
        - creators # TAGLINE
      responses:
        200:
          description: Found Entity Redirects
          schema:
            type: array
            items:
              <<: *FATCATIDENT
        <<: *ENTITYRESPONSES
  /creator/lookup:
    get:
      operationId: "lookup_creator"
      tags: # TAGLINE
        - creators # TAGLINE
      parameters:
        - name: orcid
          in: query
          required: false
          <<: *FATCATORCID
        - name: wikidata_qid
          in: query
          type: string
          required: false
        - name: expand
          in: query
          type: string
          required: false
          description: "List of sub-entities to expand in response. See `get_creator`."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. See `get_creator`."
      responses:
        200:
          description: Found Entity
          schema:
            $ref: "#/definitions/creator_entity"
        <<: *ENTITYRESPONSES
  /creator/edit/{edit_id}:
    get:
      operationId: "get_creator_edit"
      tags: # TAGLINE
        - creators # TAGLINE
      parameters:
        - name: edit_id
          in: path
          required: true
          <<: *FATCATUUID
      responses:
        200:
          description: Found Edit
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/creator/edit/{edit_id}:
    parameters:
      - name: editgroup_id
        in: path
        required: true
        type: string
      - name: edit_id
        in: path
        required: true
        <<: *FATCATUUID
    delete:
      operationId: "delete_creator_edit"
      tags: # TAGLINE
        - creators # TAGLINE
      security:
        - Bearer: []
      responses:
        200:
          description: Deleted Edit
          schema:
            $ref: "#/definitions/success"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES

  /editgroup/{editgroup_id}/file:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
    post:
      operationId: "create_file"
      tags: # TAGLINE
        - files # TAGLINE
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/file_entity"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /editgroup/auto/file/batch:
    post:
      operationId: "create_file_auto_batch"
      tags: # TAGLINE
        - files # TAGLINE
      parameters:
        - name: auto_batch
          in: body
          required: true
          schema:
            $ref: "#/definitions/file_auto_batch"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Editgroup
          schema:
            $ref: "#/definitions/editgroup"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /file/{ident}:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    get:
      operationId: "get_file"
      tags: # TAGLINE
        - files # TAGLINE
      parameters:
        - name: expand
          in: query
          type: string
          required: false
          description: "List of sub-entities to expand in response. For files, `releases` is accepted."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. For files, none accepted (yet)."
      responses:
        200:
          description: Found Entity
          schema:
            $ref: "#/definitions/file_entity"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/file/{ident}:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
      - name: ident
        in: path
        type: string
        required: true
    put:
      operationId: "update_file"
      tags: # TAGLINE
        - files # TAGLINE
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/file_entity"
      security:
        - Bearer: []
      responses:
        200:
          description: Updated Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
    delete:
      operationId: "delete_file"
      tags: # TAGLINE
        - files # TAGLINE
      security:
        - Bearer: []
      responses:
        200:
          description: Deleted Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /file/rev/{rev_id}:
    parameters:
      - name: rev_id
        in: path
        required: true
        <<: *FATCATUUID
    get:
      operationId: "get_file_revision"
      tags: # TAGLINE
        - files # TAGLINE
      parameters:
        - name: expand
          in: query
          type: string
          required: false
          description: "List of sub-entities to expand in response. See `get_file`."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. See `get_file`."
      responses:
        200:
          description: Found Entity Revision
          schema:
            $ref: "#/definitions/file_entity"
        <<: *ENTITYRESPONSES
  /file/{ident}/history:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
      - name: limit
        in: query
        type: integer
        format: int64
        required: false
    get:
      operationId: "get_file_history"
      tags: # TAGLINE
        - files # TAGLINE
      responses:
        200:
          description: Found Entity History
          schema:
            type: array
            items:
              $ref: "#/definitions/entity_history_entry"
        <<: *ENTITYRESPONSES
  /file/{ident}/redirects:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    get:
      operationId: "get_file_redirects"
      tags: # TAGLINE
        - files # TAGLINE
      responses:
        200:
          description: Found Entity Redirects
          schema:
            type: array
            items:
              <<: *FATCATIDENT
        <<: *ENTITYRESPONSES
  /file/lookup:
    get:
      operationId: "lookup_file"
      tags: # TAGLINE
        - files # TAGLINE
      parameters:
        - name: md5
          in: query
          required: false
          <<: *FATCATMD5
        - name: sha1
          in: query
          required: false
          <<: *FATCATSHA1
        - name: sha256
          in: query
          required: false
          <<: *FATCATSHA256
        - name: expand
          in: query
          type: string
          required: false
          description: "List of sub-entities to expand in response. See `get_file`."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. See `get_file`."
      responses:
        200:
          description: Found Entity
          schema:
            $ref: "#/definitions/file_entity"
        <<: *ENTITYRESPONSES
  /file/edit/{edit_id}:
    get:
      operationId: "get_file_edit"
      tags: # TAGLINE
        - files # TAGLINE
      parameters:
        - name: edit_id
          in: path
          required: true
          <<: *FATCATUUID
      responses:
        200:
          description: Found Edit
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/file/edit/{edit_id}:
    parameters:
      - name: editgroup_id
        in: path
        required: true
        type: string
      - name: edit_id
        in: path
        required: true
        <<: *FATCATUUID
    delete:
      operationId: "delete_file_edit"
      tags: # TAGLINE
        - files # TAGLINE
      security:
        - Bearer: []
      responses:
        200:
          description: Deleted Edit
          schema:
            $ref: "#/definitions/success"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES

  /editgroup/{editgroup_id}/fileset:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
    post:
      operationId: "create_fileset"
      tags: # TAGLINE
        - filesets # TAGLINE
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/fileset_entity"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /editgroup/auto/fileset/batch:
    post:
      operationId: "create_fileset_auto_batch"
      tags: # TAGLINE
        - filesets # TAGLINE
      parameters:
        - name: auto_batch
          in: body
          required: true
          schema:
            $ref: "#/definitions/fileset_auto_batch"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Editgroup
          schema:
            $ref: "#/definitions/editgroup"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /fileset/{ident}:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    get:
      operationId: "get_fileset"
      tags: # TAGLINE
        - filesets # TAGLINE
      parameters:
        - name: expand
          in: query
          type: string
          required: false
          description: "List of sub-entities to expand in response. For filesets, `releases` is accepted."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. For filesets, 'manifest' is accepted."
      responses:
        200:
          description: Found Entity
          schema:
            $ref: "#/definitions/fileset_entity"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/fileset/{ident}:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
      - name: ident
        in: path
        type: string
        required: true
    put:
      operationId: "update_fileset"
      tags: # TAGLINE
        - filesets # TAGLINE
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/fileset_entity"
      security:
        - Bearer: []
      responses:
        200:
          description: Updated Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
    delete:
      operationId: "delete_fileset"
      tags: # TAGLINE
        - filesets # TAGLINE
      security:
        - Bearer: []
      responses:
        200:
          description: Deleted Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /fileset/rev/{rev_id}:
    parameters:
      - name: rev_id
        in: path
        required: true
        <<: *FATCATUUID
    get:
      operationId: "get_fileset_revision"
      tags: # TAGLINE
        - filesets # TAGLINE
      parameters:
        - name: expand
          in: query
          type: string
          required: false
          description: "List of sub-entities to expand in response. See `get_fileset`."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. See `get_fileset`."
      responses:
        200:
          description: Found Entity Revision
          schema:
            $ref: "#/definitions/fileset_entity"
        <<: *ENTITYRESPONSES
  /fileset/{ident}/history:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
      - name: limit
        in: query
        type: integer
        format: int64
        required: false
    get:
      operationId: "get_fileset_history"
      tags: # TAGLINE
        - filesets # TAGLINE
      responses:
        200:
          description: Found Entity History
          schema:
            type: array
            items:
              $ref: "#/definitions/entity_history_entry"
        <<: *ENTITYRESPONSES
  /fileset/{ident}/redirects:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    get:
      operationId: "get_fileset_redirects"
      tags: # TAGLINE
        - filesets # TAGLINE
      responses:
        200:
          description: Found Entity Redirects
          schema:
            type: array
            items:
              <<: *FATCATIDENT
        <<: *ENTITYRESPONSES
  /fileset/edit/{edit_id}:
    get:
      operationId: "get_fileset_edit"
      tags: # TAGLINE
        - filesets # TAGLINE
      parameters:
        - name: edit_id
          in: path
          required: true
          <<: *FATCATUUID
      responses:
        200:
          description: Found Edit
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/fileset/edit/{edit_id}:
    parameters:
      - name: editgroup_id
        in: path
        required: true
        type: string
      - name: edit_id
        in: path
        required: true
        <<: *FATCATUUID
    delete:
      operationId: "delete_fileset_edit"
      tags: # TAGLINE
        - filesets # TAGLINE
      security:
        - Bearer: []
      responses:
        200:
          description: Deleted Edit
          schema:
            $ref: "#/definitions/success"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES

  /editgroup/{editgroup_id}/webcapture:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
    post:
      operationId: "create_webcapture"
      tags: # TAGLINE
        - webcaptures # TAGLINE
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/webcapture_entity"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /editgroup/auto/webcapture/batch:
    post:
      operationId: "create_webcapture_auto_batch"
      tags: # TAGLINE
        - webcaptures # TAGLINE
      parameters:
        - name: auto_batch
          in: body
          required: true
          schema:
            $ref: "#/definitions/webcapture_auto_batch"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Editgroup
          schema:
            $ref: "#/definitions/editgroup"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /webcapture/{ident}:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    get:
      operationId: "get_webcapture"
      tags: # TAGLINE
        - webcaptures # TAGLINE
      parameters:
        - name: expand
          in: query
          type: string
          required: false
          description: "List of sub-entities to expand in response. For webcaptures, `releases` is accepted."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. For webcaptures, 'cdx' is accepted."
      responses:
        200:
          description: Found Entity
          schema:
            $ref: "#/definitions/webcapture_entity"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/webcapture/{ident}:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
      - name: ident
        in: path
        type: string
        required: true
    put:
      operationId: "update_webcapture"
      tags: # TAGLINE
        - webcaptures # TAGLINE
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/webcapture_entity"
      security:
        - Bearer: []
      responses:
        200:
          description: Updated Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
    delete:
      operationId: "delete_webcapture"
      tags: # TAGLINE
        - webcaptures # TAGLINE
      security:
        - Bearer: []
      responses:
        200:
          description: Deleted Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /webcapture/rev/{rev_id}:
    parameters:
      - name: rev_id
        in: path
        required: true
        <<: *FATCATUUID
    get:
      operationId: "get_webcapture_revision"
      tags: # TAGLINE
        - webcaptures # TAGLINE
      parameters:
        - name: expand
          in: query
          type: string
          required: false
          description: "List of sub-entities to expand in response. See `get_webcapture`."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. See `get_webcapture`."
      responses:
        200:
          description: Found Entity Revision
          schema:
            $ref: "#/definitions/webcapture_entity"
        <<: *ENTITYRESPONSES
  /webcapture/{ident}/history:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
      - name: limit
        in: query
        type: integer
        format: int64
        required: false
    get:
      operationId: "get_webcapture_history"
      tags: # TAGLINE
        - webcaptures # TAGLINE
      responses:
        200:
          description: Found Entity History
          schema:
            type: array
            items:
              $ref: "#/definitions/entity_history_entry"
        <<: *ENTITYRESPONSES
  /webcapture/{ident}/redirects:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    get:
      operationId: "get_webcapture_redirects"
      tags: # TAGLINE
        - webcaptures # TAGLINE
      responses:
        200:
          description: Found Entity Redirects
          schema:
            type: array
            items:
              <<: *FATCATIDENT
        <<: *ENTITYRESPONSES
  /webcapture/edit/{edit_id}:
    get:
      operationId: "get_webcapture_edit"
      tags: # TAGLINE
        - webcaptures # TAGLINE
      parameters:
        - name: edit_id
          in: path
          required: true
          <<: *FATCATUUID
      responses:
        200:
          description: Found Edit
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/webcapture/edit/{edit_id}:
    parameters:
      - name: editgroup_id
        in: path
        required: true
        type: string
      - name: edit_id
        in: path
        required: true
        <<: *FATCATUUID
    delete:
      operationId: "delete_webcapture_edit"
      tags: # TAGLINE
        - webcaptures # TAGLINE
      security:
        - Bearer: []
      responses:
        200:
          description: Deleted Edit
          schema:
            $ref: "#/definitions/success"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES

  /editgroup/{editgroup_id}/release:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
    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).
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/release_entity"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /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.
      parameters:
        - name: auto_batch
          in: body
          required: true
          schema:
            $ref: "#/definitions/release_auto_batch"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Editgroup
          schema:
            $ref: "#/definitions/editgroup"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /release/{ident}:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    get:
      operationId: "get_release"
      tags: # TAGLINE
        - releases # TAGLINE
      description: |
        Fetches a single Release entity from the catalog.
      parameters:
        - name: expand
          in: query
          type: string
          required: false
          description: |
            List of sub-entities to expand in response. For releases, 'files',
            'filesets, 'webcaptures', 'container', and 'creators' are valid.
        - name: hide
          in: query
          type: string
          required: false
          description: |
            List of entity fields to elide in response (for efficiency). For
            releases, 'abstracts', 'refs', and 'contribs' are valid.
      responses:
        200:
          description: Found Entity
          schema:
            $ref: "#/definitions/release_entity"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/release/{ident}:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
      - name: ident
        in: path
        type: string
        required: true
    put:
      operationId: "update_release"
      tags: # 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.
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/release_entity"
      security:
        - Bearer: []
      responses:
        200:
          description: Updated Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
    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
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /release/rev/{rev_id}:
    parameters:
      - name: rev_id
        in: path
        required: true
        <<: *FATCATUUID
    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
          type: string
          required: false
          description:
            List of sub-entities to expand in response. See `get_release`,
            though note that identifier-based exapansions like `file` will
            always be empty for revisions.
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. See `get_release`."
      responses:
        200:
          description: Found Entity Revision
          schema:
            $ref: "#/definitions/release_entity"
        <<: *ENTITYRESPONSES
  /release/{ident}/history:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
      - name: limit
        in: query
        type: integer
        format: int64
        required: false
    get:
      operationId: "get_release_history"
      tags: # TAGLINE
        - releases # TAGLINE
      description: |
        Fetches the history of accepted edits (changelog entries) for a
        specific entity fatcat identifier.
      responses:
        200:
          description: Found Entity History
          schema:
            type: array
            items:
              $ref: "#/definitions/entity_history_entry"
        <<: *ENTITYRESPONSES
  /release/{ident}/files:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
      - name: hide
        in: query
        type: string
        required: false
        description: "List of entity fields to elide in response. See `get_file`."
    get:
      operationId: "get_release_files"
      tags: # TAGLINE
        - releases # TAGLINE
      description: |
        Returns the set of File entities that have a `release_id` pointing to
        this release entity.
      responses:
        200:
          description: Found
          schema:
            type: array
            items:
              $ref: "#/definitions/file_entity"
        <<: *ENTITYRESPONSES
  /release/{ident}/filesets:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
      - name: hide
        in: query
        type: string
        required: false
        description: "List of entity fields to elide in response. See `get_fileset`."
    get:
      operationId: "get_release_filesets"
      tags: # TAGLINE
        - releases # TAGLINE
      description: |
        Returns the set of Fileset entities that have a `release_id` pointing to
        this release entity.
      responses:
        200:
          description: Found
          schema:
            type: array
            items:
              $ref: "#/definitions/fileset_entity"
        <<: *ENTITYRESPONSES
  /release/{ident}/webcaptures:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
      - name: hide
        in: query
        type: string
        required: false
        description: "List of entity fields to elide in response. See `get_webcapture`."
    get:
      operationId: "get_release_webcaptures"
      tags: # 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
          schema:
            type: array
            items:
              $ref: "#/definitions/webcapture_entity"
        <<: *ENTITYRESPONSES
  /release/{ident}/redirects:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    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
          schema:
            type: array
            items:
              <<: *FATCATIDENT
        <<: *ENTITYRESPONSES
  /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:
        # TODO: use identifier types here
        - name: doi
          in: query
          type: string
          required: false
        - name: wikidata_qid
          in: query
          type: string
          required: false
        - name: isbn13
          in: query
          type: string
          required: false
        - name: pmid
          in: query
          type: string
          required: false
        - name: pmcid
          in: query
          type: string
          required: false
        - name: core
          in: query
          type: string
          required: false
        - name: arxiv
          in: query
          type: string
          required: false
        - name: jstor
          in: query
          type: string
          required: false
        - name: ark
          in: query
          type: string
          required: false
        - name: mag
          in: query
          type: string
          required: false
        - name: expand
          in: query
          type: string
          required: false
          description: "List of sub-entities to expand in response. See `get_release`."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of sub-entities to elide in response. See `get_release`."
      responses:
        200:
          description: Found Entity
          schema:
            $ref: "#/definitions/release_entity"
        <<: *ENTITYRESPONSES
  /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
          <<: *FATCATUUID
      responses:
        200:
          description: Found Edit
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/release/edit/{edit_id}:
    parameters:
      - name: editgroup_id
        in: path
        required: true
        type: string
      - name: edit_id
        in: path
        required: true
        <<: *FATCATUUID
    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
          schema:
            $ref: "#/definitions/success"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES

  /editgroup/{editgroup_id}/work:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
    post:
      operationId: "create_work"
      tags: # TAGLINE
        - works # TAGLINE
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/work_entity"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /editgroup/auto/work/batch:
    post:
      operationId: "create_work_auto_batch"
      tags: # TAGLINE
        - works # TAGLINE
      parameters:
        - name: auto_batch
          in: body
          required: true
          schema:
            $ref: "#/definitions/work_auto_batch"
      security:
        - Bearer: []
      responses:
        201:
          description: Created Editgroup
          schema:
            $ref: "#/definitions/editgroup"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /work/{ident}:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    get:
      operationId: "get_work"
      tags: # TAGLINE
        - works # TAGLINE
      parameters:
        - name: expand
          in: query
          type: string
          required: false
          description: "List of sub-entities to expand in response. For works, none accepted (yet)."
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. For works, none accepted (yet)."
      responses:
        200:
          description: Found Entity
          schema:
            $ref: "#/definitions/work_entity"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/work/{ident}:
    parameters:
      - name: editgroup_id
        in: path
        type: string
        required: true
      - name: ident
        in: path
        type: string
        required: true
    put:
      operationId: "update_work"
      tags: # TAGLINE
        - works # TAGLINE
      parameters:
        - name: entity
          in: body
          required: true
          schema:
            $ref: "#/definitions/work_entity"
      security:
        - Bearer: []
      responses:
        200:
          description: Updated Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
    delete:
      operationId: "delete_work"
      tags: # TAGLINE
        - works # TAGLINE
      security:
        - Bearer: []
      responses:
        200:
          description: Deleted Entity
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES
  /work/rev/{rev_id}:
    parameters:
      - name: rev_id
        in: path
        required: true
        <<: *FATCATUUID
    get:
      operationId: "get_work_revision"
      tags: # TAGLINE
        - works # TAGLINE
      parameters:
        - name: expand
          in: query
          type: string
          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.
        - name: hide
          in: query
          type: string
          required: false
          description: "List of entity fields to elide in response. See `get_work`."
      responses:
        200:
          description: Found Entity Revision
          schema:
            $ref: "#/definitions/work_entity"
        <<: *ENTITYRESPONSES
  /work/{ident}/history:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
      - name: limit
        in: query
        type: integer
        format: int64
        required: false
    get:
      operationId: "get_work_history"
      tags: # TAGLINE
        - works # TAGLINE
      responses:
        200:
          description: Found Entity History
          schema:
            type: array
            items:
              $ref: "#/definitions/entity_history_entry"
        <<: *ENTITYRESPONSES
  /work/{ident}/redirects:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
    get:
      operationId: "get_work_redirects"
      tags: # TAGLINE
        - works # TAGLINE
      responses:
        200:
          description: Found Entity Redirects
          schema:
            type: array
            items:
              <<: *FATCATIDENT
        <<: *ENTITYRESPONSES
  /work/{ident}/releases:
    parameters:
      - name: ident
        in: path
        type: string
        required: true
      - name: hide
        in: query
        type: string
        required: false
        description: "List of entity fields to elide in response. See `get_release`."
    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
          schema:
            type: array
            items:
              $ref: "#/definitions/release_entity"
        <<: *ENTITYRESPONSES
  /work/edit/{edit_id}:
    get:
      operationId: "get_work_edit"
      tags: # TAGLINE
        - works # TAGLINE
      parameters:
        - name: edit_id
          in: path
          required: true
          <<: *FATCATUUID
      responses:
        200:
          description: Found Edit
          schema:
            $ref: "#/definitions/entity_edit"
        <<: *ENTITYRESPONSES
  /editgroup/{editgroup_id}/work/edit/{edit_id}:
    parameters:
      - name: editgroup_id
        in: path
        required: true
        type: string
      - name: edit_id
        in: path
        required: true
        <<: *FATCATUUID
    delete:
      operationId: "delete_work_edit"
      tags: # TAGLINE
        - works # TAGLINE
      security:
        - Bearer: []
      responses:
        200:
          description: Deleted Edit
          schema:
            $ref: "#/definitions/success"
        <<: *ENTITYRESPONSES
        <<: *AUTHRESPONSES

  /editor/{editor_id}:
    parameters:
      - name: editor_id
        in: path
        type: string
        required: true
    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
          schema:
            $ref: "#/definitions/editor"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
    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.
      parameters:
       - name: editor
         in: body
         required: true
         schema:
           $ref: "#/definitions/editor"
      security:
       - Bearer: []
      responses:
        200:
          description: Updated Editor
          schema:
            $ref: "#/definitions/editor"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
        <<: *AUTHRESPONSES
  /editor/{editor_id}/editgroups:
    parameters:
      - name: editor_id
        in: path
        type: string
        required: true
    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
          type: integer
          format: int64
          required: false
        - name: before
          in: query
          type: string
          format: date-time
          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.
        - name: since
          in: query
          type: string
          format: date-time
          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.
      responses:
        200:
          description: Found
          schema:
            type: array
            items:
              $ref: "#/definitions/editgroup"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
  /editor/{editor_id}/annotations:
    parameters:
      - name: editor_id
        in: path
        required: true
        <<: *FATCATIDENT
    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
          type: integer
          format: int64
          required: false
          description: "Maximum number (count) of annotations to return in response"
        - name: before
          in: query
          type: string
          format: date-time
          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.
        - name: since
          in: query
          type: string
          format: date-time
          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.
      responses:
        200:
          description: Success
          schema:
            type: array
            items:
              $ref: "#/definitions/editgroup_annotation"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
        <<: *AUTHRESPONSES

  /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.
      parameters:
        - name: editgroup
          in: body
          required: true
          schema:
            $ref: "#/definitions/editgroup"
      security:
        - Bearer: []
      responses:
        201:
          description: Successfully Created
          schema:
            $ref: "#/definitions/editgroup"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        404: # added only for response type consistency
          description: Not Found
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
        <<: *AUTHRESPONSES
  /editgroup/{editgroup_id}:
    parameters:
      - name: editgroup_id
        in: path
        required: true
        <<: *FATCATIDENT
    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
          schema:
            $ref: "#/definitions/editgroup"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
    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: editgroup
          in: body
          required: true
          schema:
            $ref: "#/definitions/editgroup"
        - name: submit
          in: query
          type: boolean
          required: false
      responses:
        200:
          description: Updated Editgroup
          schema:
            $ref: "#/definitions/editgroup"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
        <<: *AUTHRESPONSES
  /editgroup/{editgroup_id}/accept:
    parameters:
      - name: editgroup_id
        in: path
        required: true
        <<: *FATCATIDENT
    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
          schema:
            $ref: "#/definitions/success"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/error_response"
        409:
          description: Edit Conflict
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
        <<: *AUTHRESPONSES
  /editgroup/{editgroup_id}/annotations:
    parameters:
      - name: editgroup_id
        in: path
        required: true
        <<: *FATCATIDENT
    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
          type: string
          required: false
          description: "List of sub-entities to expand in response. For editgroup annotations: 'editors'"
      responses:
        200:
          description: Success
          schema:
            type: array
            items:
              $ref: "#/definitions/editgroup_annotation"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
        <<: *AUTHRESPONSES
  /editgroup/{editgroup_id}/annotation:
    parameters:
      - name: editgroup_id
        in: path
        required: true
        <<: *FATCATIDENT
    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: []
      parameters:
        - name: annotation
          in: body
          required: true
          schema:
            $ref: "#/definitions/editgroup_annotation"
      responses:
        201:
          description: Created
          schema:
            $ref: "#/definitions/editgroup_annotation"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
        <<: *AUTHRESPONSES
  /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
          type: string
          required: false
          description: "List of sub-entities to expand in response. For editgroups: 'editors'"
        - name: limit
          in: query
          type: integer
          format: int64
          required: false
          description: "Maximum number of reviewable editgroups to return in response"
        - name: before
          in: query
          type: string
          format: date-time
          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.
        - name: since
          in: query
          type: string
          format: date-time
          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.
      responses:
        200:
          description: Found
          schema:
            type: array
            items:
              $ref: "#/definitions/editgroup"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
  /changelog:
    parameters:
      - name: limit
        in: query
        type: integer
        format: int64
        required: false
        description: "Maximum count of changelog entries to return in response"
    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
          schema:
            type: array
            items:
              $ref: "#/definitions/changelog_entry"
        400: # added only for response type consistency
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
  /changelog/{index}:
    parameters:
      - name: index
        in: path
        type: integer
        format: int64
        required: true
        description: "Changelog index of entry to return"
    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
          schema:
            $ref: "#/definitions/changelog_entry"
        400: # added only for response type consistency
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
  /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:
        # required admin privs
        - Bearer: []
      parameters:
        - name: oidc_params
          in: body
          required: true
          schema:
            $ref: "#/definitions/auth_oidc"
      responses:
        200:
          description: Found
          schema:
            $ref: "#/definitions/auth_oidc_result"
        201:
          description: Created
          schema:
            $ref: "#/definitions/auth_oidc_result"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        409:
          description: Conflict
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
        <<: *AUTHRESPONSES
  /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:
        # required admin privs
        - Bearer: []
      parameters:
        - name: role
          in: query
          required: false
          type: string
      responses:
        200:
          description: Success
          schema:
            $ref: "#/definitions/success"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
        <<: *AUTHRESPONSES
  /auth/token/{editor_id}:
    parameters:
      - name: editor_id
        in: path
        type: string
        required: true
    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
          type: integer
          example: 86400
          required: false
          description: "How long API token should be valid for (in seconds)"
      responses:
        200:
          description: Success
          schema:
            $ref: "#/definitions/auth_token_result"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/error_response"
        500:
          description: Generic Error
          schema:
            $ref: "#/definitions/error_response"
        <<: *AUTHRESPONSES