OpenGov Receipt Attachments API

openapi: 3.2.0
info:
  title: OpenGov Receipt Receipt Attachments API
  version: 1.0.0
  description: API for managing receipts.
servers:
- url: https://api-receipts.procurement.opengov.com
  description: Production
- url: https://api-receipts.procurement.ogstaging.us
  description: Staging
- url: https://api-receipts.procurement.ogintegration.us
  description: Integration
security: []
tags:
- name: receiptAttachments
paths:
  /api/v1/entities/{entityId}/receipts/{id}/attachments/upload:
    post:
      tags:
      - receiptAttachments
      operationId: receiptAttachments.initializeUpload
      parameters:
      - name: entityId
        in: path
        schema:
          type: string
          description: The UUID of the Platform entity
          default: 04eb277c-f9cd-42b0-9610-0f068f6aaea1
        required: true
        description: The UUID of the Platform entity
      - name: id
        in: path
        schema:
          type: string
          description: a string to be decoded into a number
        required: true
        description: a string to be decoded into a number
      security:
      - platformApiKey: []
      - platformBearerToken: []
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - attachmentId
                    - uploadUrl
                    - storageKey
                    properties:
                      attachmentId:
                        type: integer
                        description: an integer
                        title: int
                      uploadUrl:
                        type: string
                      storageKey:
                        type: string
                    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: Error code identifier
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Field-specific validation errors
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Field path that failed validation
                          example: status
                        detail:
                          type: string
                          description: Specific validation error message
                          example: Expected one of ["Draft", "Submitted", "Cancelled"], received "Draft112"
                        code:
                          type: string
                          description: Optional error code
                          example: INVALID_ENUM_VALUE
                        data:
                          type: object
                          description: Optional additional error context
                          additionalProperties: true
                      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: 400
                  code:
                    type: string
                    description: Error code identifier
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Field-specific validation errors
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Field path that failed validation
                          example: status
                        detail:
                          type: string
                          description: Specific validation error message
                          example: Expected one of ["Draft", "Submitted", "Cancelled"], received "Draft112"
                        code:
                          type: string
                          description: Optional error code
                          example: INVALID_ENUM_VALUE
                        data:
                          type: object
                          description: Optional additional error context
                          additionalProperties: true
                      required:
                      - parameter
                      - detail
                required:
                - status
                - code
                - detail
        '403':
          description: Receipt action forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  code:
                    type: string
                    description: Error code identifier
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Field-specific validation errors
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Field path that failed validation
                          example: status
                        detail:
                          type: string
                          description: Specific validation error message
                          example: Expected one of ["Draft", "Submitted", "Cancelled"], received "Draft112"
                        code:
                          type: string
                          description: Optional error code
                          example: INVALID_ENUM_VALUE
                        data:
                          type: object
                          description: Optional additional error context
                          additionalProperties: true
                      required:
                      - parameter
                      - detail
                required:
                - status
                - code
                - detail
        '404':
          description: EntityNotFoundError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  code:
                    type: string
                    description: Error code identifier
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Field-specific validation errors
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Field path that failed validation
                          example: status
                        detail:
                          type: string
                          description: Specific validation error message
                          example: Expected one of ["Draft", "Submitted", "Cancelled"], received "Draft112"
                        code:
                          type: string
                          description: Optional error code
                          example: INVALID_ENUM_VALUE
                        data:
                          type: object
                          description: Optional additional error context
                          additionalProperties: true
                      required:
                      - parameter
                      - detail
                required:
                - status
                - code
                - detail
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  code:
                    type: string
                    description: Error code identifier
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Field-specific validation errors
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Field path that failed validation
                          example: status
                        detail:
                          type: string
                          description: Specific validation error message
                          example: Expected one of ["Draft", "Submitted", "Cancelled"], received "Draft112"
                        code:
                          type: string
                          description: Optional error code
                          example: INVALID_ENUM_VALUE
                        data:
                          type: object
                          description: Optional additional error context
                          additionalProperties: true
                      required:
                      - parameter
                      - detail
                required:
                - status
                - code
                - detail
        '500':
          description: InfrastructureError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  code:
                    type: string
                    description: Error code identifier
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Field-specific validation errors
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Field path that failed validation
                          example: status
                        detail:
                          type: string
                          description: Specific validation error message
                          example: Expected one of ["Draft", "Submitted", "Cancelled"], received "Draft112"
                        code:
                          type: string
                          description: Optional error code
                          example: INVALID_ENUM_VALUE
                        data:
                          type: object
                          description: Optional additional error context
                          additionalProperties: true
                      required:
                      - parameter
                      - detail
                required:
                - status
                - code
                - detail
      description: Creates an rcp_attachments row with upload_status=INITIATED and returns a presigned S3 PUT URL. Client uploads the file directly to S3. Allowed only while the receipt is in Draft or Submitted status.
      summary: Initialize a file upload (get presigned PUT URL)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadRaw'
        required: true
  /api/v1/entities/{entityId}/receipts/{id}/attachments/{attachmentId}/complete:
    post:
      tags:
      - receiptAttachments
      operationId: receiptAttachments.completeUpload
      parameters:
      - name: entityId
        in: path
        schema:
          type: string
          description: The UUID of the Platform entity
          default: 04eb277c-f9cd-42b0-9610-0f068f6aaea1
        required: true
        description: The UUID of the Platform entity
      - name: id
        in: path
        schema:
          type: string
          description: a string to be decoded into a number
        required: true
        description: a string to be decoded into a number
      - name: attachmentId
        in: path
        schema:
          type: string
          description: a string to be decoded into a number
        required: true
        description: a string to be decoded into a number
      security:
      - platformApiKey: []
      - platformBearerToken: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - attachment
                    properties:
                      attachment:
                        type: object
                        required:
                        - id
                        - fileName
                        - mimeType
                        - sizeBytes
                        - storageKey
                        - createdAt
                        properties:
                          id:
                            type: integer
                            description: an integer
                            title: int
                          fileName:
                            type: string
                            description: a string at most 255 character(s) long
                            title: maxLength(255)
                            maxLength: 255
                          mimeType:
                            type: string
                            description: a string at most 255 character(s) long
                            title: maxLength(255)
                            maxLength: 255
                          sizeBytes:
                            type: integer
                            description: an integer
                            title: int
                          uploadStatus:
                            $ref: '#/components/schemas/UploadStatus'
                          storageKey:
                            type: string
                            description: a string at most 512 character(s) long
                            title: maxLength(512)
                            maxLength: 512
                          createdAt:
                            $ref: '#/components/schemas/DateTimeUtc'
                        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: Error code identifier
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Field-specific validation errors
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Field path that failed validation
                          example: status
                        detail:
                          type: string
                          description: Specific validation error message
                          example: Expected one of ["Draft", "Submitted", "Cancelled"], received "Draft112"
                        code:
                          type: string
                          description: Optional error code
                          example: INVALID_ENUM_VALUE
                        data:
                          type: object
                          description: Optional additional error context
                          additionalProperties: true
                      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: 400
                  code:
                    type: string
                    description: Error code identifier
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Field-specific validation errors
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Field path that failed validation
                          example: status
                        detail:
                          type: string
                          description: Specific validation error message
                          example: Expected one of ["Draft", "Submitted", "Cancelled"], received "Draft112"
                        code:
                          type: string
                          description: Optional error code
                          example: INVALID_ENUM_VALUE
                        data:
                          type: object
                          description: Optional additional error context
                          additionalProperties: true
                      required:
                      - parameter
                      - detail
                required:
                - status
                - code
                - detail
        '403':
          description: Receipt action forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  code:
                    type: string
                    description: Error code identifier
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Field-specific validation errors
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Field path that failed validation
                          example: status
                        detail:
                          type: string
                          description: Specific validation error message
                          example: Expected one of ["Draft", "Submitted", "Cancelled"], received "Draft112"
                        code:
                          type: string
                          description: Optional error code
                          example: INVALID_ENUM_VALUE
                        data:
                          type: object
                          description: Optional additional error context
                          additionalProperties: true
                      required:
                      - parameter
                      - detail
                required:
                - status
                - code
                - detail
        '404':
          description: EntityNotFoundError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  code:
                    type: string
                    description: Error code identifier
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Field-specific validation errors
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Field path that failed validation
                          example: status
                        detail:
                          type: string
                          description: Specific validation error message
                          example: Expected one of ["Draft", "Submitted", "Cancelled"], received "Draft112"
                        code:
                          type: string
                          description: Optional error code
                          example: INVALID_ENUM_VALUE
                        data:
                          type: object
                          description: Optional additional error context
                          additionalProperties: true
                      required:
                      - parameter
                      - detail
                required:
                - status
                - code
                - detail
        '409':
          description: Attachment invalid state
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  code:
                    type: string
                    description: Error code identifier
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Field-specific validation errors
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Field path that failed validation
                          example: status
                        detail:
                          type: string
                          description: Specific validation error message
                          example: Expected one of ["Draft", "Submitted", "Cancelled"], received "Draft112"
                        code:
                          type: string
                          description: Optional error code
                          example: INVALID_ENUM_VALUE
                        data:
                          type: object
                          description: Optional additional error context
                          additionalProperties: true
                      required:
                      - parameter
                      - detail
                required:
                - status
                - code
                - detail
        '500':
          description: InfrastructureError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  code:
                    type: string
                    description: Error code identifier
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Field-specific validation errors
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Field path that failed validation
                          example: status
                        detail:
                          type: string
                          description: Specific validation error message
                          example: Expected one of ["Draft", "Submitted", "Cancelled"], received "Draft112"
                        code:
                          type: string
                          description: Optional error code
                          example: INVALID_ENUM_VALUE
                        data:
                          type: object
                          description: Optional additional error context
                          additionalProperties: true
                      required:
                      - parameter
                      - detail
                required:
                - status
                - code
                - detail
      description: Client calls this after uploading to S3. If success=true (default), server verifies the S3 object exists via HeadObject and transitions INITIATED → UPLOADED. If success=false, server transitions INITIATED → FAILED (client-signaled failure).
      summary: Complete a file upload (confirm S3 object)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: []
              properties:
                success:
                  type: boolean
              additionalProperties: false
        required: true
  /api/v1/entities/{entityId}/receipts/{id}/attachments/{attachmentId}/download:
    get:
      tags:
      - receiptAttachments
      operationId: receiptAttachments.downloadAttachment
      parameters:
      - name: entityId
        in: path
        schema:
          type: string
          description: The UUID of the Platform entity
          default: 04eb277c-f9cd-42b0-9610-0f068f6aaea1
        required: true
        description: The UUID of the Platform entity
      - name: id
        in: path
        schema:
          type: string
          description: a string to be decoded into a number
        required: true
        description: a string to be decoded into a number
      - name: attachmentId
        in: path
        schema:
          type: string
          description: a string to be decoded into a number
        required: true
        description: a string to be decoded into a number
      security:
      - platformApiKey: []
      - platformBearerToken: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - downloadUrl
                    - fileName
                    properties:
                      downloadUrl:
                        type: string
                      fileName:
                        type: string
                    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: Error code identifier
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Field-specific validation errors
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Field path that failed validation
                          example: status
                        detail:
                          type: string
                          description: Specific validation error message
                          example: Expected one of ["Draft", "Submitted", "Cancelled"], received "Draft112"
                        code:
                          type: string
                          description: Optional error code
                          example: INVALID_ENUM_VALUE
                        data:
                          type: object
                          description: Optional additional error context
                          additionalProperties: true
                      required:
                      - parameter
                      - detail
                required:
        

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