OpenGov Categories API

openapi: 3.2.0
info:
  title: Opengov Categories API
  version: '1.0'
  description: 'Operations tagged Categories across 2 of this provider''s published API definitions: opengov-procurement-v1-openapi.yml, opengov-procurement-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.procurement.opengov.com
  description: Production
tags:
- name: Categories
  x-displayName: Categories
paths:
  /public/api/v1/contracts/categories:
    servers:
    - url: https://api.procurement.opengov.com
      description: Production
    get:
      description: This endpoint fetches a paginated list of categories for a given category set (NIGP, NAICS, or UNSPSC), ordered by ID, with cursor-based pagination.
      operationId: CategoriesV1Controller_listCategories
      parameters:
      - name: set
        required: true
        in: query
        description: The category set to retrieve.
        schema:
          example: nigp
          type: string
          enum:
          - nigp
          - naics
          - unspsc
      - name: first
        required: false
        in: query
        description: The number of categories to return.
        schema:
          default: 10
          example: 10
          type: number
      - name: after
        required: false
        in: query
        description: A cursor for use in pagination.
        schema:
          example: Y2F0ZWdvcnkuaWQ9MQ==
          type: string
      responses:
        '200':
          description: A paginated list of categories was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCategoriesResponseDto'
        '400':
          description: The request parameters are invalid.
          content:
            application/json:
              examples:
                Invalid `set` parameter:
                  value:
                    statusCode: 400
                    message:
                    - '`set` query parameter must be one of: nigp, naics, unspsc'
                    error: Bad Request
                Invalid `first` parameter (not an integer):
                  value:
                    statusCode: 400
                    message:
                    - '`first` query parameter must be an integer'
                    error: Bad Request
                Invalid `first` parameter (negative value):
                  value:
                    statusCode: 400
                    message:
                    - '`first` query parameter must be a non-negative number'
                    error: Bad Request
                Malformed `after` cursor:
                  value:
                    statusCode: 400
                    message: Invalid `after` cursor, please only use cursors generated by this API
                    error: Bad Request
        '401':
          content:
            application/json:
              examples:
                Missing Authorization Header:
                  value:
                    statusCode: 401
                    message: Authorization header not found
                    error: Unauthorized
                Missing Authorization Value:
                  value:
                    statusCode: 401
                    message: Authorization header value not found
                    error: Unauthorized
                Invalid Authorization Header:
                  value:
                    statusCode: 401
                    message: Invalid authorization header
                    error: Unauthorized
                Token Verification Failed:
                  value:
                    statusCode: 401
                    message: Token verification failed
                    error: Unauthorized
                API Key Authentication Failed:
                  value:
                    statusCode: 401
                    message: API key authentication failed
                    error: Unauthorized
                Incomplete User Information:
                  value:
                    statusCode: 401
                    message: 'User or entity information incomplete: userUUID=undefined, entityUUID=undefined'
                    error: Unauthorized
                Failed to Get Entitlements:
                  value:
                    statusCode: 401
                    message: Failed to get entitlements
                    error: Unauthorized
          description: ''
        '403':
          content:
            application/json:
              examples:
                Missing Required Entitlements:
                  value:
                    statusCode: 403
                    message: 'Required entitlements not found: PLATFORM_ADMIN_SETTINGS_ENTITLEMENT, PRO_ENTITLEMENT'
                    error: Forbidden
                Not a Member of Requested Entity:
                  value:
                    statusCode: 403
                    message: User is not a member of the requested entity
                    error: Forbidden
                No Associated Government Organization:
                  value:
                    statusCode: 403
                    message: No associated government organization found for user
                    error: Forbidden
          description: ''
        '404':
          content:
            application/json:
              examples:
                Requested Entity Not Found:
                  value:
                    statusCode: 404
                    message: Requested entity not found
                    error: Not Found
          description: ''
        '500':
          content:
            application/json:
              examples:
                Server Error:
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
          description: ''
      summary: List Categories
      tags:
      - Categories
      security:
      - BearerToken: []
      - APIKey: []
  /public/api/v2/entities/{entityUuid}/contracts/categories:
    servers:
    - url: https://api.procurement.opengov.com
      description: Production
    get:
      description: This endpoint fetches a paginated list of categories for a given category set (NIGP, NAICS, or UNSPSC), ordered by ID, with cursor-based pagination.
      operationId: CategoriesV2Controller_listCategories
      parameters:
      - name: set
        required: true
        in: query
        description: The category set to retrieve.
        schema:
          example: nigp
          type: string
          enum:
          - nigp
          - naics
          - unspsc
      - name: first
        required: false
        in: query
        description: The number of categories to return.
        schema:
          default: 10
          example: 10
          type: number
      - name: after
        required: false
        in: query
        description: A cursor for use in pagination.
        schema:
          example: Y2F0ZWdvcnkuaWQ9MQ==
          type: string
      - required: true
        name: entityUuid
        description: UUID of the OpenGov entity (typically an agency) the request is acting on
        schema:
          type: string
          format: uuid
        in: path
      responses:
        '200':
          description: A paginated list of categories was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCategoriesResponseDto'
        '400':
          description: The request parameters are invalid.
          content:
            application/json:
              examples:
                Invalid `set` parameter:
                  value:
                    statusCode: 400
                    message:
                    - '`set` query parameter must be one of: nigp, naics, unspsc'
                    error: Bad Request
                Invalid `first` parameter (not an integer):
                  value:
                    statusCode: 400
                    message:
                    - '`first` query parameter must be an integer'
                    error: Bad Request
                Invalid `first` parameter (negative value):
                  value:
                    statusCode: 400
                    message:
                    - '`first` query parameter must be a non-negative number'
                    error: Bad Request
                Malformed `after` cursor:
                  value:
                    statusCode: 400
                    message: Invalid `after` cursor, please only use cursors generated by this API
                    error: Bad Request
        '401':
          content:
            application/json:
              examples:
                Missing Authorization Header:
                  value:
                    statusCode: 401
                    message: Authorization header not found
                    error: Unauthorized
                Missing Authorization Value:
                  value:
                    statusCode: 401
                    message: Authorization header value not found
                    error: Unauthorized
                Invalid Authorization Header:
                  value:
                    statusCode: 401
                    message: Invalid authorization header
                    error: Unauthorized
                Token Verification Failed:
                  value:
                    statusCode: 401
                    message: Token verification failed
                    error: Unauthorized
                API Key Authentication Failed:
                  value:
                    statusCode: 401
                    message: API key authentication failed
                    error: Unauthorized
                Incomplete User Information:
                  value:
                    statusCode: 401
                    message: 'User or entity information incomplete: userUUID=undefined, entityUUID=undefined'
                    error: Unauthorized
                Failed to Get Entitlements:
                  value:
                    statusCode: 401
                    message: Failed to get entitlements
                    error: Unauthorized
          description: ''
        '403':
          content:
            application/json:
              examples:
                Missing Required Entitlements:
                  value:
                    statusCode: 403
                    message: 'Required entitlements not found: PLATFORM_ADMIN_SETTINGS_ENTITLEMENT, PRO_ENTITLEMENT'
                    error: Forbidden
                Not a Member of Requested Entity:
                  value:
                    statusCode: 403
                    message: User is not a member of the requested entity
                    error: Forbidden
                No Associated Government Organization:
                  value:
                    statusCode: 403
                    message: No associated government organization found for user
                    error: Forbidden
          description: ''
        '404':
          content:
            application/json:
              examples:
                Requested Entity Not Found:
                  value:
                    statusCode: 404
                    message: Requested entity not found
                    error: Not Found
          description: ''
        '500':
          content:
            application/json:
              examples:
                Server Error:
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
          description: ''
      summary: List Categories
      tags:
      - Categories
      security:
      - BearerToken: []
      - APIKey: []
components:
  schemas:
    PageInfo:
      type: object
      properties:
        totalResultsCount:
          type: number
          description: The total number of categories matching the query.
          example: 250
        endCursor:
          type: object
          description: The cursor that points to the last category on the current page.
          example: Y2F0ZWdvcnkuaWQ9MTMz
          nullable: true
        hasMoreResults:
          type: boolean
          description: Indicates whether there are more categories available to fetch.
          example: true
      required:
      - totalResultsCount
      - endCursor
      - hasMoreResults
    ListCategoriesResponseDto:
      type: object
      properties:
        results:
          description: A list of categories, each with a cursor for pagination.
          type: array
          items:
            $ref: '#/components/schemas/CategoryEdge'
        pageInfo:
          description: Information to assist with pagination.
          allOf:
          - $ref: '#/components/schemas/PageInfo'
      required:
      - results
      - pageInfo
    CategoryEdge:
      type: object
      properties:
        node:
          description: The category data.
          allOf:
          - $ref: '#/components/schemas/CategoryDetails'
        cursor:
          type: string
          description: A cursor for use in pagination.
          example: Y2F0ZWdvcnkuaWQ9NDI=
      required:
      - node
      - cursor
    CategoryDetails:
      type: object
      properties:
        code:
          type: string
          description: The code representing the category.
          example: '20800'
        title:
          type: string
          description: The category title.
          example: Office Supplies
        codeType:
          type: string
          description: The category set this category belongs to.
          example: NIGP
      required:
      - code
      - title
      - codeType
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
    xApiKeyHeaderAuth:
      type: apiKey
      in: header
      name: x-api-key
    APIKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'Format: `Token your-api-key-here`'
    BearerToken:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Enter Bearer Token without Bearer prefix
x-refined-from:
- opengov-procurement-v1-openapi.yml
- opengov-procurement-v2-openapi.yml
x-og-spec-id: bnp-api-v1
x-og-env-servers:
  production: https://api.bnp.opengov.com
  development: https://api.bnp.ogintegration.us