openapi: 3.0.0
info:
  title: NextGen Catalog Accounts Online Availability API
  version: 0.2.0
  description: "\nThis is the NextGen Catalog API application made with Express and documented with Swagger.\n\nThis API requires the use of an API key in order to access. Once you have obtained an API key, you can pass the API key into a REST API call in the x-api-key header of the request. For example, the request might look like\n\n    curl --location --request GET 'https://catalog.archives.gov/api/v2/records/search?q=constitution'\n    --header 'Content-Type: application/json'\n    --header 'x-api-key: API_KEY'\n\nwhere API_KEY is the key string of your API key.\n\nFor write operations, in addition to the API key, a user ID in the format of a Universally Unique Identifier (UUID) is required in the body of the request. For example, a request to POST a tag might look like:\n\n    curl --location --request POST 'https://catalog.archives.gov/api/v2/tags'\n    --header 'Content-Type: application/json'\n    --data-raw '{\n    \"tag\": \"example tag\",\n    \"targetNaId\": 1667751,\n    \"userId\": \"USER_UUID\"\n    }'\nwhere USER_UUID is the UUID of the user.\n\nPlease contact O&M at Catalog_API@nara.gov for an API Key."
servers:
- url: https://catalog.archives.gov/api/v2/
tags:
- name: Online Availability
  description: Information about record online availability
paths:
  /online-availability:
    get:
      summary: Get all online availability information.
      tags:
      - Online Availability
      parameters:
      - $ref: '#/components/parameters/paramAvailability'
      - $ref: '#/components/parameters/paramAvailabilityStatus'
      - $ref: '#/components/parameters/paramNaId'
      - $ref: '#/components/parameters/paramLimit'
      - $ref: '#/components/parameters/paramPage'
      responses:
        '200':
          description: A body of response data containing full record objects if any were found.
        '400':
          description: Bad Request. Invalid search terms, revise terms.
        '422':
          description: Unprocessable Entity. Query must be a non-empty string.
  /online-availability/naId/{naId}:
    get:
      summary: Get all online availability information for a record with the given naId.
      tags:
      - Online Availability
      parameters:
      - $ref: '#/components/parameters/paramPathNaId'
      responses:
        '200':
          description: A body of response data containing full record objects if any were found.
        '400':
          description: Bad Request. Invalid search terms, revise terms.
        '422':
          description: Unprocessable Entity. Query must be a non-empty string.
  /online-availability/update:
    put:
      summary: Update or insert online availability information given a record's naId.
      tags:
      - Online Availability
      requestBody:
        description: Add online availability information about a record.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/onlineAvailabilityBody'
      responses:
        '200':
          description: A body of response data containing full record objects if any were found.
        '400':
          description: Bad Request. Invalid search terms, revise terms.
        '422':
          description: Unprocessable Entity. Query must be a non-empty string.
  /online-availability/delete:
    delete:
      summary: Completely remove online availability information for a given record naId.
      tags:
      - Online Availability
      parameters:
      - $ref: '#/components/parameters/paramNaId'
      responses:
        '200':
          description: A message confirming the online availability status for the specified record was successfully deleted
        '500':
          description: Internal server error.
components:
  parameters:
    paramLimit:
      in: query
      name: limit
      description: Maximum number of results returned for each page of paginated data.
      required: false
      schema:
        default: 20
        maximum: 1000
        type: integer
      example: 75
    paramPage:
      in: query
      name: page
      description: Page number of the paginated result set in which to return.
      required: false
      schema:
        default: 1
        maximum: 10000
        type: integer
      example: 20
    paramPathNaId:
      in: path
      name: naId
      description: Unique, NARA-specific identifier given to each record.
      required: false
      schema:
        maximum: 30
        type: integer
      example: 146919092
    paramAvailabilityStatus:
      in: query
      name: availabilityStatus
      description: An array of online availability status values
      required: false
      schema:
        enum:
        - active
        - inactive
        type: string
      example: active, inactive
    paramNaId:
      in: query
      name: naId
      description: An array of NARA-specific identifiers, each of which is unique to a single record.
      required: false
      schema:
        maximum: 10000
        type: string
      example: 146919092, 146919093
    paramAvailability:
      in: query
      name: availability
      description: An array of online availability values
      required: false
      schema:
        enum:
        - fullyDigitized
        - unrestrictedOnly
        type: string
      example: fullyDigitized, unrestrictedOnly
  schemas:
    onlineAvailabilityBody:
      type: object
      properties:
        naId:
          type: string
          example: 123456
          maximum: 30
        status:
          type: string
          example: active
        availability:
          type: string
          example: fullyDigitized
          accepted:
          - fullyDigitized
          - unrestrictedOnly
      required:
      - naId