Fatcat Editors API

openapi: 3.2.0
info:
  title: fatcat Editors API
  version: 0.5.0
  description: 'Fatcat is a scalable, versioned, API-oriented catalog of bibliographic

    entities and file metadata.'
  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: Editors
  x-displayName: Editors
  description: '**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'
paths:
  /editor/{editor_id}:
    parameters:
    - name: editor_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: get_editor
      tags:
      - Editors
      description: 'Returns an editor object, including metadata such as the username,

        type, and role of editor.'
      responses:
        200:
          description: Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/editor'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      summary: Get editor
      x-summary-source: derived
    put:
      operationId: update_editor
      tags:
      - Editors
      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.'
      security:
      - Bearer: []
      responses:
        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 Editor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/editor'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/editor'
        required: true
      summary: Update editor
      x-summary-source: derived
  /editor/{editor_id}/editgroups:
    parameters:
    - name: editor_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: get_editor_editgroups
      tags:
      - Editors
      description: 'Returns a set of editgroups created by the given editor, regardless of

        the status (accepted/submitted) of the editgroups.'
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: before
        in: query
        required: false
        description: 'Return only editgroups created *before* the given timestamp (not

          inclusive). Editgroups will be sorted by creation time in

          descending order (most recent first). For use in pagination.

          '
        schema:
          type: string
          format: date-time
      - name: since
        in: query
        required: false
        description: 'Return only editgroups created *after* the given timestamp (not

          inclusive). Editgroups will be sorted by creation time in ascending

          order (most recent last). For use in pagination.

          '
        schema:
          type: string
          format: date-time
      responses:
        200:
          description: Found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/editgroup'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      summary: Get editor editgroups
      x-summary-source: derived
  /editor/{editor_id}/annotations:
    parameters:
    - description: base32-encoded unique identifier
      name: editor_id
      in: path
      required: true
      schema:
        type: string
        maxLength: 26
        minLength: 26
        pattern: '[a-zA-Z2-7]{26}'
    get:
      operationId: get_editor_annotations
      tags:
      - Editors
      description: Fetches a list of annotations made by a particular editor.
      parameters:
      - name: limit
        in: query
        required: false
        description: Maximum number (count) of annotations to return in response
        schema:
          type: integer
          format: int64
      - name: before
        in: query
        required: false
        description: 'Return only annotations made *before* the given timestamp (not

          inclusive). Annotations will be sorted by creation time in

          descending order (most recent first). For use in pagination.

          '
        schema:
          type: string
          format: date-time
      - name: since
        in: query
        required: false
        description: 'Return only annotations made *after* the given timestamp (not

          inclusive). Annotations will be sorted by creation time in

          ascending order (most recent last). For use in pagination.

          '
        schema:
          type: string
          format: date-time
      responses:
        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: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/editgroup_annotation'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      summary: Get editor annotations
      x-summary-source: derived
  /editor/lookup:
    get:
      operationId: lookup_editor
      tags:
      - Editors
      description: 'Fetches editor by, eg, username.


        One (and only one) lookup identifier should be specified per request.'
      parameters:
      - name: username
        in: query
        required: false
        schema:
          type: string
      responses:
        200:
          description: Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/editor'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        500:
          description: Generic Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      summary: Lookup editor
      x-summary-source: derived
components:
  schemas:
    editor:
      type: object
      required:
      - username
      properties:
        editor_id:
          type: string
          pattern: '[a-zA-Z2-7]{26}'
          minLength: 26
          maxLength: 26
          description: 'Fatcat identifier for the editor. Can not be changed.

            '
          example: q3nouwy3nnbsvo3h5klxsx4a7y
        username:
          type: string
          example: zerocool93
          description: 'Username/handle (short slug-like string) to identify this editor. May

            be changed at any time by the editor; use the `editor_id` as a

            persistend identifier.

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

            '
    entity_edit:
      type: object
      required:
      - edit_id
      - ident
      - editgroup_id
      properties:
        edit_id:
          type: string
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
          minLength: 36
          maxLength: 36
          description: 'Unique UUID for this specific edit object.

            '
          example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
        ident:
          type: string
          pattern: '[a-zA-Z2-7]{26}'
          minLength: 26
          maxLength: 26
          description: 'Fatcat identifier of the entity this edit is mutating.

            '
          example: q3nouwy3nnbsvo3h5klxsx4a7y
        revision:
          type: string
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
          minLength: 36
          maxLength: 36
          description: 'Entity revision that this edit will set the entity to. May be

            `null` in the case of deletions.

            '
          example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
        prev_revision:
          type: string
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
          minLength: 36
          maxLength: 36
          description: 'Revision of entity just before this edit. May be used in the future

            to prevent edit race conditions.

            '
          example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
        redirect_ident:
          type: string
          pattern: '[a-zA-Z2-7]{26}'
          minLength: 26
          maxLength: 26
          description: 'When an edit is to merge entities (redirect one to another), this

            is the entity fatcat identifier for the target entity.

            '
          example: q3nouwy3nnbsvo3h5klxsx4a7y
        editgroup_id:
          type: string
          pattern: '[a-zA-Z2-7]{26}'
          minLength: 26
          maxLength: 26
          description: 'Editgroup identifier that this edit is part of.

            '
          example: q3nouwy3nnbsvo3h5klxsx4a7y
        extra:
          type: object
          additionalProperties: {}
    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
    editgroup:
      type: object
      properties:
        editgroup_id:
          type: string
          pattern: '[a-zA-Z2-7]{26}'
          minLength: 26
          maxLength: 26
          description: 'Fatcat identifier for this editgroup. Assigned on creation.

            '
          example: q3nouwy3nnbsvo3h5klxsx4a7y
        editor_id:
          type: string
          pattern: '[a-zA-Z2-7]{26}'
          minLength: 26
          maxLength: 26
          description: 'Fatcat identifier of editor that created this editgroup.

            '
          example: q3nouwy3nnbsvo3h5klxsx4a7y
        editor:
          $ref: '#/components/schemas/editor'
          description: 'Complete editor object identified by `container_id` field. Only

            included in GET responses.

            '
        changelog_index:
          type: integer
          example: 1048576
          format: int64
          description: 'For accepted/merged editgroups, the changelog index that the accept

            occurred at. WARNING: not populated in all contexts that an editgroup

            could be included in a response.

            '
        created:
          type: string
          format: date-time
          description: 'Timestamp when this editgroup was first created.

            '
        submitted:
          type: string
          format: date-time
          description: 'Timestamp when this editgroup was most recently submitted for review.

            If withdrawn, or never submitted, will be `null`.

            '
        description:
          type: string
          description: 'Comment describing the changes in this editgroup. Can be updated with

            PUT request.

            '
        extra:
          type: object
          additionalProperties: {}
          description: 'Free-form JSON metadata attached to this editgroup. Eg, metadata

            provenance, or script user-agent details. See guide for (unenforced)

            schema norms.

            '
        annotations:
          type: array
          items:
            $ref: '#/components/schemas/editgroup_annotation'
          description: 'Only included in GET responses, and not in all contexts. Do not

            include this field in PUT or POST requests.

            '
        edits:
          type: object
          description: 'Only included in GET responses, and not in all contexts. Do not

            include this field in PUT or POST requests.

            '
          properties:
            containers:
              type: array
              items:
                $ref: '#/components/schemas/entity_edit'
            creators:
              type: array
              items:
                $ref: '#/components/schemas/entity_edit'
            files:
              type: array
              items:
                $ref: '#/components/schemas/entity_edit'
            filesets:
              type: array
              items:
                $ref: '#/components/schemas/entity_edit'
            webcaptures:
              type: array
              items:
                $ref: '#/components/schemas/entity_edit'
            releases:
              type: array
              items:
                $ref: '#/components/schemas/entity_edit'
            works:
              type: array
              items:
                $ref: '#/components/schemas/entity_edit'
  securitySchemes:
    Bearer:
      type: apiKey
      name: Authorization
      in: header
      description: "The only current API authentication mechanism is HTTP bearer\nauthentication using the `Authorization` HTTP header. The header should\nbe formatted as the string \"Bearer\", then a space, then API token (in the\nusual base64 string encoding).\n\nAn example HTTP request would look on the wire like:\n\n    GET /v0/auth/check HTTP/1.1\n    Accept: */*\n    Accept-Encoding: gzip, deflate\n    Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\n    Connection: keep-alive\n    Host: api.qa.fatcat.wiki\n    User-Agent: HTTPie/0.9.8\n\nHeaders can be passed on the command line using `http` (HTTPie) like:\n\n    http get https://api.qa.fatcat.wiki/v0/auth/check Authorization:\"Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\"\n\nOr with `curl`:\n\n    curl -H \"Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\" https://qa.fatcat.wiki/v0/auth/check\n"
x-servers:
- url: https://api.fatcat.wiki/v0
  description: Production Server
- url: https://api.qa.fatcat.wiki/v0
  description: QA Server
x-tagGroups:
- name: Entities
  tags:
  - containers
  - creators
  - files
  - filesets
  - webcaptures
  - releases
  - works
- name: Editing
  tags:
  - editors
  - editgroups
  - changelog
- name: Other
  tags:
  - auth
x-fatcat-ident:
  type: string
  pattern: '[a-zA-Z2-7]{26}'
  minLength: 26
  maxLength: 26
  description: base32-encoded unique identifier
x-fatcat-ident-example:
  example: q3nouwy3nnbsvo3h5klxsx4a7y
x-fatcat-uuid:
  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:
  example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
x-issn:
  type: string
  pattern: \d{4}-\d{3}[0-9X]
  minLength: 9
  maxLength: 9
x-issn-example:
  example: 1234-5678
x-orcid:
  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:
  example: 0000-0002-1825-0097
x-md5:
  type: string
  pattern: '[a-f0-9]{32}'
  minLength: 32
  maxLength: 32
  description: MD5 hash of data, in hex encoding
x-md5-example:
  example: 1b39813549077b2347c0f370c3864b40
x-sha1:
  type: string
  pattern: '[a-f0-9]{40}'
  minLength: 40
  maxLength: 40
  description: SHA-1 hash of data, in hex encoding
x-sha1-example:
  example: e9dd75237c94b209dc3ccd52722de6931a310ba3
x-sha256:
  type: string
  pattern: '[a-f0-9]{64}'
  minLength: 64
  maxLength: 64
  description: SHA-256 hash of data, in hex encoding
x-sha256-example:
  example: cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452
x-entity-props:
  state:
    type: string
    enum:
    - wip
    - active
    - redirect
    - deleted
    example: active
  ident:
    type: string
    pattern: '[a-zA-Z2-7]{26}'
    minLength: 26
    maxLength: 26
    description: base32-encoded unique identifier
    example: q3nouwy3nnbsvo3h5klxsx4a7y
  revision:
    type: string
    pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
    minLength: 36
    maxLength: 36
    description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
    example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
  redirect:
    type: string
    pattern: '[a-zA-Z2-7]{26}'
    minLength: 26
    maxLength: 26
    description: base32-encoded unique identifier
    example: q3nouwy3nnbsvo3h5klxsx4a7y
  extra:
    type: object
    description: 'Free-form JSON metadata that will be stored with the other entity

      metadata. See guide for (unenforced) schema conventions.

      '
    additionalProperties: {}
  edit_extra:
    type: object
    description: 'Free-form JSON metadata that will be stored with specific entity edits

      (eg, creation/update/delete).

      '
    additionalProperties: {}
x-auth-responses:
  401:
    description: Not Authorized
    schema:
      $ref: '#/components/schemas/error_response'
    headers:
      WWW_Authenticate:
        type: string
  403:
    description: Forbidden
    schema:
      $ref: '#/components/schemas/error_response'
x-entity-responses:
  400:
    description: Bad Request
    schema:
      $ref: '#/components/schemas/error_response'
  404:
    description: Not Found
    schema:
      $ref: '#/components/schemas/error_response'
  500:
    description: Generic Error
    schema:
      $ref: '#/components/schemas/error_response'