NextGen Catalog API — Contributions

naftiko: 1.0.0-alpha2
info:
  label: NextGen Catalog API — Contributions
  description: 'NextGen Catalog API — Contributions. 9 operations. Lead operation: Update a contribution.. Self-contained
    Naftiko capability covering one National Archives And Records Administration Nara business surface.'
  tags:
  - National Archives And Records Administration Nara
  - Contributions
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    NATIONAL_ARCHIVES_AND_RECORDS_ADMINISTRATION_NARA_API_KEY: NATIONAL_ARCHIVES_AND_RECORDS_ADMINISTRATION_NARA_API_KEY
capability:
  consumes:
  - type: http
    namespace: national-archives-and-records-administration-nara--contributions
    baseUri: https://catalog.archives.gov/api/v2
    description: NextGen Catalog API — Contributions business capability. Self-contained, no shared references.
    resources:
    - name: contributions
      path: /contributions/
      operations:
      - name: put
        method: PUT
        description: Update a contribution.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: review
          in: query
          type: boolean
          description: review flag which when true indicates that a contribution should be reviewed
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: get
        method: GET
        description: Get contribution data directly from the database.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: contributions-contributionId-contributionId
      path: /contributions/contributionId/{contributionId}
      operations:
      - name: get
        method: GET
        description: Get contribution data by contribution id directly from the database.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: contributions-delete
      path: /contributions/delete
      operations:
      - name: delete
        method: DELETE
        description: Deactivate/remove a contribution.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: contributionList
          in: body
          type: array
          description: Array containing contributionIds of the contribution to be deactivated/removed.
          required: true
        - name: userId
          in: body
          type: string
          description: Moderator's unique identifier which maps to the userId field in the MySQL database
          required: true
    - name: contributions-parentContributionId-parentContributionId
      path: /contributions/parentContributionId/{parentContributionId}
      operations:
      - name: get
        method: GET
        description: Get contribution data by parent contribution id directly from the database.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: contributions-search
      path: /contributions/search
      operations:
      - name: get
        method: GET
        description: Get search results for contributions data by sending a request with search parameters to the catalog.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: contributions-targetNaId-targetNaId
      path: /contributions/targetNaId/{targetNaId}
      operations:
      - name: get
        method: GET
        description: Get contribution data by target naId directly from the database.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: contributions-targetObjectId-targetObjectId
      path: /contributions/targetObjectId/{targetObjectId}
      operations:
      - name: get
        method: GET
        description: Get contribution data by target object id directly from the database.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: contributions-userId-userId
      path: /contributions/userId/{userId}
      operations:
      - name: get
        method: GET
        description: Get contribution data by user id directly from the database.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    namespace: national-archives-and-records-administration-nara--contributions-rest
    port: 8080
    description: REST adapter for NextGen Catalog API — Contributions. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/contributions
      name: contributions
      description: REST surface for contributions.
      operations:
      - method: PUT
        name: put
        description: Update a contribution.
        call: national-archives-and-records-administration-nara--contributions.put
        with:
          review: rest.review
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: get
        description: Get contribution data directly from the database.
        call: national-archives-and-records-administration-nara--contributions.get
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contributions/contributionid/{contributionid}
      name: contributions-contributionid-contributionid
      description: REST surface for contributions-contributionId-contributionId.
      operations:
      - method: GET
        name: get
        description: Get contribution data by contribution id directly from the database.
        call: national-archives-and-records-administration-nara--contributions.get
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contributions/delete
      name: contributions-delete
      description: REST surface for contributions-delete.
      operations:
      - method: DELETE
        name: delete
        description: Deactivate/remove a contribution.
        call: national-archives-and-records-administration-nara--contributions.delete
        with:
          contributionList: rest.contributionList
          userId: rest.userId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contributions/parentcontributionid/{parentcontributionid}
      name: contributions-parentcontributionid-parentcontributionid
      description: REST surface for contributions-parentContributionId-parentContributionId.
      operations:
      - method: GET
        name: get
        description: Get contribution data by parent contribution id directly from the database.
        call: national-archives-and-records-administration-nara--contributions.get
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contributions/search
      name: contributions-search
      description: REST surface for contributions-search.
      operations:
      - method: GET
        name: get
        description: Get search results for contributions data by sending a request with search parameters to the catalog.
        call: national-archives-and-records-administration-nara--contributions.get
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contributions/targetnaid/{targetnaid}
      name: contributions-targetnaid-targetnaid
      description: REST surface for contributions-targetNaId-targetNaId.
      operations:
      - method: GET
        name: get
        description: Get contribution data by target naId directly from the database.
        call: national-archives-and-records-administration-nara--contributions.get
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contributions/targetobjectid/{targetobjectid}
      name: contributions-targetobjectid-targetobjectid
      description: REST surface for contributions-targetObjectId-targetObjectId.
      operations:
      - method: GET
        name: get
        description: Get contribution data by target object id directly from the database.
        call: national-archives-and-records-administration-nara--contributions.get
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contributions/userid/{userid}
      name: contributions-userid-userid
      description: REST surface for contributions-userId-userId.
      operations:
      - method: GET
        name: get
        description: Get contribution data by user id directly from the database.
        call: national-archives-and-records-administration-nara--contributions.get
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: national-archives-and-records-administration-nara--contributions-mcp
    port: 9090
    transport: http
    description: MCP adapter for NextGen Catalog API — Contributions. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: update-contribution
      description: Update a contribution.
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: national-archives-and-records-administration-nara--contributions.put
      with:
        review: tools.review
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contribution-data-directly-database
      description: Get contribution data directly from the database.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: national-archives-and-records-administration-nara--contributions.get
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contribution-data-contribution-id
      description: Get contribution data by contribution id directly from the database.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: national-archives-and-records-administration-nara--contributions.get
      outputParameters:
      - type: object
        mapping: $.
    - name: deactivate-remove-contribution
      description: Deactivate/remove a contribution.
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: national-archives-and-records-administration-nara--contributions.delete
      with:
        contributionList: tools.contributionList
        userId: tools.userId
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contribution-data-parent-contribution
      description: Get contribution data by parent contribution id directly from the database.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: national-archives-and-records-administration-nara--contributions.get
      outputParameters:
      - type: object
        mapping: $.
    - name: get-search-results-contributions-data
      description: Get search results for contributions data by sending a request with search parameters to the catalog.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: national-archives-and-records-administration-nara--contributions.get
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contribution-data-target-naid
      description: Get contribution data by target naId directly from the database.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: national-archives-and-records-administration-nara--contributions.get
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contribution-data-target-object
      description: Get contribution data by target object id directly from the database.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: national-archives-and-records-administration-nara--contributions.get
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contribution-data-user-id
      description: Get contribution data by user id directly from the database.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: national-archives-and-records-administration-nara--contributions.get
      outputParameters:
      - type: object
        mapping: $.