OpenGov Co Comment API

openapi: 3.2.0
info:
  title: OpenGov Purchase Order Co Comment 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: coComment
paths:
  /api/v1/po/entities/{entityId}/purchase-orders/{poId}/change-orders/{coId}/comments:
    post:
      tags:
      - coComment
      operationId: coComment.createCoComment
      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
      - name: poId
        in: path
        schema:
          $ref: '#/components/schemas/NumberFromString'
        required: true
      - name: coId
        in: path
        schema:
          $ref: '#/components/schemas/NumberFromString'
        required: true
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - activity
                    properties:
                      activity:
                        type: object
                        required:
                        - activityId
                        - entryType
                        - commentId
                        - visibilityScope
                        - body
                        - author
                        - lineItem
                        - attachments
                        - createdAt
                        - isEdited
                        properties:
                          activityId:
                            type: number
                          entryType:
                            $ref: '#/components/schemas/ActivityLogEntryType'
                          commentId:
                            anyOf:
                            - type: number
                            - type: 'null'
                          visibilityScope:
                            type: string
                            enum:
                            - INTERNAL
                            - EXTERNAL
                          body:
                            anyOf:
                            - type: object
                              required:
                              - html
                              properties:
                                html:
                                  type: string
                              additionalProperties: false
                            - type: 'null'
                          author:
                            type: object
                            required:
                            - userId
                            - displayName
                            properties:
                              userId:
                                type: string
                              displayName:
                                type: string
                            additionalProperties: false
                          lineItem:
                            anyOf:
                            - type: object
                              required:
                              - lineItemId
                              properties:
                                lineItemId:
                                  type: number
                              additionalProperties: false
                            - type: 'null'
                          attachments:
                            type: array
                            items:
                              type: object
                              required:
                              - id
                              - fileName
                              - mimeType
                              - sizeBytes
                              - downloadPath
                              properties:
                                id:
                                  type: number
                                fileName:
                                  type: string
                                mimeType:
                                  type: string
                                sizeBytes:
                                  type: number
                                downloadPath:
                                  type: string
                                baselineAttachmentId:
                                  anyOf:
                                  - type: number
                                  - type: 'null'
                                deletedAt:
                                  anyOf:
                                  - type: string
                                  - type: 'null'
                              additionalProperties: false
                          createdAt:
                            type: string
                          isEdited:
                            type: boolean
                          logMessage:
                            anyOf:
                            - type: string
                            - type: 'null'
                          changeOrderId:
                            anyOf:
                            - type: number
                            - type: 'null'
                        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
        '409':
          description: ConflictError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 409
                  code:
                    type: string
                    description: Machine-readable error code
                    example: IDEMPOTENCY_CONFLICT
                  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: A request with this idempotency key is currently being processed. Retry after the in-flight request completes.
                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: Creates a comment scoped to a specific Change Order (and optionally a CO line). Mirrors POST /purchase-orders/:poId/comments but routes through the CO-scoped guards (CO must belong to PO, CO must be in Draft, attachments must already be CO-scoped).
      summary: Create a CO-scoped comment or attachment-only entry
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: []
              properties:
                body:
                  anyOf:
                  - type: object
                    required:
                    - html
                    properties:
                      html:
                        type: string
                        description: a string at most 51200 character(s) long
                        title: maxLength(51200)
                        maxLength: 51200
                    additionalProperties: false
                  - type: 'null'
                visibilityScope:
                  type: string
                  enum:
                  - INTERNAL
                  - EXTERNAL
                coLineId:
                  anyOf:
                  - type: number
                  - type: 'null'
                lineItemId:
                  anyOf:
                  - type: number
                  - type: 'null'
                attachmentIds:
                  type: array
                  items:
                    type: number
                  description: an array of at most 100 item(s)
                  title: maxItems(100)
                  maxItems: 100
              additionalProperties: false
        required: true
  /api/v1/po/entities/{entityId}/purchase-orders/{poId}/change-orders/{coId}/comments/{commentId}:
    patch:
      tags:
      - coComment
      operationId: coComment.editCoComment
      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
      - name: poId
        in: path
        schema:
          $ref: '#/components/schemas/NumberFromString'
        required: true
      - name: coId
        in: path
        schema:
          $ref: '#/components/schemas/NumberFromString'
        required: true
      - name: commentId
        in: path
        schema:
          $ref: '#/components/schemas/NumberFromString'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - activity
                    properties:
                      activity:
                        type: object
                        required:
                        - activityId
                        - entryType
                        - commentId
                        - visibilityScope
                        - body
                        - author
                        - lineItem
                        - attachments
                        - createdAt
                        - isEdited
                        properties:
                          activityId:
                            type: number
                          entryType:
                            $ref: '#/components/schemas/ActivityLogEntryType'
                          commentId:
                            anyOf:
                            - type: number
                            - type: 'null'
                          visibilityScope:
                            type: string
                            enum:
                            - INTERNAL
                            - EXTERNAL
                          body:
                            anyOf:
                            - type: object
                              required:
                              - html
                              properties:
                                html:
                                  type: string
                              additionalProperties: false
                            - type: 'null'
                          author:
                            type: object
                            required:
                            - userId
                            - displayName
                            properties:
                              userId:
                                type: string
                              displayName:
                                type: string
                            additionalProperties: false
                          lineItem:
                            anyOf:
                            - type: object
                              required:
                              - lineItemId
                              properties:
                                lineItemId:
                                  type: number
                              additionalProperties: false
                            - type: 'null'
                          attachments:
                            type: array
                            items:
                              type: object
                              required:
                              - id
                              - fileName
                              - mimeType
                              - sizeBytes
                              - downloadPath
                              properties:
                                id:
                                  type: number
                                fileName:
                                  type: string
                                mimeType:
                                  type: string
                                sizeBytes:
                                  type: number
                                downloadPath:
                                  type: string
                                baselineAttachmentId:
                                  anyOf:
                                  - type: number
                                  - type: 'null'
                                deletedAt:
                                  anyOf:
                                  - type: string
                                  - type: 'null'
                              additionalProperties: false
                          createdAt:
                            type: string
                          isEdited:
                            type: boolean
                          logMessage:
                            anyOf:
                            - type: string
                            - type: 'null'
                          changeOrderId:
                            anyOf:
                            - type: number
                            - type: 'null'
                        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
        '409':
          description: ConflictError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 409
                  code:
                    type: string
                    description: Machine-readable error code
                    example: IDEMPOTENCY_CONFLICT
                  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: A request with this idempotency key is currently being processed. Retry after the in-flight request completes.
                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: Updates a CO-scoped comment body and/or attachment links. CO must remain in Draft. Author-only (mirrors PO precedent).
      summary: Edit a CO-scoped comment (body, add/remove attachments)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: []
              properties:
                body:
                  anyOf:
                  - type: object
                    required:
                    - html
                    properties:
                      html:
                        type: string
                        description: a string at most 51200 character(s) long
                        title: maxLength(51200)
                        maxLength: 51200
                    additionalProperties: false
                  - type: 'null'
                addAttachmentIds:
                  type: array
                  items:
                    type: number
                  description: an array of at most 100 item(s)
                  title: maxItems(100)
                  maxItems: 100
                removeAttachmentIds:
                  type: array
                  items:
                    type: number
              additionalProperties: false
        required: true
    delete:
      tags:
      - coComment
      operationId: coComment.deleteCoComment
      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
      - name: poId
        in: path
        schema:
          $ref: '#/components/schemas/NumberFromString'
        required: true
      - name: coId
        in: path
        schema:
          $ref: '#/components/schemas/NumberFromString'
        required: true
      - name: commentId
        in: path
        schema:
          $ref: '#/components/schemas/NumberFromString'
        required: true
      responses:
        '204':
          description: Success
        '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
            

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/opengov/refs/heads/main/openapi/opengov-cocomment-api-openapi.yml