National Archives and Records Administration Contributions API

openapi: 3.2.0
info:
  title: NextGen Catalog Contributions API
  version: 0.2.0
  description: This is the NextGen Catalog API application made with Express and documented with Swagger.
servers:
- url: https://catalog.archives.gov/api/v2/
tags:
- name: Contributions
  description: Contribution search and data retrieval; Contributions include Tags, Transcriptions, and Comments - search/retrieve contributions when you want to return any contribution type.
paths:
  /contributions/:
    put:
      summary: Update a contribution
      description: Update a contribution to a record.
      tags:
      - Contributions
      requestBody:
        description: Update a contribution to a record.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/contributionBody'
      parameters:
      - in: query
        name: review
        schema:
          type: boolean
        required: false
        description: review flag which when true indicates that a contribution should be reviewed
        example: 'true'
      responses:
        '200':
          description: A response body containing confirmation that the transcription was added successfully.
        '400':
          description: Bad Request. Invalid search terms, revise terms.
        '422':
          description: An error response while processing the request to add a transcription.
      operationId: putContributions
      x-operation-id-source: derived
    get:
      summary: Get contribution data directly from the database
      description: Get contribution data directly from the database. Returns a JSON result.
      tags:
      - Contributions
      parameters:
      - $ref: '#/components/parameters/paramUserId'
      - $ref: '#/components/parameters/paramContStatus'
      - $ref: '#/components/parameters/paramContType'
      - $ref: '#/components/parameters/paramTargetNaIdFilter'
      - $ref: '#/components/parameters/paramCreatedAtFilter'
      - $ref: '#/components/parameters/paramUpdatedAtFilter'
      - $ref: '#/components/parameters/paramSortBy'
      - $ref: '#/components/parameters/paramIncludeTotalCount'
      responses:
        '200':
          description: A body of response data containing contribution data from the database if any were found.
        '422':
          description: Unprocessable Entity.
      operationId: getContributions
      x-operation-id-source: derived
  /contributions/search:
    get:
      summary: Get search results for contributions data by sending a request with search…
      description: Get search results for contributions data by sending a request with search parameters to the catalog. Returns a JSON result.
      tags:
      - Contributions
      parameters:
      - $ref: '#/components/parameters/paramContQuery'
      - $ref: '#/components/parameters/paramContId'
      - $ref: '#/components/parameters/paramUserName'
      - $ref: '#/components/parameters/paramUserId'
      - $ref: '#/components/parameters/paramNaId'
      - $ref: '#/components/parameters/paramDebug'
      - $ref: '#/components/parameters/paramSearchAfterContribution'
      responses:
        '200':
          description: A body of response data containing full contribution objects if any were found.
        '422':
          description: Unprocessable Entity.
      operationId: getContributionsSearch
      x-operation-id-source: derived
  /contributions/targetObjectId/{targetObjectId}:
    get:
      summary: Get contribution data by target object id directly from the database
      description: Get contribution data by target object id directly from the database. Returns a JSON result.
      tags:
      - Contributions
      parameters:
      - $ref: '#/components/parameters/paramTargetObjectId'
      - $ref: '#/components/parameters/paramContStatus'
      - $ref: '#/components/parameters/paramContType'
      - $ref: '#/components/parameters/paramTargetPageNum'
      responses:
        '200':
          description: A body of response data containing contribution data from the database if any were found.
        '422':
          description: Unprocessable Entity.
      operationId: getContributionsTargetObjectIdByTargetObjectId
      x-operation-id-source: derived
  /contributions/parentContributionId/{parentContributionId}:
    get:
      summary: Get contribution data by parent contribution id directly from the database
      description: Get contribution data by parent contribution id directly from the database. Returns a JSON result.
      tags:
      - Contributions
      parameters:
      - $ref: '#/components/parameters/paramParentContUuid'
      - $ref: '#/components/parameters/paramContStatus'
      - $ref: '#/components/parameters/paramContType'
      - $ref: '#/components/parameters/paramTargetNaIdFilter'
      - $ref: '#/components/parameters/paramCreatedAtFilter'
      - $ref: '#/components/parameters/paramUpdatedAtFilter'
      - $ref: '#/components/parameters/paramSortBy'
      responses:
        '200':
          description: A body of response data containing contribution data from the database if any were found.
        '422':
          description: Unprocessable Entity.
      operationId: getContributionsParentContributionIdByParentContributionId
      x-operation-id-source: derived
  /contributions/contributionId/{contributionId}:
    get:
      summary: Get contribution data by contribution id directly from the database
      description: Get contribution data by contribution id directly from the database. Returns a JSON result.
      tags:
      - Contributions
      parameters:
      - $ref: '#/components/parameters/paramContUuid'
      - $ref: '#/components/parameters/paramContStatus'
      - $ref: '#/components/parameters/paramContType'
      responses:
        '200':
          description: A body of response data containing contribution data from the database if any were found.
        '422':
          description: Unprocessable Entity.
      operationId: getContributionsContributionIdByContributionId
      x-operation-id-source: derived
  /contributions/userId/{userId}:
    get:
      summary: Get contribution data by user id directly from the database
      description: Get contribution data by user id directly from the database. Returns a JSON result.
      tags:
      - Contributions
      parameters:
      - $ref: '#/components/parameters/paramContUserId'
      - $ref: '#/components/parameters/paramContStatus'
      - $ref: '#/components/parameters/paramContType'
      - $ref: '#/components/parameters/updatedAfter'
      - $ref: '#/components/parameters/paramTargetNaIdFilter'
      - $ref: '#/components/parameters/paramCreatedAtFilter'
      - $ref: '#/components/parameters/paramUpdatedAtFilter'
      - $ref: '#/components/parameters/paramSortBy'
      responses:
        '200':
          description: A body of response data containing contribution data from the database if any were found.
        '422':
          description: Unprocessable Entity.
      operationId: getContributionsUserIdByUserId
      x-operation-id-source: derived
  /contributions/targetNaId/{targetNaId}:
    get:
      summary: Get contribution data by target naId directly from the database
      description: Get contribution data by target naId directly from the database. Returns a JSON result.
      tags:
      - Contributions
      parameters:
      - $ref: '#/components/parameters/paramTargetNaId'
      - $ref: '#/components/parameters/paramContStatus'
      - $ref: '#/components/parameters/paramContType'
      - $ref: '#/components/parameters/paramCreatedAtFilter'
      - $ref: '#/components/parameters/paramUpdatedAtFilter'
      - $ref: '#/components/parameters/paramSortBy'
      responses:
        '200':
          description: A body of response data containing contribution data from the database if any were found.
        '422':
          description: Unprocessable Entity.
      operationId: getContributionsTargetNaIdByTargetNaId
      x-operation-id-source: derived
  /contributions/delete:
    delete:
      summary: Deactivate/remove a contribution
      description: Change the status of a contribution to 'inactive'
      tags:
      - Contributions
      parameters:
      - in: body
        name: contributionList
        schema:
          type: array
        required: true
        description: Array containing contributionIds of the contribution to be deactivated/removed.
        example:
        - e3fe99d2-7af7-11ec-90d6-0242ac120003
        - 3fa85f64-5717-4562-b3fc-2c963f66afa
      - in: body
        name: userId
        schema:
          type: string
        required: true
        description: Moderator's unique identifier which maps to the userId field in the MySQL database
        example: 55555555-5555-5555-5555-555555555555
      responses:
        '200':
          description: A response body containing confirmation that the contribution was deactivated/removed successfully.
        '409':
          description: An error response while processing the request to deactivate/remove the contribution.
      operationId: deleteContributionsDelete
      x-operation-id-source: derived
components:
  parameters:
    paramDebug:
      in: query
      name: debug
      description: Turns on debug mode, showing metadata in the response body, if set to true.
      required: false
      schema:
        maximum: 100
        type: boolean
      example: true
    paramSearchAfterContribution:
      in: query
      name: searchAfter
      description: 'Enables deep pagination to retrieve records beyond the first 10,000 results.  Not compatible with sort, or page parameters.


        For the inital request use `searchAfter=*` and for all subsequent requests set `searchAfter` to the value of the sort array in the last member of `body.hits.hits` for each page.

        '
      required: false
      schema:
        maximum: 100
        type: string
      example: 55555555-5555-5555-5555-555555555555
    paramSortBy:
      in: query
      name: sortBy
      required: false
      schema:
        maximum: 30
        type: string
        enum:
        - contribution.asc
        - contribution.desc
        - createdAt.asc
        - createdAt.desc
        - updatedAt.asc
        - updatedAt.desc
      description: "Sort order:\n * `contribution.asc` - Sort by contribution, ascending from A to Z\n * `contribution.desc` - Sort by contribution, descending from Z to A\n * `createdAt.asc` - Sort by created date, ascending\n * `createdAt.desc` - Sort by created date, descending\n * `updatedAt.asc` - Sort by updated date, ascending\n * `updatedAt.desc` - Sort by updated date, descending\n * `count.asc` - Sort by aggregated tag counts, ascending, ONLY works when contributionType = tag is present\n * `count.desc` - Sort by aggregated tag counts, descending, ONLY works when contributionType = tag is present\n"
    paramTargetNaId:
      in: path
      name: targetNaId
      description: Contribution's target record's unique identifier which maps to the targetNaId field in the MySQL database
      required: true
      schema:
        maximum: 30
        type: integer
      example: 1667758
    paramContQuery:
      in: query
      name: q
      description: A search query string which accepts boolean operators (AND, OR, NOT), wildcards (*), and exact phrases ("").
      required: false
      schema:
        maximum: 1024
        type: string
      examples:
        simple:
          value: we the people
          summary: Simple keyword
          description: Returns results which contain one or more contributions with the words we, the, and people. Note that the boolean operator AND is used by default.
        bool:
          value: people NOT we
          summary: Boolean operators
          description: Returns results which contain one or more contributions with the word people but do not contain the word we.
        exact:
          value: United States
          summary: Exact phrase
          description: Returns results which contain one or more contributions with the words "United" and "States" together.
        stemming:
          value: photo*
          summary: Stemming with wildcards
          description: Returns results which contain one or more contributions with variations of the word "photo", such as "photograph" and "photography".
    paramCreatedAtFilter:
      in: query
      name: createdAt
      description: Contribution's date of creation by which to filter
      required: false
      schema:
        maximum: 30
        type: string
      example: '2020-01-01 07:00:00'
    paramContId:
      in: query
      name: id
      description: An individual contribution's unique identifier which maps to the record.contributionId field
      required: false
      schema:
        maximum: 50
        type: string
      example: 55555555-5555-5555-5555-555555555555
    paramTargetPageNum:
      in: query
      name: targetPageNum
      description: Contribution's target page number which maps to the targetPageNum field in the MySQL database
      required: false
      schema:
        maximum: 30
        type: integer
      example: 1
    updatedAfter:
      in: query
      name: updatedAt
      description: Compares provided timestamp to records updated timestamp, which maps to the updatedAt field in the MySQL database
      required: false
      schema:
        maximum: 30
        type: string
      example: tag
    paramUserId:
      in: query
      name: userId
      description: Contributor's unique identifier which maps to the record.contributor.userId field
      required: false
      schema:
        maximum: 50
        type: string
      example: 55555555-5555-5555-5555-555555555555
    paramContUserId:
      in: query
      name: userId
      description: Contributor's unique identifier which maps to the userId field in the MySQL database
      required: true
      schema:
        maximum: 36
        type: string
      example: 55555555-5555-5555-5555-555555555555
    paramContUuid:
      in: path
      name: contributionId
      description: An individual contribution's unique uuid identifier which maps to the contributorId field in the MySQL database
      required: true
      schema:
        maximum: 50
        type: string
      example: 55555555-5555-5555-5555-555555555555
    paramContType:
      in: query
      name: contributionType
      description: Contribution type which maps to the contributionType field in the MySQL database
      required: false
      schema:
        maximum: 20
        type: string
      example: tag
    paramTargetObjectId:
      in: path
      name: targetObjectId
      description: Contribution's target objects's unique identifier which maps to the targetObjectId field in the MySQL database
      required: true
      schema:
        maximum: 30
        type: integer
      example: 45710028
    paramTargetNaIdFilter:
      in: query
      name: targetNaId
      description: Contribution's target record's unique identifier which maps to the targetNaId field in the MySQL database
      required: false
      schema:
        maximum: 30
        type: string
      example: 1667758
    paramUserName:
      in: query
      name: userName
      description: Contributor's screen name which maps to the record.contributor.userName field
      required: false
      schema:
        maximum: 100
        type: string
      example: johndoe1
    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
    paramIncludeTotalCount:
      in: query
      name: includeTotalCount
      description: Returns the total count of results in each result.
      required: false
      schema:
        maximum: 100
        type: boolean
      example: true
    paramParentContUuid:
      in: path
      name: parentContributionId
      description: A contribution's parent contribution's unique uuid identifier, which maps to the parentContributorId field in the MySQL database
      required: true
      schema:
        maximum: 50
        type: string
      example: 55555555-5555-5555-5555-555555555555
    paramContStatus:
      in: query
      name: status
      description: Contribution's status which maps to the status field in the MySQL database
      required: false
      schema:
        maximum: 30
        type: string
      example: active
    paramUpdatedAtFilter:
      in: query
      name: updatedAt
      description: Contribution's date of modification by which to filter
      required: false
      schema:
        maximum: 30
        type: string
      example: '2020-01-02 07:00:00'