Fatcat releases API

openapi: 3.2.0
info:
  title: fatcat auth Releases API
  version: 0.5.0
  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.


    NOTE: as of Spring 2021, the QA server is temporarily unavailable.


    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 unforeseen uses and contributions, but may need to impose

    restrictions (like rate-limits) to keep the service functional for other

    users, and in extreme cases reserve the option to block accounts and IP

    ranges if necessary to keep the service operational.


    The Internet Archive owns and operates it''s own server equipment and data

    centers, and operations are optimized for low-cost, not high-availability.

    Users and partners should expect some downtime on the fatcat API, on the

    order of hours a month.


    Periodic metadata exports are available for batch processing, and database

    snapshots can be used to create locally-hosted mirrors of the service for

    more intensive and reliable querying.


    ### Other Nitty Gritties


    Cross-origin requests are allowed for the API service, to enable third

    parties to build in-browser applications.


    A metadata search service is available at <https://search.fatcat.wiki>.

    The API is currently the raw elasticsearch API, with only GET (read)

    requests allowed. This public service is experimental and may be removed or

    limited in the future.


    ## Authentication


    The API allows basic read-only "GET" HTTP requests with no authentication.

    Proposing changes to the metadata, or other mutating requests ("PUT",

    "POST", "DELETE") all require authentication, and some operations require

    additional account permissions.


    End-user account creation and login happens through the web interface. From

    a logged-in editor profile page, you can generate a API token. Tokens are

    "macaroons", similar to JWT tokens, and are used for all API

    authentication. The web interface includes macaroons in browser cookies and

    passes them through to the API to authenticate editor actions.


    <!-- ReDoc-Inject: <security-definitions> -->

    <!-- ENDLONGDESCRIPTION -->

    '
  termsOfService: https://guide.fatcat.wiki/policies.html
  contact:
    name: Internet Archive Web Group
    email: webservices@archive.org
    url: https://fatcat.wiki
  x-logo:
    url: https://fatcat.wiki/static/paper_man_confused.gif
    altText: Confused Papers Man (Logo)
    backgroundColor: '#FFFFFF'
servers:
- url: https://api.fatcat.wiki/v0
tags:
- name: releases
  x-displayName: Releases
  description: '**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

    '
paths:
  /editgroup/{editgroup_id}/release:
    parameters:
    - name: editgroup_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: create_release
      tags:
      - releases
      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).

        '
      security:
      - Bearer: []
      responses:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        401:
          description: Not Authorized
          headers:
            WWW_Authenticate:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        201:
          description: Created Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entity_edit'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/release_entity'
        required: true
  /editgroup/auto/release/batch:
    post:
      operationId: create_release_auto_batch
      tags:
      - releases
      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.

        '
      security:
      - Bearer: []
      responses:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        401:
          description: Not Authorized
          headers:
            WWW_Authenticate:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        201:
          description: Created Editgroup
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/editgroup'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/release_auto_batch'
        required: true
  /release/{ident}:
    parameters:
    - name: ident
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: get_release
      tags:
      - releases
      description: 'Fetches a single Release entity from the catalog.

        '
      parameters:
      - name: expand
        in: query
        required: false
        description: 'List of sub-entities to expand in response. For releases, ''files'',

          ''filesets, ''webcaptures'', ''container'', and ''creators'' are valid.

          '
        schema:
          type: string
      - name: hide
        in: query
        required: false
        description: 'List of entity fields to elide in response (for efficiency). For

          releases, ''abstracts'', ''refs'', and ''contribs'' are valid.

          '
        schema:
          type: string
      responses:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Found Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/release_entity'
  /editgroup/{editgroup_id}/release/{ident}:
    parameters:
    - name: editgroup_id
      in: path
      required: true
      schema:
        type: string
    - name: ident
      in: path
      required: true
      schema:
        type: string
    put:
      operationId: update_release
      tags:
      - releases
      description: 'Updates an existing entity as part of a specific (existing) editgroup.

        The editgroup must be open for updates (aka, not accepted/merged), and

        the editor making the request must have permissions (aka, must have

        created the editgroup or have `admin` role).


        This method can also be used to update an existing entity edit as part

        of an editgroup. For example, if an entity was created in this

        editgroup, an editor could make changes to the new entity''s metadata

        before merging.

        '
      security:
      - Bearer: []
      responses:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        401:
          description: Not Authorized
          headers:
            WWW_Authenticate:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Updated Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entity_edit'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/release_entity'
        required: true
    delete:
      operationId: delete_release
      tags:
      - releases
      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:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        401:
          description: Not Authorized
          headers:
            WWW_Authenticate:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Deleted Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entity_edit'
  /release/rev/{rev_id}:
    parameters:
    - description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
      name: rev_id
      in: path
      required: true
      schema:
        type: string
        maxLength: 36
        minLength: 36
        pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
    get:
      operationId: get_release_revision
      tags:
      - releases
      description: 'Fetches a specific entity revision. Note that the returned revision

        will not be associated with any particular fatcat identifier (even if

        one or more identifiers do currently point to this revision). The

        revision may even be part of an un-merged editgroup.


        Revisions are immutable and can not be deleted or updated.

        '
      parameters:
      - name: expand
        in: query
        required: false
        description: List of sub-entities to expand in response. See `get_release`, though note that identifier-based exapansions like `file` will always be empty for revisions.
        schema:
          type: string
      - name: hide
        in: query
        required: false
        description: List of entity fields to elide in response. See `get_release`.
        schema:
          type: string
      responses:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Found Entity Revision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/release_entity'
  /release/{ident}/history:
    parameters:
    - name: ident
      in: path
      required: true
      schema:
        type: string
    - name: limit
      in: query
      required: false
      schema:
        type: integer
        format: int64
    get:
      operationId: get_release_history
      tags:
      - releases
      description: 'Fetches the history of accepted edits (changelog entries) for a

        specific entity fatcat identifier.

        '
      responses:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Found Entity History
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/entity_history_entry'
  /release/{ident}/files:
    parameters:
    - name: ident
      in: path
      required: true
      schema:
        type: string
    - name: hide
      in: query
      required: false
      description: List of entity fields to elide in response. See `get_file`.
      schema:
        type: string
    get:
      operationId: get_release_files
      tags:
      - releases
      description: 'Returns the set of File entities that have a `release_id` pointing to

        this release entity.

        '
      responses:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/file_entity'
  /release/{ident}/filesets:
    parameters:
    - name: ident
      in: path
      required: true
      schema:
        type: string
    - name: hide
      in: query
      required: false
      description: List of entity fields to elide in response. See `get_fileset`.
      schema:
        type: string
    get:
      operationId: get_release_filesets
      tags:
      - releases
      description: 'Returns the set of Fileset entities that have a `release_id` pointing to

        this release entity.

        '
      responses:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/fileset_entity'
  /release/{ident}/webcaptures:
    parameters:
    - name: ident
      in: path
      required: true
      schema:
        type: string
    - name: hide
      in: query
      required: false
      description: List of entity fields to elide in response. See `get_webcapture`.
      schema:
        type: string
    get:
      operationId: get_release_webcaptures
      tags:
      - releases
      description: 'Returns the set of Web Capture entities that have a `release_id`

        pointing to this release entity.

        '
      responses:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/webcapture_entity'
  /release/{ident}/redirects:
    parameters:
    - name: ident
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: get_release_redirects
      tags:
      - releases
      description: 'Returns the set of entity identifiers which currently redirect to this

        identifier.

        '
      responses:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Found Entity Redirects
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  pattern: '[a-zA-Z2-7]{26}'
                  minLength: 26
                  maxLength: 26
                  description: base32-encoded unique identifier
  /release/lookup:
    get:
      operationId: lookup_release
      tags:
      - releases
      description: 'Looks for an active entity with the given external identifier. If any

        such entity is found, returns a single complete entity. If multiple

        entities have the same external identifier, this is considered a soft

        catalog error, and the behavior of which entity is returned is

        undefined.


        One (and only one) external identifier should be specified per request.

        '
      parameters:
      - name: doi
        in: query
        required: false
        schema:
          type: string
      - name: wikidata_qid
        in: query
        required: false
        schema:
          type: string
      - name: isbn13
        in: query
        required: false
        schema:
          type: string
      - name: pmid
        in: query
        required: false
        schema:
          type: string
      - name: pmcid
        in: query
        required: false
        schema:
          type: string
      - name: core
        in: query
        required: false
        schema:
          type: string
      - name: arxiv
        in: query
        required: false
        schema:
          type: string
      - name: jstor
        in: query
        required: false
        schema:
          type: string
      - name: ark
        in: query
        required: false
        schema:
          type: string
      - name: mag
        in: query
        required: false
        schema:
          type: string
      - name: doaj
        in: query
        required: false
        schema:
          type: string
      - name: dblp
        in: query
        required: false
        schema:
          type: string
      - name: oai
        in: query
        required: false
        schema:
          type: string
      - name: hdl
        in: query
        required: false
        schema:
          type: string
      - name: expand
        in: query
        required: false
        description: List of sub-entities to expand in response. See `get_release`.
        schema:
          type: string
      - name: hide
        in: query
        required: false
        description: List of sub-entities to elide in response. See `get_release`.
        schema:
          type: string
      responses:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Found Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/release_entity'
  /release/edit/{edit_id}:
    get:
      operationId: get_release_edit
      tags:
      - releases
      description: 'Returns the entity edit object with the given identifier. This method

        is expected to be used rarely.

        '
      parameters:
      - description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
        name: edit_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 36
          minLength: 36
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
      responses:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Found Edit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entity_edit'
  /editgroup/{editgroup_id}/release/edit/{edit_id}:
    parameters:
    - name: editgroup_id
      in: path
      required: true
      schema:
        type: string
    - description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
      name: edit_id
      in: path
      required: true
      schema:
        type: string
        maxLength: 36
        minLength: 36
        pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
    delete:
      operationId: delete_release_edit
      tags:
      - releases
      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:
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        401:
          description: Not Authorized
          headers:
            WWW_Authenticate:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        200:
          description: Deleted Edit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
components:
  schemas:
    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.

            '
    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.

            '
    editgroup_annotation:
      type: object
      properties:
        annotation_id:
          type: string
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
          minLength: 36
          maxLength: 36
          description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
          example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
        editgroup_id:
          type: string
          pattern: '[a-zA-Z2-7]{26}'
          minLength: 26
          maxLength: 26
          description: 'Editgroup that this annotation applies to. Set automatically in

            creations based on URL parameter.

            '
          example: q3nouwy3nnbsvo3h5klxsx4a7y
        editor_id:
          type: string
          pattern: '[a-zA-Z2-7]{26}'
          minLength: 26
          maxLength: 26
          description: 'Defaults to editor created the annotation via POST request.

            '
          example: q3nouwy3nnbsvo3h5klxsx4a7y
        editor:
          $ref: '#/components/schemas/editor'
          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.

            '
    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
    fileset_entity:
      type: object
      properties:
        state:
          type: string
          enum:
          - wip
          - active
          - redirect
          - deleted
          example: active
        ident:
          type: string
          pattern: '[a-zA-Z2-7]{26}'
          minLength: 26
          maxLength: 26
          description: base32-encoded unique identifier
          example: q3nouwy3nnbsvo3h5klxsx4a7y
        revision:
         

# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fatcat/refs/heads/main/openapi/fatcat-releases-api-openapi.yml