OpenGov Gl Suggestions API

openapi: 3.2.0
info:
  title: OpenGov Purchase Order Gl Suggestions API
  version: 1.0.0
  description: API for managing purchase orders, line items, splits, and vendors.
servers:
- url: https://api-purchase-order.procurement.opengov.com
  description: Production
- url: https://api-purchase-order.procurement.ogstaging.us
  description: Staging
- url: https://api-purchase-order.procurement.ogintegration.us
  description: Integration
security:
- platformApiKey: []
- platformBearerToken: []
tags:
- name: glSuggestions
paths:
  /api/v1/po/entities/{entityId}/gl-suggestions/search:
    post:
      tags:
      - glSuggestions
      operationId: glSuggestions.search
      parameters:
      - name: entityId
        in: path
        schema:
          type: string
          description: The UUID of the Platform entity
          default: 04eb277c-f9cd-42b0-9610-0f068f6aaea1
          format: uuid
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
        description: The UUID of the Platform entity
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - candidates
                    properties:
                      candidates:
                        type: array
                        items:
                          type: object
                          required:
                          - purchaseOrderId
                          - poNumber
                          - poStatus
                          - lineItemId
                          - lineItemSplits
                          - createdAt
                          - lastModifiedAt
                          - similarityScore
                          - matchSource
                          - matchedTerm
                          properties:
                            purchaseOrderId:
                              type: number
                            poNumber:
                              type: string
                              description: a string at most 32 character(s) long
                              title: maxLength(32)
                              maxLength: 32
                            poDescription:
                              anyOf:
                              - type: string
                              - type: 'null'
                            poStatus:
                              $ref: '#/components/schemas/PoStatus'
                            lineItemId:
                              type: number
                            lineItemDescription:
                              anyOf:
                              - type: string
                                description: a string at most 2048 character(s) long
                                title: maxLength(2048)
                                maxLength: 2048
                              - type: 'null'
                            lineItemSplits:
                              type: array
                              items:
                                type: object
                                required: []
                                properties:
                                  accountNumber:
                                    anyOf:
                                    - type: string
                                    - type: 'null'
                                  accountPseudoKey:
                                    anyOf:
                                    - type: string
                                      description: a string at most 64 character(s) long
                                      title: maxLength(64)
                                      maxLength: 64
                                    - type: 'null'
                                  projectAccountNumber:
                                    anyOf:
                                    - type: string
                                      description: a string at most 64 character(s) long
                                      title: maxLength(64)
                                      maxLength: 64
                                    - type: 'null'
                                  projectAccountDescription:
                                    anyOf:
                                    - type: string
                                      description: a string at most 256 character(s) long
                                      title: maxLength(256)
                                      maxLength: 256
                                    - type: 'null'
                                  reimbursable:
                                    type: boolean
                                  allocatedPercent:
                                    anyOf:
                                    - $ref: '#/components/schemas/Decimal_18_2'
                                    - type: 'null'
                                additionalProperties: false
                            createdAt:
                              type: string
                            lastModifiedAt:
                              type: string
                            similarityScore:
                              type: number
                            matchSource:
                              type: string
                              enum:
                              - like
                              - levenshtein
                            matchedTerm:
                              type: string
                          additionalProperties: false
                    additionalProperties: false
                additionalProperties: false
        '400':
          description: The request did not match the expected schema
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  code:
                    type: string
                    description: Machine-readable error code
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Per-field validation errors (present for 400 validation errors)
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Dot-path to the field
                          example: lineItems.0.lineItemSplits.1
                        detail:
                          type: string
                          description: Human-readable validation message
                          example: 'Account 101-5100 has insufficient budget: requested 500.00, available 200.00'
                        code:
                          type: string
                          description: Machine-readable rule identifier
                          example: BUDGET_INSUFFICIENT
                        data:
                          type: object
                          description: Structured context for the error (account codes, amounts, IDs, etc.)
                          additionalProperties: true
                          example:
                            accountNumber: 101-5100
                            accountPseudoKey: GF-101-5100
                            requestedAmount: 500
                            availableAmount: 200
                      required:
                      - parameter
                      - detail
                required:
                - status
                - code
                - detail
        '401':
          description: AuthError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 401
                  code:
                    type: string
                    description: Machine-readable error code
                    example: AuthenticationError
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: Authentication is required to access this resource.
                required:
                - status
                - code
                - detail
        '403':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 403
                  code:
                    type: string
                    description: Machine-readable error code
                    example: AuthorizationError
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: You do not have permission to perform this action.
                required:
                - status
                - code
                - detail
        '404':
          description: EntityNotFoundError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 404
                  code:
                    type: string
                    description: Machine-readable error code
                    example: PurchaseOrderNotFound
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: Purchase order with id 123 was not found.
                required:
                - status
                - code
                - detail
        '500':
          description: InfrastructureError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 500
                  code:
                    type: string
                    description: Machine-readable error code
                    example: InternalServerError
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: An unexpected error occurred while processing your request. Please try again later.
                required:
                - status
                - code
                - detail
      description: "Returns up to `limit` (default 15, max 50) historical PO line items whose descriptions contain any of the input `descriptions` keywords (case-insensitive substring match), along with their splits and PO context. Filters: status != Cancelled, line item has at least one non-deleted split. Designed for an AI-agent consumer to rerank.\n\nPass 1..10 semantically-related keywords for the same logical line item (e.g. `[\"laptop\", \"macbook\"]`). Each candidate is matched against any input term; candidates are deduplicated by line item and the winning term is reported in `matchedTerm`.\n\nEach candidate carries:\n- `matchedTerm`: the input keyword (one of `descriptions`) that produced this candidate's match. Lets the agent cite which query won.\n- `matchSource`:\n  - `\"like\"`: matched via case-insensitive substring containment (`ILIKE '%term%'`). `similarityScore` is 1.0 — every hit is an exact substring match (high precision; preferred).\n  - `\"levenshtein\"`: matched via word-aware Levenshtein character-edit distance after the LIKE path returned no candidates for that term. Use for typo tolerance; `similarityScore` is computed as the average of best per-query-word match scores (each `1 - levenshtein(word, target_word) / max_len`) and lives in the 0..1 range. Agents should weight Levenshtein matches more cautiously."
      summary: Search historical line items for GL suggestions
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - descriptions
              properties:
                descriptions:
                  type: array
                  items:
                    type: string
                    description: a string at most 256 character(s) long
                    title: maxLength(256)
                    minLength: 1
                    maxLength: 256
                  description: an array of at most 10 item(s)
                  title: maxItems(10)
                  minItems: 1
                  maxItems: 10
                limit:
                  allOf:
                  - $ref: '#/components/schemas/Int'
                    description: a number between 1 and 50
                    title: between(1, 50)
                    minimum: 1
                    maximum: 50
                  title: between(1, 50)
                  description: a number between 1 and 50
              additionalProperties: false
        required: true
components:
  schemas:
    Decimal_18_2:
      type: string
      title: Decimal (18,2)
    Int:
      type: integer
      description: an integer
      title: int
    PoStatus:
      type: string
      enum:
      - Draft
      - PendingApproval
      - Approved
      - Issued
      - Closed
      - Cancelled
      description: 'Purchase order status: Draft, PendingApproval, Approved, Issued, Closed, Cancelled'
      title: PO Status
  securitySchemes:
    platformApiKey:
      description: OpenGov Platform API Key
      type: apiKey
      name: Authorization
      in: header
    platformBearerToken:
      type: http
      scheme: bearer