openapi.yml

openapi: 3.1.0
info:
  title: OPRE OPS API
  description: OPRE OPS API Specification
  version: 0.1.1
servers:
  - url: https://localhost:8080/api/v1
    description: OPS API Localhost
  - url: https://dev.ops.opre.acf.gov/api/v1/
    description: OPS API Development Server (Live)
  - url: https://stg.ops.opre.acf.gov/api/v1/
    description: OPS API Staging Server (Live)
  - url: https://ops.opre.acf.gov/api/v1/
    description: OPS API Production Server (Live)

tags:
  - name: Agreements
    description: Everything having to do with agreements
  - name: Procurement Actions
    description: Procurement actions for agreements (similar to MAPS AAP)
  - name: Procurement Trackers
    description: Procurement trackers for tracking the workflow of procurement actions
  - name: Procurement Tracker Steps
    description: Individual workflow steps within procurement trackers
  - name: Lookups
    description: Lookup endpoints for enum values and reference data
paths:
  /agreements/:
    get:
      tags:
        - Agreements
      operationId: Get Agreements
      description: Get a list of agreements
      parameters:
        - in: query
          name: fiscal_year
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - in: query
          name: budget_line_status
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - in: query
          name: portfolio
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - in: query
          name: project_id
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - in: query
          name: agreement_reason
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - in: query
          name: agreement_type
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - in: query
          name: name
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - in: query
          name: nick_name
          description: Nickname to filter agreements by
          schema:
            type: string
          style: form
        - in: query
          name: search
          description: Search terms for finding agreements by name (case-insensitive)
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - in: query
          name: only_my
          description: Only includes agreements that a user owns
          schema:
            type: boolean
          style: form
        - in: query
          name: exact_match
          description: >
            When true, forces exact matching on agreement names instead of partial matching.
            Only applies when filtering by agreement name. Default is true (exact match).
          schema:
            type: boolean
            default: true
          style: form
        - in: query
          name: sort_conditions
          description: A list of conditions used to sort agreement results
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - in: query
          name: sort_descending
          description: >
            Sort agreements ascending or descending based on sort_conditions.
            Has no effect if sort_conditions is not specified.
          schema:
            type: boolean
          style: form
        - in: query
          name: limit
          description: Maximum number of agreements to return
          schema:
            type: integer
            default: 10
          style: form
        - in: query
          name: offset
          description: Number of agreements to skip before returning results
          schema:
            type: integer
            default: 0
          style: form

      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      oneOf:
                        - $ref: "#/components/schemas/AgreementResponse"
                        - $ref: "#/components/schemas/ContractAgreementResponse"
                        - $ref: "#/components/schemas/GrantAgreementResponse"
                        - $ref: "#/components/schemas/DirectAgreementResponse"
                        - $ref: "#/components/schemas/IaaAgreementResponse"
                        - $ref: "#/components/schemas/AaAgreementResponse"
                  count:
                    type: integer
                    description: Total number of agreements matching the query
                  limit:
                    type: integer
                    description: Maximum number of agreements returned
                  offset:
                    type: integer
                    description: Number of agreements skipped
                  totals:
                    type: object
                    description: Aggregate totals across all matching agreements
                    properties:
                      count:
                        type: integer
                        description: Total count of agreements
                      obligated:
                        type: number
                        format: float
                        description: Total obligated amount
                      fees:
                        type: number
                        format: float
                        description: Total fees
                      in_draft:
                        type: number
                        format: float
                        description: Total in draft status
                      planned:
                        type: number
                        format: float
                        description: Total planned amount
                      executing:
                        type: number
                        format: float
                        description: Total executing amount
                required:
                  - data
                  - count
                  - limit
                  - offset
                  - totals
        "400":
          description: Bad Request
        "500":
          description: Internal Server Error
    post:
      tags:
        - Agreements
      operationId: Create Agreement
      summary: Create a new agreement with optional nested entities
      description: |
        Create a new agreement with optional budget line items and services components
        in a single atomic operation. All operations are performed within a single
        database transaction - if any part fails, the entire operation is rolled back.

        ## Nested Entity Creation

        You can create the following entities atomically:
        - Agreement (required)
        - Budget Line Items (optional array)
        - Services Components (optional array)

        ## Budget Line Item to Services Component Linking

        Budget line items can reference services components in two ways:
        1. `services_component_id`: Reference an existing services component by database ID
        2. `services_component_ref`: Reference a services component being created in the
           same request by its `ref` field value

        ## Services Component References

        - Each services component can have a `ref` field (string) for identification
        - Budget line items reference these using `services_component_ref`
        - If no `ref` is provided, the array index (as a string) is used: "0", "1", etc.

        ## Backward Compatibility

        Omitting `budget_line_items` and `services_components` creates an agreement
        without nested entities, maintaining full backward compatibility.

        ## Error Handling

        - Returns 400 for validation errors (e.g., invalid `services_component_ref`)
        - Returns 404 for missing references (e.g., invalid `can_id`)
        - On error, all changes are rolled back (no partial data created)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/AgreementData"
                - $ref: "#/components/schemas/ContractAgreementData"
                - $ref: "#/components/schemas/GrantAgreementData"
                - $ref: "#/components/schemas/DirectAgreementData"
                - $ref: "#/components/schemas/IaaAgreementData"
                - $ref: "#/components/schemas/AaAgreementData"
            examples:
              "0":
                $ref: "#/components/examples/simple_agreement"
              "1":
                $ref: "#/components/examples/with_budget_line_items"
              "2":
                $ref: "#/components/examples/full_atomic_creation"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - id
                  - budget_line_items_created
                  - services_components_created
                properties:
                  message:
                    type: string
                    description: |
                      Human-readable success message. Examples:
                      - "Agreement created"
                      - "Agreement created with 2 budget line items"
                      - "Agreement created with 3 services components"
                      - "Agreement created with 2 budget line items and 3 services components"
                  id:
                    type: integer
                    description: ID of the created agreement
                  budget_line_items_created:
                    type: integer
                    description: Number of budget line items created (0 if none)
                  services_components_created:
                    type: integer
                    description: Number of services components created (0 if none)
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "404":
          description: Not Found
        "500":
          description: Internal Server Error

  /agreements/{id}:
    get:
      tags:
        - Agreements
      operationId: Get Agreement
      description: Get a specific agreement by ID with fiscal year context
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: Agreement ID
        - in: query
          name: fiscal_year
          schema:
            type: integer
          description: |
            Fiscal year for budget calculations and fiscal year-specific data.
            If not provided, defaults to the current fiscal year.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/AgreementResponse"
                  - $ref: "#/components/schemas/ContractAgreementResponse"
                  - $ref: "#/components/schemas/GrantAgreementResponse"
                  - $ref: "#/components/schemas/DirectAgreementResponse"
                  - $ref: "#/components/schemas/IaaAgreementResponse"
                  - $ref: "#/components/schemas/AaAgreementResponse"
        "400":
          description: Bad Request - Invalid fiscal_year parameter
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
    put:
      tags:
        - Agreements
      operationId: Update Agreement (Full)
      description: |
        Fully replace an existing agreement. All fields must be provided.
        Budget line items and services components cannot be included in update requests.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: Agreement ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/AgreementData"
                - $ref: "#/components/schemas/ContractAgreementData"
                - $ref: "#/components/schemas/GrantAgreementData"
                - $ref: "#/components/schemas/DirectAgreementData"
                - $ref: "#/components/schemas/IaaAgreementData"
                - $ref: "#/components/schemas/AaAgreementData"
      responses:
        "200":
          description: Agreement updated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - id
                properties:
                  message:
                    type: string
                    example: "Agreement updated"
                  id:
                    type: integer
                    description: ID of the updated agreement
        "400":
          description: |
            Bad Request - This error will be returned when:
            - The request contains invalid data
            - The request attempts to modify immutable fields on an awarded agreement (fields listed in _meta.immutable_awarded_fields cannot be changed once the agreement is awarded)
            - The request includes budget_line_items or services_components (these cannot be updated via this endpoint)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Cannot update immutable field 'contract_type' on awarded agreement"
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
    patch:
      tags:
        - Agreements
      operationId: Update Agreement (Partial)
      description: |
        Partially update an existing agreement. Only provided fields are updated.
        Budget line items and services components cannot be included in update requests.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: Agreement ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/AgreementData"
                - $ref: "#/components/schemas/ContractAgreementData"
                - $ref: "#/components/schemas/GrantAgreementData"
                - $ref: "#/components/schemas/DirectAgreementData"
                - $ref: "#/components/schemas/IaaAgreementData"
                - $ref: "#/components/schemas/AaAgreementData"
      responses:
        "200":
          description: Agreement updated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - id
                properties:
                  message:
                    type: string
                    example: "Agreement updated"
                  id:
                    type: integer
                    description: ID of the updated agreement
        "400":
          description: |
            Bad Request - This error will be returned when:
            - The request contains invalid data
            - The request attempts to modify immutable fields on an awarded agreement (fields listed in _meta.immutable_awarded_fields cannot be changed once the agreement is awarded)
            - The request includes budget_line_items or services_components (these cannot be updated via this endpoint)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Cannot update immutable field 'contract_type' on awarded agreement"
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
    delete:
      tags:
        - Agreements
      operationId: Delete Agreement
      description: Delete an existing agreement
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
          description: Agreement ID
      responses:
        "200":
          description: Agreement deleted successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - id
                properties:
                  message:
                    type: string
                    example: "Agreement deleted"
                  id:
                    type: integer
                    description: ID of the deleted agreement
        "400":
          description: Bad Request - Validation error prevents deletion
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
  /agreement-agencies/:
    get:
      tags:
        - Agreements
      operationId: getAllAgreementAgencies
      summary: >
        Get a list of all the Agreement Agencies. If both Requesting and Servicing are either True or False,
        all agencies are returned.
      parameters:
        - in: query
          name: requesting
          description: Whether to include Requesting agencies in the return
          schema:
            type: boolean
        - in: query
          name: servicing
          description: Whether to include Servicing agencies in the return
          schema:
            type: boolean
        - $ref: "#/components/parameters/simulatedError"
      description: Get Agreement Agencies
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AgreementAgency"
  /agreement-agencies/{agency_id}:
    get:
      tags:
        - Agreements
      operationId: getAgreementAgencyById
      summary: Get an individual Agreement Agency
      description: Get Agreement Agency by Id
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: agency_id
          description: Agreement Agency Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgreementAgency"
        "404":
          description: The specified Agreement Agency was not found.
  /agreements/{id}/history/:
    get:
      tags:
        - Agreements
      operationId: getAgreementHistoryById
      description: Get Agreement History By Agreement Id
      parameters:
        - in: path
          name: id
          description: Agreement Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
          example: 10
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          example: 0
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgreementHistory"
        "404":
          description: Not Found
  /agreements-filters/:
    get:
      tags:
        - Agreements
      operationId: getAgreementsFilterOptions
      summary: Get filter options for agreements
      description: |
        Returns available filter options from all agreements in the database.
        This endpoint provides distinct values for filtering agreements, including
        fiscal years, portfolios, project titles, agreement types, agreement names,
        contract numbers, and research types.

        The endpoint supports the `only_my` parameter to limit results to agreements
        associated with the current user (as team member, project officer, portfolio leader, etc.).
      parameters:
        - in: query
          name: only_my
          description: |
            When true, only returns filter options from agreements associated with the current user.
            User association includes: team member, project officer, portfolio team leader,
            division director, or users with BUDGET_TEAM/SYSTEM_OWNER roles.
          schema:
            type: boolean
            default: false
          style: form
      responses:
        "200":
          description: Successfully retrieved agreement filter options
          content:
            application/json:
              schema:
                type: object
                required:
                  - fiscal_years
                  - portfolios
                  - project_titles
                  - agreement_types
                  - agreement_names
                  - contract_numbers
                  - research_types
                properties:
                  fiscal_years:
                    type: array
                    items:
                      type: integer
                    description: List of fiscal years from budget line items (sorted descending)
                    example: [2025, 2024, 2023]
                  portfolios:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - name
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                    description: List of portfolios (sorted by name)
                    example:
                      - id: 1
                        name: "Child Care"
                      - id: 2
                        name: "Child Welfare"
                  project_titles:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - name
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                    description: List of project titles (sorted by name)
                    example:
                      - id: 100
                        name: "Project Alpha"
                      - id: 101
                        name: "Project Beta"
                  agreement_types:
                    type: array
                    items:
                      type: string
                      enum: [CONTRACT, GRANT, IAA, AA, DIRECT_OBLIGATION]
                    description: List of agreement types (sorted alphabetically)
                    example: ["AA", "CONTRACT", "GRANT"]
                  agreement_names:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - name
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                    description: List of agreement names (sorted by name)
                    example:
                      - id: 1
                        name: "Agreement 001"
                      - id: 2
                        name: "Agreement 002"
                  contract_numbers:
                    type: array
                    items:
                      type: string
                    description: List of contract numbers (only from CONTRACT and AA agreements, sorted alphabetically)
                    example: ["12345", "67890"]
                  research_types:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - name
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                    description: List of research methodologies (currently returns empty array - business logic TBD)
                    example: []
        "400":
          description: Bad Request
        "401":
          description: Unauthorized - authentication required
        "500":
          description: Internal Server Error
  /procurement-actions/:
    get:
      tags:
        - Procurement Actions
      operationId: Get Procurement Actions
      summary: Get a list of procurement actions
      description: Get a paginated list of procurement actions with optional filtering
      parameters:
        - in: query
          name: agreement_id
          description: Filter by agreement ID(s)
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - in: query
          name: budget_line_item_id
          description: Filter by budget line item ID(s)
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - in: query
          name: status
          description: Filter by procurement action status
          schema:
            type: array
            items:
              $ref: "#/components/schemas/ProcurementActionStatus"
          style: form
          explode: true
        - in: query
          name: award_type
          description: Filter by award type
          schema:
            type: array
            items:
              $ref: "#/components/schemas/AwardType"
          style: form
          explode: true
        - in: query
          name: procurement_shop_id
          description: Filter by procurement shop ID(s)
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - in: query
          name: limit
          description: Maximum number of procurement actions to return
          schema:
            type: integer
            default: 10
            max: 50
          style: form
        - in: query
          name: offset
          description: Number of procurement actions to skip before returning results
          schema:
            type: integer
            default: 0
          style: form
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProcurementActionResponse"
                  count:
                    type: integer
                    description: Total number of procurement actions matching the query
                  limit:
                    type: integer
                    description: Maximum number of procurement actions returned
                  offset:
                    type: integer
                    description: Number of procurement actions skipped
                required:
                  - data
                  - count
                  - limit
                  - offset
        "400":
          description: Bad Request
        "500":
          description: Internal Server Error
  /procurement-actions/{procurement_action_id}:
    get:
      tags:
        - Procurement Actions
      operationId: Get Procurement Action
      summary: Get a procurement action by ID
      description: Get a specific procurement action by ID
      parameters:
        - in: path
          name: procurement_action_id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcurementActionResponse"
              examples:
                "0":
                  $ref: "#/components/examples/ProcurementActionInProcess"
                "1":
                  $ref: "#/components/examples/ProcurementActionAwarded"
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
  /procurement-trackers/:
    get:
      tags:
        - Procurement Trackers
      operationId: Get Procurement Trackers
      summary: Get a list of procurement trackers
      description: Get a paginated list of procurement trackers with optional filtering
      parameters:
        - in: query
          name: agreement_id
          description: Filter by agreement ID(s)
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - in: query
          name: limit
          description: Maximum number of procurement trackers to return
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 50
          style: form
        - in: query
          name: offset
          description: Number of procurement trackers to skip before returning results
          schema:
            type: integer
            default: 0
            minimum: 0
          style: form
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProcurementTrackerResponse"
                  count:
                    type: integer
                    description: Total number of procurement trackers matching the query
                  limit:
                    type: integer
                    description: Maximum number of procurement trackers returned
                  offset:
                    type: integer
                    description: Number of procurement trackers skipped
                required:
                  - data
                  - count
                  - limit
                  - offset
              examples:
                "0":
                  $ref: "#/components/examples/ProcurementTrackersList"
        "400":
          description: Bad Request
        "500":
          description: Internal Server Error
  /procurement-trackers/{id}:
    get:
      tags:
        - Procurement Trackers
      operationId: Get Procurement Tracker
      summary: Get a procurement tracker by ID
      description: Get a specific procurement tracker by ID with its associated steps
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcurementTrackerResponse"
              examples:
                InProgress:
                  $ref: "#/components/examples/ProcurementTracker"
                NewlyInitialized:
                  $ref: "#/components/examples/ProcurementTrackerNewlyInitialized"
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
  /procurement-tracker-steps/:
    get:
      tags:
        - Procurement Tracker Steps
      operationId: Get Procurement Tracker Steps
      summary: Get a list of procurement tracker steps
      description: >-
        Get a paginated list of procurement tracker steps with optional
        filtering by agreement ID
      parameters:
        - in: query
          name: agreement_id
          description: Filter by agreement ID
          schema:
            type: integer
          style: form
        - in: query
          name: limit
          description: Maximum number of procurement tracker steps to return
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 50
          style: form
        - in: query
          name: offset
          description: Number of procurement tracker steps to skip before returning results
          schema:
            type: integer
            default: 0
            minimum: 0
          style: form
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      anyOf:
                        - $ref: "#/components/schemas/ProcurementTrackerStep"
                        - $ref: "#/components/schemas/ProcurementTrackerAcquisitionPlanningStep"
                    description: >-
                      Array of workflow steps. ACQUISITION_PLANNING steps
                      include additional fields (task_completed_by,
                      date_completed, notes).
                  count:
                    type: integer
                    description: >-
                      Total number of procurement tracker steps matching
                      the query
                  limit:
                    type: integer
                    description: >-
                      Maximum number of procurement tracker steps returned
                  offset:
                    type: integer
                    description: >-
                      Number of procurement tracker steps skipped
                required:
                  - data
                  - count
                  - limit
                  - offset
        "400":
          description: Bad Request
        "500":
          description: Internal Server Error
  /procurement-tracker-steps/pending-approvals/:
    get:
      tags:
        - Procurement Tracker Steps
      operationId: Get Pending Pre-Award Approvals
      summary: Get pending pre-award approval requests for the current user
      description: >-
        List pending pre-award approval requests that require review by the current user.
        Returns steps where the user has permission to approve (Division Director, Budget Team, or System Owner).
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ProcurementTrackerPreAwardStep"
              examples:
                "0":
                  summary: List of pending pre-award approvals
                  value:
                    - id: 25
                      procurement_tracker_id: 5
                      procurement_tracker:
                        id: 5
                        agreement_id: 13
                        agreement:
                          id: 13
                          name: "Contract #13"
                          display_name: "Contract #13"
                      step_number: 5
                      step_type: "PRE_AWARD"
                      status: "IN_PROGRESS"
                      step_start_date: "2026-04-05"
                      step_completed_date: null
                      approval_requested: true
                      approval_requested_date: "2026-04-05"
                      approval_requested_by: 42
                      requestor_notes: "Urgent approval needed for Q2 budget execution"
                      approval_status: "PENDING"
                      approval_responded_by: null
                      approval_responded_date: null
                      reviewer_notes: null
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
  /procurement-tracker-steps/{id}:
    get:
      tags:
        - Procurement Tracker Steps
      operationId: Get Procurement Tracker Step
      summary: Get a procurement tracker step by ID
      description: Get a specific procurement tracker step by ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/ProcurementTrackerStep"
                  - $ref: "#/components/schemas/ProcurementTrackerAcquisitionPlanningStep"
                  - $ref: "#/components/schemas/ProcurementTrackerPreSolicitationStep"
                  - $ref: "#/components/schemas/ProcurementTrackerSolicitationStep"
                  - $ref: "#/components/schemas/ProcurementTrackerEvaluationStep"
                  - $ref: "#/components/schemas/ProcurementTrackerPreAwardStep"
                description: >-
                  Procurement tracker step. ACQUISITION_PLANNING steps
                  include additional fields (task_completed_by,
                  date_completed, notes). PRE_SOLICITATION steps include
                  additional fields (target_completion_date,
                  task_completed_by, date_completed, notes,
                  draft_solicitation_date). PRE_AWARD steps include additional
                  fields (target_completion_date, task_completed_by,
                  date_completed, notes, approval_requested,
                  approval_requested_date, approval_requested_by,
                  requestor_notes, approval_status, approval_responded_by,
                  approval_responded_date, reviewer_notes).
              examples:
                "0":
                  $ref: "#/components/examples/ProcurementTrackerStepExample"
                "1":
                  $ref: "#/components/examples/ProcurementTrackerAcquisitionPlanningStepExample"
                "2":
                  $ref: "#/components/examples/ProcurementTrackerPreSolicitationStepExample"
                "3":
                  $ref: "#/components/examples/ProcurementTrackerSolicitationStepExample"
                "4":
                  $ref: "#/components/examples/ProcurementTrackerPreAwardStepExample"
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
    patch:
      tags:
        - Procurement Tracker Steps
      operationId: Update Procurement Tracker Step
      summary: Update a procurement tracker step
      description: >-
        Update specific fields of a procurement tracker step. All fields
        are optional. For ACQUISITION_PLANNING steps, additional fields
        (task_completed_by, date_completed, notes) can be updated. For
        PRE_SOLICITATION steps, additional fields
        (target_completion_date, task_completed_by, date_completed,
        notes, draft_solicitation_date) can be updated. For PRE_AWARD
        steps, additional fields (approval_status, reviewer_notes) can
        be updated by approvers.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProcurementTrackerStepRequest"
            examples:
              "0":
                summary: Update step status and dates
                value:
                  status: "COMPLETED"
              "1":
                $ref: "#/components/examples/UpdateProcurementTrackerStepAcquisitionPlanningRequest"
              "2":
                $ref: "#/components/examples/UpdateProcurementTrackerStepPreSolicitationRequest"
              "3":
                $ref: "#/components/examples/UpdateProcurementTrackerStepSolicitationRequest"
              "4":
                $ref: "#/components/examples/UpdateProcurementTrackerStepPreAwardRequest"
      responses:
        "200":
          description: Procurement tracker step updated successfully
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/ProcurementTrackerStep"
                  - $ref: "#/components/schemas/ProcurementTrackerAcquisitionPlanningStep"
                  - $ref: "#/components/schemas/ProcurementTrackerPreSolicitationStep"
                  - $ref: "#/components/schemas/ProcurementTrackerSolicitationStep"
                  - $ref: "#/components/schemas/ProcurementTrackerEvaluationStep"
                  - $ref: "#/components/schemas/ProcurementTrackerPreAwardStep"
                description: >-
                  Updated procurement tracker step. ACQUISITION_PLANNING
                  steps include additional fields (task_completed_by,
                  date_completed, notes). PRE_SOLICITATION steps include
                  additional fields (target_completion_date,
                  task_completed_by, date_completed, notes,
                  draft_solicitation_date). PRE_AWARD steps include additional
                  fields (approval_status, approval_responded_by,
                  approval_responded_date, reviewer_notes).
              examples:
                "0":
                  $ref: "#/components/examples/ProcurementTrackerStepExample"
                "1":
                  $ref: "#/components/examples/ProcurementTrackerAcquisitionPlanningStepExample"
                "2":
                  $ref: "#/components/examples/ProcurementTrackerPreSolicitationStepExample"
                "3":
                  $ref: "#/components/examples/ProcurementTrackerSolicitationStepExample"
                "4":
                  $ref: "#/components/examples/ProcurementTrackerPreAwardStepExample"
        "400":
          description: Bad Request
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
  /cans/:
    get:
      tags:
        - CANs
      operationId: getAllCANs
      summary: Get a paginated list of CANs with optional filtering and sorting
      parameters:
        - in: query
          name: limit
          description: Maximum number of CANs to return per page (1-50)
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
          style: form
        - in: query
          name: offset
          description: Number of CANs to skip (for pagination)
          schema:
            type: integer
            minimum: 0
            default: 0
          style: form
        - in: query
          name: search
          description: Search terms to filter CANs
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - in: query
          name: fiscal_year
          description: Filter by fiscal year(s) for funding_budget info
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - in: query
          name: sort_conditions
          description: List of fields to sort by (e.g., number, fiscal_year)
          schema:
            type: array
            items:
              type: string
              enum: [number, fiscal_year, portfolio, active_period, obligate_by]
          style: form
          explode: true
        - in: query
          name: sort_descending
          description: >
            Sort in descending order. Corresponds to each sort_condition.
            If not specified, defaults to ascending.
          schema:
            type: array
            items:
              type: boolean
          style: form
          explode: true
        - in: query
          name: active_period
          description: Filter by active period (fiscal year)
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - in: query
          name: transfer
          description: Filter by method of transfer
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - in: query
          name: portfolio
          description: Filter by portfolio abbreviation
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - in: query
          name: portfolio_id
          description: Filter by portfolio ID
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - in: query
          name: can_ids
          description: Filter by specific CAN IDs
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
        - in: query
          name: budget_min
          description: Filter CANs with budget greater than or equal to this amount
          schema:
            type: array
            items:
              type: number
              format: float
          style: form
          explode: true
        - in: query
          name: budget_max
          description: Filter CANs with budget less than or equal to this amount
          schema:
            type: array
            items:
              type: number
              format: float
          style: form
          explode: true
        - $ref: "#/components/parameters/simulatedError"
      description: Get a paginated list of CANs with optional filtering and sorting
      responses:
        "200":
          description: Successfully retrieved paginated list of CANs
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - limit
                  - offset
                properties:
                  data:
                    type: array
                    description: Array of CAN objects
                    items:
                      $ref: "#/components/schemas/CANList"
                  count:
                    type: integer
                    description: Total number of CANs matching the filter criteria
                    example: 42
                  limit:
                    type: integer
                    description: Maximum number of results returned in this page
                    example: 10
                  offset:
                    type: integer
                    description: Number of results skipped
                    example: 0
    post:
      tags:
        - CANs
      operationId: createCAN
      summary: Create a new CAN object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdateCANRequestSchema"
            examples:
              "0":
                $ref: "#/components/examples/CreateUpdateCANRequestSchema"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CAN"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.

  /cans/{can_id}:
    get:
      tags:
        - CANs
      summary: Get an individual CAN
      operationId: getCANById
      description: Get CAN by Id
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_id
          description: CAN Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CAN"
              example:
                "0":
                  $ref: "#/components/examples/CAN"
    patch:
      tags:
        - CANs
      summary: Update an existing CAN with the provided fields
      operationId: patchCan
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_id
          description: Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdateCANRequestSchema"
            examples:
              "0":
                $ref: "#/components/examples/CreateUpdateCANRequestSchema"
      responses:
        "200":
          description: CAN Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CAN"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.
        "404":
          description: CAN not found
    put:
      tags:
        - CANs
      summary: Update an existing CAN
      operationId: putCan
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_id
          description: Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdateCANRequestSchema"
            examples:
              "0":
                $ref: "#/components/examples/CreateUpdateCANRequestSchema"
      responses:
        "200":
          description: CAN Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CAN"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.
        "404":
          description: CAN not found
    delete:
      tags:
        - CANs
      operationId: deleteCan
      summary: Delete a Common Accounting Number (CAN)
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_id
          description: Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized

  /cans-filters/:
    get:
      tags:
        - CANs
      operationId: getCanFilterOptions
      summary: Get filter options for the CAN list
      description: |
        Returns available filter options for the CAN list page, computed via SQL aggregation.
        Includes distinct portfolios, CAN numbers, and FY budget min/max range.
        This is more efficient than fetching all CANs and computing options client-side.
      parameters:
        - in: query
          name: fiscal_year
          description: Filter budget range by fiscal year
          schema:
            type: integer
          style: form
      responses:
        "200":
          description: Successfully retrieved CAN filter options
          content:
            application/json:
              schema:
                type: object
                required:
                  - portfolios
                  - can_numbers
                  - fy_budget_range
                properties:
                  portfolios:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - name
                        - abbreviation
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        abbreviation:
                          type: string
                    description: List of portfolios associated with CANs (sorted by name)
                    example:
                      - id: 1
                        name: "Child Care"
                        abbreviation: "CC"
                      - id: 2
                        name: "Child Welfare"
                        abbreviation: "CW"
                  can_numbers:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - number
                      properties:
                        id:
                          type: integer
                        number:
                          type: string
                    description: List of CAN numbers (sorted alphabetically)
                    example:
                      - id: 500
                        number: "G99HRF2"
                      - id: 501
                        number: "G99IA14"
                  fy_budget_range:
                    type: object
                    required:
                      - min
                      - max
                    properties:
                      min:
                        type: number
                        format: float
                        description: Minimum FY budget across all CANs
                      max:
                        type: number
                        format: float
                        description: Maximum FY budget across all CANs
                    description: Min and max FY budget values for range slider
                    example:
                      min: 0
                      max: 1000000
        "400":
          description: Bad Request
        "401":
          description: Unauthorized - authentication required
        "403":
          description: Forbidden - insufficient permissions
        "500":
          description: Internal Server Error

  /can-funding-received/:
    get:
      tags:
        - CAN Funding Received
      operationId: getAllCANFundingReceived
      summary: Get a list all CANs funding received
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      description: Get CANFundingReceived
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FundingReceivedList"
    post:
      tags:
        - CANs Funding Received
      operationId: createCANFundingReceived
      summary: Create a new CANFundingReceived object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdateFundingReceived"
            examples:
              "0":
                $ref: "#/components/examples/CreateUpdateFundingReceived"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FundingReceived"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.

  /can-funding-received/{can_funding_received_id}:
    get:
      tags:
        - CAN Funding Received
      summary: Get an individual CANFundingReceived
      operationId: getCANFundingReceivedById
      description: Get CANFundingReceived by Id
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_funding_received_id
          description: CAN Funding Received Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FundingReceived"
              example:
                "0":
                  $ref: "#/components/examples/FundingReceived"
        "404":
          description: The specified CANFundingReceived was not found.
    patch:
      tags:
        - CAN Funding Received
      summary: Update an existing CANFundingReceived with the provided fields
      operationId: patchCANFundingReceived
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_funding_received_id
          description: CAN Funding Received Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdateFundingReceived"
            examples:
              "0":
                $ref: "#/components/examples/CreateUpdateFundingReceived"
      responses:
        "200":
          description: CANFundingReceivedUpdated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FundingReceived"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.
        "404":
          description: CANFundingReceived not found
    put:
      tags:
        - CAN Funding Received
      summary: Update an existing CANFundingReceived
      operationId: putCanFundingReceived
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_funding_received_id
          description: CAN Funding Received Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdateFundingReceived"
            examples:
              "0":
                $ref: "#/components/examples/CreateUpdateFundingReceived"
      responses:
        "200":
          description: CAN Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FundingReceived"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.
        "404":
          description: CAN not found
    delete:
      tags:
        - CAN Funding Received
      operationId: deleteCanFundingReceived
      summary: Delete a CANFundingReceived
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_funding_received_id
          description: CANFundingReceived ID
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "404":
          description: Unable to find specified CANFundingReceived

  /can-funding-details/:
    get:
      tags:
        - CAN Funding Details
      operationId: getAllCANFundingDetails
      summary: Get a list all CANs funding details objects
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      description: Get CANFundingDetails
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FundingDetailsList"
    post:
      tags:
        - CAN Funding Details
      operationId: createCANFundingDetails
      summary: Create a new CANFundingDetails object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdateFundingDetails"
            examples:
              "0":
                $ref: "#/components/examples/CreateUpdateFundingDetails"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FundingDetails"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.

  /can-funding-details/{can_funding_details_id}:
    get:
      tags:
        - CAN Funding Details
      summary: Get an individual CANFundingDetails
      operationId: getCANFundingDetailsById
      description: Get CANFundingDetails by Id
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_funding_details_id
          description: CAN Funding Details Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FundingDetails"
        "404":
          description: The specified CANFundingDetails was not found.
    patch:
      tags:
        - CAN Funding Details
      summary: Update an existing CANFundingDetails with the provided fields
      operationId: patchCANFundingDetails
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_funding_details_id
          description: CAN Funding Details Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdateFundingDetails"
            examples:
              "0":
                $ref: "#/components/examples/CreateUpdateFundingDetails"
      responses:
        "200":
          description: CANFundingDetails Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FundingDetails"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.
        "404":
          description: CANFundingDetails not found
    put:
      tags:
        - CAN Funding Details
      summary: Update an existing CANFundingDetails
      operationId: putCanFundingDetails
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_funding_details_id
          description: CAN Funding Details Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdateFundingDetails"
            examples:
              "0":
                $ref: "#/components/examples/CreateUpdateFundingDetails"
      responses:
        "200":
          description: CAN Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FundingDetails"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.
        "404":
          description: CAN not found
    delete:
      tags:
        - CAN Funding Details
      operationId: deleteCanFundingDetails
      summary: Delete a CANFundingDetails
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_funding_details_id
          description: CANFundingDetails ID
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "404":
          description: Unable to find specified CANFundingDetails

  /can-funding-budgets/:
    get:
      tags:
        - CAN Funding Budgets
      operationId: getAllCANFundingBudgets
      summary: Get a list of all the CAN funding budgets
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      description: Get CANFundingBudgets
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FundingBudgetList"
    post:
      tags:
        - CAN Funding Budgets
      operationId: createCANFundingBudget
      summary: Create a new CANFundingBudget object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdateCANFundingBudgetRequest"
            examples:
              "0":
                $ref: "#/components/examples/CreateUpdateCANFundingBudgetRequest"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FundingBudget"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.
        "403":
          description: Forbidden
        "404":
          description: CAN not found

  /can-funding-budgets/{can_funding_budget_id}:
    get:
      tags:
        - CAN Funding Budgets
      summary: Get an individual CANFundingBudget
      operationId: getCANFundingBudgetById
      description: Get CANFundingBudget by Id
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_funding_budget_id
          description: CAN Funding Budget Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FundingBudget"
              example:
                "0":
                  $ref: "#/components/examples/FundingBudget"
        "404":
          description: The specified CANFundingBudget was not found.
    patch:
      tags:
        - CAN Funding Budgets
      summary: Update an existing CANFundingBudget with the provided fields
      operationId: patchCanFundingBudget
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_funding_budget_id
          description: CAN Funding Budget Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdateCANFundingBudgetRequest"
            examples:
              "0":
                $ref: "#/components/examples/CreateUpdateCANFundingBudgetRequest"
      responses:
        "200":
          description: CANFundingBudget Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FundingBudget"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.
        "404":
          description: CANFundingBudget not found
    put:
      tags:
        - CAN Funding Budgets
      summary: Update an existing CANFundingBudget
      operationId: putCanFundingBudget
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_funding_budget_id
          description: CAN Funding Budget Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdateCANFundingBudgetRequest"
            examples:
              "0":
                $ref: "#/components/examples/CreateUpdateCANFundingBudgetRequest"
      responses:
        "200":
          description: CAN Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FundingBudget"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.
        "404":
          description: CAN not found
    delete:
      tags:
        - CAN Funding Budgets
      operationId: deleteCanFundingBudget
      summary: Delete a CANFundingBudget
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: can_funding_budget_id
          description: CANFundingBudget ID
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "404":
          description: Unable to find specified CANFundingBudget

  /cans/{id}/history/:
    get:
      tags:
        - CAN History
      operationId: getAllCANHistory
      summary: Get a list all CAN history objects, sorted by their timestamps from newest to oldest
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: CAN Id
          required: true
          schema:
            type: integer
          example: 1
        - name: offset
          in: query
          schema:
            type: integer
          example: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
          example: 10
        - name: fiscal_year
          in: query
          schema:
            type: integer
          example: 2025
        - name: sort_asc
          in: query
          description: Optional parameter that sets whether to sort the results in ascending (oldest to newest) order
          schema:
            type: boolean
          example: true
      description: Get CANHistory
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CANHistoryList"
        "401":
          description: Insufficient Privileges to use this endpoint.
        "403":
          description: Forbidden

  /cans/{id}/funding/:
    get:
      tags:
        - CANs
      operationId: getCanFunding
      summary: Get funding summary for a single CAN
      description: Returns funding totals, funding breakdown by fiscal year, and CAN metadata. When no fiscal_year is provided, returns data across all fiscal years.
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: CAN Id
          required: true
          schema:
            type: integer
          example: 500
        - name: fiscal_year
          in: query
          description: Fiscal year to filter funding data (optional, returns all FY data when omitted)
          schema:
            type: integer
          example: 2023
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  fiscal_year:
                    type: integer
                    nullable: true
                  funding:
                    $ref: "#/components/schemas/CANFundingAmounts"
                  funding_by_fiscal_year:
                    type: array
                    items:
                      type: object
                      properties:
                        fiscal_year:
                          type: integer
                        amount:
                          type: number
                          format: float
                  can:
                    $ref: "#/components/schemas/CANFundingDetail"
        "404":
          description: CAN not found

  /cans/funding/:
    get:
      tags:
        - CANs
      operationId: getCansFundingAggregate
      summary: Get aggregated funding summary across all CANs
      description: Returns aggregated funding totals and per-CAN detail for all CANs matching the optional filters.
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - name: fiscal_year
          in: query
          description: Fiscal year to filter funding data (optional)
          schema:
            type: integer
          example: 2023
        - name: active_period
          in: query
          description: List of active periods to filter by (optional)
          schema:
            type: array
            items:
              type: integer
          example: [1, 5]
        - name: transfer
          in: query
          description: List of CAN method of transfer values to filter by (optional)
          schema:
            type: array
            items:
              type: string
              enum:
                - DIRECT
                - COST_SHARE
                - IAA
                - IDDA
                - OTHER
          example: ["DIRECT", "IAA"]
        - name: portfolio
          in: query
          description: List of portfolio abbreviations to filter by (optional)
          schema:
            type: array
            items:
              type: string
          example: ["HS", "HMRF", "CC"]
        - name: fy_budget
          in: query
          description: Min and max fiscal year budget range (exactly 2 values)
          schema:
            type: array
            items:
              type: number
            minItems: 2
            maxItems: 2
          example: [50000, 100000]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  fiscal_year:
                    type: integer
                    nullable: true
                  funding:
                    $ref: "#/components/schemas/CANFundingAmounts"
                  cans:
                    type: array
                    items:
                      $ref: "#/components/schemas/CANFundingDetail"
        "400":
          description: Invalid filter parameter (e.g. invalid transfer value or fy_budget length)

  /portfolios/:
    get:
      tags:
        - Portfolios
      summary: Get all Portfolios
      operationId: getAllPortfolios
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: query
          name: project_id
          required: false
          schema:
            type: integer
            format: int32
          description: Filter portfolios by project ID. Returns only portfolios associated with the given project through the Agreement → BudgetLineItem → CAN chain.
      description: Get Portfolios
      responses:
        "200":
          description: OK

  /portfolios/{portfolio_id}:
    get:
      tags:
        - Portfolios
      operationId: getPortfolioById
      description: Get Portfolio by Id
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: portfolio_id
          description: portfolio Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Portfolio"
              examples:
                "0":
                  $ref: "#/components/examples/Portfolio"

  /portfolios-url/:
    get:
      tags:
        - Portfolio Url
      summary: Get all Portfolio URLs
      operationId: getAllPortfolioUrls
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      description: Get Portfolio URLs
      responses:
        "200":
          description: OK
    post:
      tags:
        - Portfolio Url
      operationId: createPortfolioUrl
      summary: Create a new PortfolioUrl object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUpdatePortfolioUrl"
            examples:
              "0":
                $ref: "#/components/examples/CreateUpdatePortfolioUrl"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateUpdatePortfolioUrl"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.
  /portfolios-url/{portfolio_url_id}:
    get:
      tags:
        - Portfolio Url
      operationId: getPortfolioUrlById
      description: Get PortfolioUrl by Id
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: portfolio_url_id
          description: Portfolio Url Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PortfolioUrl"
              examples:
                "0":
                  $ref: "#/components/examples/PortfolioUrl"
    patch:
      tags:
        - Portfolio Url
      summary: Update an existing PortfolioUrl with the provided fields
      operationId: patchPortfolioUrl
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: portfolio_url_id
          description: Portfolio Url Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PortfolioUrl"
            examples:
              "0":
                $ref: "#/components/examples/PortfolioUrl"
      responses:
        "200":
          description: PortfolioUrlUpdated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PortfolioUrl"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.
        "404":
          description: PortfolioUrl not found
    put:
      tags:
        - Portfolio Url
      summary: Update an existing PortfolioUrl with the provided fields
      operationId: putPortfolioUrl
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: portfolio_url_id
          description: Portfolio Url Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PortfolioUrl"
            examples:
              "0":
                $ref: "#/components/examples/PortfolioUrl"
      responses:
        "200":
          description: PortfolioUrlUpdated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PortfolioUrl"
        "400":
          description: Bad Request
        "401":
          description: Insufficient Privileges to use this endpoint.
        "404":
          description: PortfolioUrl not found
    delete:
      tags:
        - Portfolio Url
      operationId: PortfolioUrlReceived
      summary: Delete a PortfolioUrl
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: portfolio_url_id
          description: Portfolio Url Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "404":
          description: Unable to find specified PortfolioUrl
  /portfolios/{portfolio_id}/cans/:
    get:
      tags:
        - Portfolios
      operationId: getCansByPortfolioId
      description: Get CANs associated with a Portfolio
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - name: year
          in: query
          schema:
            type: string
          example: "2023"
        - name: budgetFiscalYear
          in: query
          schema:
            type: string
          example: "2023"
        - name: includeInactive
          in: query
          description: |
              Include inactive CANs in the results.
              Only applies when budgetFiscalYear is provided.
              When false (default), only returns CANs with an active period that includes the budget fiscal year.
          schema:
            type: boolean
            default: false
          example: false
        - in: path
          name: portfolio_id
          description: portfolio Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                properties: {}
                items:
                  type: string
              examples:
                "0":
                  value: |
                    [
                      {
                        "appropriation_date": "01/10/2023",
                        "appropriation_term": 1,
                        "arrangement_type_id": 3,
                        "authorizer_id": 26,
                        "description": "Incoming Interagency Agreements",
                        "expiration_date": "01/09/2024",
                        "id": 2,
                        "managing_portfolio_id": 1,
                        "managing_project_id": null,
                        "nickname": "IAA-Incoming",
                        "number": "G99IA14",
                        "purpose": ""
                      },
                      {
                        "appropriation_date": "01/10/2022",
                        "appropriation_term": 1,
                        "arrangement_type_id": 4,
                        "authorizer_id": 26,
                        "description": "Child Development Research Fellowship Grant Program",
                        "expiration_date": "01/09/2023",
                        "id": 4,
                        "managing_portfolio_id": 1,
                        "managing_project_id": 1,
                        "nickname": "ASPE SRCD-IDDA",
                        "number": "G990136",
                        "purpose": ""
                      }
                    ]
  /portfolio-funding-summary/:
    get:
      tags:
        - Portfolio Funding Summary
      summary: Get funding summary for multiple portfolios with optional filters
      operationId: getPortfolioFundingSummaryBatch
      description: Retrieve funding summaries for all portfolios or a filtered subset based on fiscal year, portfolio IDs, budget range, and available budget percentage.
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - name: fiscal_year
          in: query
          description: Fiscal year for which the funding summary is requested
          schema:
            type: integer
            example: 2026
        - name: portfolio_ids
          in: query
          description: List of portfolio IDs to filter by (optional)
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          example: [1, 2, 3]
        - name: budget_min
          in: query
          description: Minimum budget amount to filter by (optional)
          schema:
            type: number
            format: float
          example: 1000000
        - name: budget_max
          in: query
          description: Maximum budget amount to filter by (optional)
          schema:
            type: number
            format: float
          example: 50000000
        - name: available_pct
          in: query
          description: |
            Available budget percentage ranges to filter by (optional).
            Valid values: over90, 75-90, 50-75, 25-50, under25
          schema:
            type: array
            items:
              type: string
              enum:
                - over90
                - 75-90
                - 50-75
                - 25-50
                - under25
          style: form
          explode: true
          example: ["over90", "75-90"]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolios:
                    type: array
                    items:
                      allOf:
                        - type: object
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                            abbreviation:
                              type: string
                            division_id:
                              type: integer
                            division:
                              type: object
                              properties:
                                id:
                                  type: integer
                                name:
                                  type: string
                                abbreviation:
                                  type: string
                        - $ref: "#/components/schemas/PortfolioFundingSummary"
              example:
                portfolios:
                  - id: 1
                    name: "Child Care Research"
                    abbreviation: "CCR"
                    division_id: 1
                    division:
                      id: 1
                      name: "Division of Child and Family Development"
                      abbreviation: "DCFD"
                    total_funding:
                      amount: 10000000.00
                      percent: "Total"
                    carry_forward_funding:
                      amount: 2000000.00
                      percent: "Carry-Forward"
                    draft_funding:
                      amount: 500000.00
                      percent: "5"
                    planned_funding:
                      amount: 3000000.00
                      percent: "30"
                    obligated_funding:
                      amount: 4000000.00
                      percent: "40"
                    in_execution_funding:
                      amount: 1000000.00
                      percent: "10"
                    available_funding:
                      amount: 1500000.00
                      percent: "15"
                    new_funding:
                      amount: 8000000.00
                      percent: "New"
        "400":
          description: Bad Request - Invalid parameters
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
  /portfolio-funding-summary/{portfolio_id}:
    get:
      tags:
        - Portfolio Funding Summary
      summary: Get the funding summary for a specific portfolio
      operationId: getPortfolioFundingSummary
      description: Retrieve the funding summary for a given portfolio by its ID.
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: portfolio_id
          description: Portfolio ID
          required: true
          schema:
            type: integer
            format: int32
        - name: fiscal_year
          in: query
          description: Fiscal year for which the funding summary is requested
          schema:
            type: integer
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PortfolioFundingSummary"
              example:
                value:
                  total_funding:
                    amount: 1000000.00
                    percent: "Total"
                  carry_forward_funding:
                    amount: 200000.00
                    percent: "Carry-Forward"
                  draft_funding:
                    amount: 50000.00
                    percent: "5"
                  planned_funding:
                    amount: 300000.00
                    percent: "30"
                  obligated_funding:
                    amount: 400000.00
                    percent: "40"
                  in_execution_funding:
                    amount: 100000.00
                    percent: "10"
                  available_funding:
                    amount: 150000.00
                    percent: "15"
                  new_funding:
                    amount: 800000.00
                    percent: "New"
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "404":
          description: Portfolio not found
        "500":
          description: Internal Server Error
  /users/:
    get:
      tags:
        - Users
      operationId: getAllUsers
      description: Get all Users
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - name: oidc_id
          in: query
          schema:
            type: string
          example: e5711101-bc3e-41e5-a6a2-051874b307ca
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
              examples:
                "example_1":
                  summary: Single user
                  value:
                    - id: 5
                      oidc_id: "e5711101-bc3e-41e5-a6a2-051874b307ca"
                      status: "active"
                      hhs_id: "234232"
                      email: "tdonaworth+dev@flexion.us"
                      first_name: "Tim"
                      last_name: "Donaworth"
                      full_name: "(no name) (no name)"
                      division: 3
                      roles:
                        - id: 10
                          name: "Tech Lead"
                          is_superuser: false
                      display_name: "Tim Donaworth"
                      is_superuser: false
                      created_by: 520
                      updated_by: 521
                      created_on: "2023-04-06T20:33:38.292475"
                      updated_on: "2023-05-06T10:05:21.292565"
                "example_2":
                  summary: Multiple users
                  value:
                    - id: 1
                      oidc_id: "00000000-0000-1111-a111-000000000001"
                      status: "active"
                      hhs_id: "123456"
                      email: "emily.ball@example.com"
                      first_name: "Emily"
                      last_name: "Ball"
                      full_name: "(no name) (no name)"
                      division: 1
                      roles:
                        - id: 1
                          name: "COR"
                          is_superuser: false
                        - id : 3
                          name: "SUPER USER"
                          is_superuser: true
                      display_name: "Emily Ball"
                      is_superuser: true
                      created_by: 100
                      updated_by: 101
                      created_on: "2023-04-06T20:33:38.292475"
                      updated_on: null
                    - id: 2
                      oidc_id: "00000000-0000-1111-a111-000000000002"
                      status: "active"
                      hhs_id: "123457"
                      email: "Bethanne.Barnes@example.com"
                      first_name: "Bethanne"
                      last_name: "Barnes"
                      full_name: "Bethanne Barnes"
                      division: 4
                      roles:
                        - id: 2
                          name: "Division Director"
                          is_superuser: false
                      display_name: "Bethanne Barnes"
                      is_superuser: false
                      created_by: 100
                      updated_by: 101
                      created_on: "2023-04-06T20:33:38.292475"
                      updated_on: null
  /users/{user_id}:
    get:
      tags:
        - Users
      operationId: getUserById
      description: Get User by Id
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: user_id
          description: User Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 0
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              examples:
                "0":
                  $ref: "#/components/examples/User"
  /login/:
    servers:
      - url: https://localhost:8080/auth
        description: Auth API Localhost
      - url: https://dev.ops.opre.acf.gov/auth
        description: Auth Development Server (Live)
      - url: https://stg.ops.opre.acf.gov/auth
        description: Auth Staging Server (Live)
      - url: https://ops.opre.acf.gov/auth
        description: Auth Production Server (Live)
    post:
      tags:
        - Authentication
      operationId: login
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      description: Authenticate a user via an external provider (fakeauth, logingov, or hhsams)
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
            examples:
              login:
                value:
                  code: "authentication_code_from_provider"
                  provider: "fakeauth"
        required: true
      responses:
        "200":
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginResponse"
        "400":
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginErrorResponse"
        "500":
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

  /projects/:
    get:
      tags:
        - Projects
      operationId: getProjects
      description: Get Projects with optional filtering and pagination
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - name: fiscal_year
          in: query
          description: Filter projects by fiscal year (can specify multiple, OR logic)
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          example: [2023, 2024]
        - name: portfolio_id
          in: query
          description: Filter projects by portfolio ID (can specify multiple, OR logic)
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          example: [1, 5]
        - name: project_search
          in: query
          description: Filter by exact project title or short_title (can specify multiple values, OR logic - matches if any value equals the title or short_title)
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          example: ["HSS", "RFH", "Human Services Interoperability Support"]
        - name: agreement_search
          in: query
          description: Filter by exact agreement name or nickname (can specify multiple values, OR logic - matches projects that have agreements with exactly matching names or nicknames)
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          example: ["Contract #1: African American Child and Family Research Center", "Grant Beta"]
        - name: project_type
          in: query
          description: Filter projects by type (can specify multiple, OR logic)
          schema:
            type: array
            items:
              type: string
              enum: [RESEARCH, ADMINISTRATIVE_AND_SUPPORT]
          style: form
          explode: true
          example: [RESEARCH]
        - name: limit
          in: query
          description: Maximum number of projects to return (1-50, default 10)
          schema:
            type: array
            items:
              type: integer
              minimum: 1
              maximum: 50
              default: 10
          style: form
          explode: true
          example: [10]
        - name: offset
          in: query
          description: Number of projects to skip (default 0)
          schema:
            type: array
            items:
              type: integer
              minimum: 0
              default: 0
          style: form
          explode: true
          example: [0]
        - name: sort_field
          in: query
          description: Field to sort projects by
          schema:
            type: array
            items:
              type: string
              enum: [TITLE, PROJECT_TYPE, PROJECT_START, PROJECT_END, FY_TOTAL, PROJECT_TOTAL]
          style: form
          explode: true
          example: [TITLE]
        - name: sort_descending
          in: query
          description: Sort order - true for descending, false for ascending
          schema:
            type: array
            items:
              type: boolean
          style: form
          explode: true
          example: [false]
        - name: sort_fiscal_year
          in: query
          description: Fiscal year to use when sorting by FY_TOTAL (required when sort_field includes FY_TOTAL)
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          example: [2023]
      responses:
        "200":
          description: OK - Returns paginated list of projects with metadata
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - count
                  - limit
                  - offset
                  - summary
                properties:
                  data:
                    type: array
                    items:
                      oneOf:
                        - $ref: "#/components/schemas/ResearchProjectListItem"
                        - $ref: "#/components/schemas/ProjectListItem"
                      discriminator:
                        propertyName: project_type
                  count:
                    type: integer
                    description: Total number of projects matching the filter criteria (before pagination)
                    example: 42
                  limit:
                    type: integer
                    description: Maximum number of projects returned in this response
                    example: 10
                  offset:
                    type: integer
                    description: Number of projects skipped
                    example: 0
                  summary:
                    type: object
                    description: Aggregated summary data computed over the full filtered result set (ignoring pagination)
                    required:
                      - total_projects
                      - projects_by_type
                      - amounts_by_type
                    properties:
                      total_projects:
                        type: integer
                        description: Total number of projects matching the filter criteria
                        example: 20
                      projects_by_type:
                        type: object
                        description: Count of projects grouped by project type. Always includes both RESEARCH and ADMINISTRATIVE_AND_SUPPORT keys (0 if none match).
                        additionalProperties:
                          type: integer
                        example:
                          RESEARCH: 15
                          ADMINISTRATIVE_AND_SUPPORT: 5
                      amounts_by_type:
                        type: object
                        description: >
                          Total amounts and percentages grouped by project type. Always includes both
                          RESEARCH and ADMINISTRATIVE_AND_SUPPORT keys (0 if none match). When a specific
                          fiscal year is selected, contains FY-specific totals. When no fiscal year is
                          selected (FY = All), contains lifetime totals.
                        additionalProperties:
                          type: object
                          required:
                            - amount
                            - percent
                          properties:
                            amount:
                              type: number
                              format: float
                              description: Total amount for this project type
                            percent:
                              type: number
                              format: float
                              description: Percentage of total amount across all project types
                        example:
                          RESEARCH:
                            amount: 7000000.00
                            percent: 70.0
                          ADMINISTRATIVE_AND_SUPPORT:
                            amount: 3000000.00
                            percent: 30.0
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
    post:
      tags:
        - Projects
      operationId: createProject
      summary: Create a new Project (Research or Administrative/Support)
      description: |
        Create a new project of any type. The project_type field determines whether
        a Research Project or Administrative/Support Project is created.

        - For Research projects: all fields including origination_date are supported
        - For Administrative/Support projects: origination_date is ignored if provided
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResearchProjectRequest"
            examples:
              research_project:
                summary: Research Project Example
                value:
                  project_type: RESEARCH
                  title: "Child Welfare Research Initiative"
                  short_title: "CWRI"
                  description: "Research on child welfare outcomes"
                  url: "https://example.com"
                  origination_date: "2023-01-01"
                  team_leaders:
                    - id: 500
                      full_name: "Jane Smith"
                      email: "jane.smith@example.com"
              admin_project:
                summary: Administrative Project Example
                value:
                  project_type: ADMINISTRATIVE_AND_SUPPORT
                  title: "IT Infrastructure Support"
                  short_title: "IT-INFRA"
                  description: "Infrastructure support project"
                  team_leaders:
                    - id: 501
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The ID of the newly created project
                    example: 1001
        "400":
          description: Bad Request - Invalid input or validation error
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
  /projects/{id}:
    get:
      tags:
        - Projects
      operationId: getProjectById
      description: Get a Project by ID (supports both Research and Administrative/Support projects)
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Project ID
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ResearchProject"
                  - $ref: "#/components/schemas/Project"
                description: Returns ResearchProject schema for research projects, or Project schema for administrative/support projects
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "404":
          description: Not Found
    patch:
      tags:
        - Projects
      operationId: updateProject
      summary: Update an existing Project
      description: |
        Update a Project by ID. The project_type field cannot be changed.
        Only the fields provided in the request body will be updated.
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Project ID
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResearchProjectRequest"
            examples:
              update_title:
                summary: Update Project Title
                value:
                  title: "Updated Project Title"
              update_team_leaders:
                summary: Update Team Leaders
                value:
                  team_leaders:
                    - id: 500
                    - id: 501
      responses:
        "200":
          description: OK - Project updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: The ID of the updated project
                    example: 1
        "400":
          description: Bad Request - Invalid input or validation error
        "401":
          description: Unauthorized
        "404":
          description: Not Found - Project does not exist
        "500":
          description: Internal Server Error

  /projects/{id}/funding/:
    get:
      tags:
        - Projects
      operationId: getProjectFunding
      description: Get funding summary for a project by ID
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Project ID
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
        - in: query
          name: fiscal_year
          description: Fiscal year for funding summary (defaults to current fiscal year if not provided)
          required: false
          schema:
            type: integer
            format: int32
            example: 2025
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectFunding"
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "404":
          description: Not Found

  /projects/{id}/spending/:
    get:
      tags:
        - Projects
      operationId: getProjectSpending
      summary: Get spending metadata for a project
      description: |
        Returns project spending metadata including:
        - Total spending across all agreements
        - Spending totals by fiscal year
        - Spending breakdown by type (contract, grant, partner, direct_obligation) per fiscal year
        - Agreements grouped by fiscal year

        Only includes non-DRAFT budget line items (or OBE items regardless of status).
        Totals include both BLI amounts and fees.
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Project ID
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            example: 1002
      responses:
        "200":
          description: OK - Successfully retrieved project spending metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectSpendingMetadata"
              example:
                total: "150000.00"
                total_by_fiscal_year:
                  "2023": "50000.00"
                  "2024": "75000.00"
                  "2025": "25000.00"
                spending_type_by_fiscal_year:
                  "2023":
                    contract: "30000.00"
                    grant: "20000.00"
                    partner: "0.00"
                    direct_obligation: "0.00"
                  "2024":
                    contract: "75000.00"
                    grant: "0.00"
                    partner: "0.00"
                    direct_obligation: "0.00"
                agreements_by_fy:
                  "2023": [1, 2]
                  "2024": [1]
                  "2025": [2]
        "401":
          description: Unauthorized
        "404":
          description: Not Found - Project does not exist

  /projects-filters/:
    get:
      tags:
        - Projects
      operationId: getProjectsFilterOptions
      summary: Get filter options for projects
      description: |
        Returns available filter options from all projects in the database.
        This endpoint provides distinct values for filtering projects, including
        fiscal years, portfolios, project titles, project types, and agreement names.

        Uses database-level aggregation with DISTINCT queries for efficiency,
        even with thousands of projects and related records.
      responses:
        "200":
          description: Successfully retrieved project filter options
          content:
            application/json:
              schema:
                type: object
                required:
                  - fiscal_years
                  - portfolios
                  - project_titles
                  - project_types
                  - agreement_names
                properties:
                  fiscal_years:
                    type: array
                    items:
                      type: integer
                    description: List of fiscal years from budget line items associated with projects (sorted descending)
                    example: [2025, 2024, 2023]
                  portfolios:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - name
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                    description: List of portfolios linked to projects via CANs and budget line items (sorted by name)
                    example:
                      - id: 1
                        name: "Child Care"
                      - id: 2
                        name: "Child Welfare"
                  project_titles:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - name
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                    description: List of project titles (sorted by name)
                    example:
                      - id: 100
                        name: "Child Welfare Research Initiative"
                      - id: 101
                        name: "IT Infrastructure Support"
                  project_types:
                    type: array
                    items:
                      type: string
                      enum: [RESEARCH, ADMINISTRATIVE_AND_SUPPORT]
                    description: List of project types (sorted alphabetically)
                    example: ["ADMINISTRATIVE_AND_SUPPORT", "RESEARCH"]
                  agreement_names:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - name
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                    description: List of agreement names and nicknames associated with projects (sorted alphabetically by name, no duplicates)
                    example:
                      - id: 1
                        name: "Agreement 001"
                      - id: 2
                        name: "Contract Alpha"
                      - id: 3
                        name: "Grant Beta"
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error

  /reporting-summary/:
    get:
      tags:
        - Reporting Summary
      summary: Get consolidated reporting summary
      operationId: getReportingSummary
      description: >
        Retrieve a consolidated reporting summary for the reporting page including spending
        by agreement type and counts of projects, agreements, and budget lines for a given fiscal year.
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - name: fiscal_year
          in: query
          description: Fiscal year for which the summary is requested. Defaults to the current fiscal year if not provided.
          schema:
            type: integer
            example: 2025
        - name: portfolio_ids
          in: query
          description: Filter results to only include data from budget line items associated with the specified portfolio IDs.
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  spending:
                    type: object
                    properties:
                      total_spending:
                        type: number
                        format: float
                      agreement_types:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              enum: [CONTRACT, PARTNER, GRANT, DIRECT_OBLIGATION]
                            label:
                              type: string
                            total:
                              type: number
                              format: float
                            percent:
                              type: integer
                            new:
                              type: number
                              format: float
                            continuing:
                              type: number
                              format: float
                  counts:
                    type: object
                    properties:
                      projects:
                        $ref: "#/components/schemas/CountGroup"
                      agreements:
                        $ref: "#/components/schemas/CountGroup"
                      new_agreements:
                        $ref: "#/components/schemas/CountGroup"
                      continuing_agreements:
                        $ref: "#/components/schemas/CountGroup"
                      budget_lines:
                        $ref: "#/components/schemas/CountGroup"
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
  /procurement-shops/:
    get:
      tags:
        - Procurement Shops
      operationId: getAllProcurementShops
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      description: Get all Procurement Shops
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ProcurementShop"
              examples:
                "0":
                  value: [
                    {
                      "id": 1,
                      "name": "National Institutes of Health",
                      "abbr": "NIH",
                      "procurement_shop_fees": [
                        {
                          "id": 1,
                          "procurement_shop": {
                            "id": 1,
                            "name": "National Institutes of Health",
                            "abbr": "NIH",
                            "fee_percentage": 0.05
                          },
                          "fee": 0.05,
                          "start_date": "2023-01-01",
                          "end_date": "2023-12-31"
                        },
                        {
                          "id": 2,
                          "procurement_shop": {
                            "id": 1,
                            "name": "National Institutes of Health",
                            "abbr": "NIH",
                            "fee_percentage": 0.05
                          },
                          "fee": 0.06,
                          "start_date": "2024-01-01",
                          "end_date": null
                        }
                      ],
                      "fee_percentage": 0.05,
                      "current_fee": {
                        "id": 1,
                        "procurement_shop": {
                          "id": 1,
                          "name": "National Institutes of Health",
                          "abbr": "NIH",
                          "fee_percentage": 0.05
                        },
                        "fee": 0.05,
                        "start_date": "2023-01-01",
                        "end_date": "2023-12-31"
                      }
                    },
                    {
                      "id": 2,
                      "name": "General Services Administration",
                      "abbr": "GSA",
                      "procurement_shop_fees": [
                        {
                          "id": 3,
                          "procurement_shop": {
                            "id": 2,
                            "name": "General Services Administration",
                            "abbr": "GSA",
                            "fee_percentage": 0.075
                          },
                          "fee": 0.075,
                          "start_date": "2023-01-01",
                          "end_date": null
                        }
                      ],
                      "fee_percentage": 0.075,
                      "current_fee": {
                        "id": 3,
                        "procurement_shop": {
                          "id": 2,
                          "name": "General Services Administration",
                          "abbr": "GSA",
                          "fee_percentage": 0.075
                        },
                        "fee": 0.075,
                        "start_date": "2023-01-01",
                        "end_date": null
                      }
                    }
                  ]
  /procurement-shops/{id}:
    get:
      tags:
        - Procurement Shops
      operationId: getProcurementShopById
      description: Get Procurement Shop by id
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 0
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcurementShop"
              example:
                id: 1
                name: "National Institutes of Health"
                abbr: "NIH"
                procurement_shop_fees: [
                  {
                    "id": 1,
                    "procurement_shop": {
                      "id": 1,
                      "name": "National Institutes of Health",
                      "abbr": "NIH",
                      "fee_percentage": 0.05
                    },
                    "fee": 0.05,
                    "start_date": "2023-01-01",
                    "end_date": "2023-12-31"
                  },
                  {
                    "id": 2,
                    "procurement_shop": {
                      "id": 1,
                      "name": "National Institutes of Health",
                      "abbr": "NIH",
                      "fee_percentage": 0.05
                    },
                    "fee": 0.06,
                    "start_date": "2024-01-01",
                    "end_date": null
                  }
                ]
                fee_percentage: 0.05
                current_fee: {
                  "id": 1,
                  "procurement_shop": {
                    "id": 1,
                    "name": "National Institutes of Health",
                    "abbr": "NIH",
                    "fee_percentage": 0.05
                  },
                  "fee": 0.05,
                  "start_date": "2023-01-01",
                  "end_date": "2023-12-31"
                }
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
  /budget-line-items-filters/:
    get:
      tags:
        - Budget Line Items
      operationId: getBudgetLineItemsFilters
      description: Get budget line items filter options
      parameters:
        - in: query
          name: only_my
          schema:
            type: boolean
            example: true
          description: If true, only return filter options for the user's budget line items
        - in: query
          name: enable_obe
          schema:
            type: boolean
          description: If true, include OBE (Overcome by Events) status in the response
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - fiscal_years
                  - statuses
                  - portfolios
                  - budget_line_total_range
                properties:
                  fiscal_years:
                    type: array
                    items:
                      type: integer
                    description: Available fiscal years for filtering
                  statuses:
                    type: array
                    items:
                      type: string
                    description: Available budget line statuses for filtering
                  portfolios:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                    description: Available portfolios for filtering
                  budget_line_total_range:
                    type: object
                    properties:
                      min:
                        type: number
                        format: float
                      max:
                        type: number
                        format: float
                    description: The range of budget line totals (amount + fees) available in the dataset

  /budget-line-items/:
    get:
      tags:
        - Budget Line Items
      operationId: getBudgetLineItems
      description: Get a list of budget line items with optional filtering
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 50
            default: 10
          description: Maximum number of items to return
        - in: query
          name: offset
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 0
          description: Number of items to skip
        - in: query
          name: fiscal_year
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by fiscal year(s)
        - in: query
          name: budget_line_status
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          description: Filter by budget line status(es)
        - in: query
          name: portfolio
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by portfolio ID(s)
        - in: query
          name: agreement_id
          schema:
            type: array
            items:
              type: integer
          style: form
          explode: true
          description: Filter by agreement ID(s)
        - in: query
          name: budget_line_total_min
          schema:
            type: number
            format: float
          description: Filter budget lines with total (amount + fees) greater than or equal to this value
        - in: query
          name: budget_line_total_max
          schema:
            type: number
            format: float
          description: Filter budget lines with total (amount + fees) less than or equal to this value
        - in: query
          name: only_my
          schema:
            type: boolean
          description: If true, only return budget line items associated with the current user
        - in: query
          name: include_fees
          schema:
            type: boolean
          description: If true, include procurement shop fees in the totals
        - in: query
          name: sort_conditions
          schema:
            type: string
          description: Sort by the provided sort condition
        - in: query
          name: sort_descending
          schema:
            type: boolean
          description: Sort results should be returned descending or not. Ignored if sort_conditions not included
        - in: query
          name: enable_obe
          schema:
            type: boolean
          description: If true, include OBE (Overcome by Events) BLIs in the response
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/BudgetLineItemListItem"
                description: |
                  Optimized list response. Excludes team_members and portfolio_team_leaders
                  (not used in list views). CAN object is minimal (id, display_name, number, portfolio_id only).
                  Use GET /budget-line-items/{id} for full details.
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
    post:
      tags:
        - Budget Line Items
      operationId: createBudgetLineItem
      description: Create a new budget line item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BudgetLineItemRequest"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BudgetLineItem"
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error

  /budget-line-items/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
          format: int32
        description: The ID of the budget line item
    get:
      tags:
        - Budget Line Items
      operationId: getBudgetLineItem
      description: Get a budget line item by ID
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/BudgetLineItem"
                  - type: object
                    properties:
                      _meta:
                        $ref: "#/components/schemas/BudgetLineItemMeta"
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
    put:
      tags:
        - Budget Line Items
      operationId: updateBudgetLineItem
      description: Update a budget line item (full update)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BudgetLineItemRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BudgetLineItem"
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
    patch:
      tags:
        - Budget Line Items
      operationId: partialUpdateBudgetLineItem
      description: Partially update a budget line item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BudgetLineItemRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BudgetLineItem"
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
    delete:
      tags:
        - Budget Line Items
      operationId: deleteBudgetLineItem
      description: Delete a budget line item
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  id:
                    type: integer
        "401":
          description: Unauthorized
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
  /notifications/:
    get:
      tags:
        - Notifications
      operationId: getNotifications
      description: Get Notifications
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - name: user_id
          in: query
          schema:
            type: integer
          example: 1
        - name: oidc_id
          in: query
          schema:
            type: string
          example: 6dd69df5-b6ab-4f27-890a-e64dd1d7f1e6
        - name: is_read
          in: query
          schema:
            type: boolean
          example: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Notifications"
              examples:
                "0":
                  $ref: "#/components/examples/Notifications"
  /notifications/{id}:
    get:
      tags:
        - Notifications
      operationId: getNotificationById
      description: Get Notifications By Id
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Notification"
    put:
      tags:
        - Notifications
      operationId: putNotification
      summary: Update a Notification (Over-write)
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationRequest"
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
    patch:
      tags:
        - Notifications
      operationId: patchNotification
      summary: Update a Notification (Merge)
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationRequest"
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
  /services-components/:
    get:
      tags:
        - Service Components
      operationId: getServicesComponents
      description: Get Services Components
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - name: agreement_id
          in: query
          schema:
            type: integer
          example: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServicesComponents"
    post:
      tags:
        - Service Components
      operationId: createServicesComponent
      summary: Create a new Service Component
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ServicesComponentRequestPost"
      responses:
        "201":
          description: Created
        "400":
          description: Bad Request
        "500":
          description: Internal Server Error
  /services-components/{id}:
    get:
      tags:
        - Service Components
      operationId: getServicesComponentById
      description: Get Services Component by id
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServicesComponent"
    put:
      tags:
        - Service Components
      operationId: putServicesComponent
      summary: Update a Services Component (Over-write)
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ServicesComponentRequest"
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
    patch:
      tags:
        - Service Components
      operationId: patchServicesComponent
      summary: Update a Services Component (Merge)
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ServicesComponentRequest"
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
    delete:
      tags:
        - Service Components
      operationId: deleteServicesComponent
      summary: Delete a Service Component
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
  /change-requests/:
    description: ChangeRequests collection endpoint
    get:
      tags:
        - Change Requests
      operationId: getChangeRequests
      description: Get a list of change requests with pagination
      parameters:
        - name: userId
          in: query
          description: The user id to filter change requests
          schema:
            type: string
        - name: offset
          in: query
          description: The number of items to skip before starting to collect the result set
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 0
        - name: limit
          in: query
          description: The numbers of items to return
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 10
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GenericChangeRequest"
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
  /change-requests/{id}:
    patch:
      tags:
        - Change Requests
      operationId: approveOrRejectChangeRequest
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: The change request ID
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
      description: approve or reject a change request
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: "APPROVE or REJECT"
                requestor_notes:
                  description: optional notes from the requestor added the change request
                  type: string
                reviewer_notes:
                  description: optional notes from the reviewer added the change request
                  type: string
            examples:
              "0":
                value: >-
                  {"action": "APPROVE", "reviewer_notes": "Looks good to me"}
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error

  /documents/:
    get:
      tags:
        - Documents
      operationId: Get Documents
      description: Get documents by agreement id
      parameters:
        - in: query
          name: agreement_id
          description: The agreement id to filter documents
          required: true
          schema:
            type: integer
            format: int32
            minimum: 0
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                  documents:
                    type: array
                    items:
                      $ref: "#/components/schemas/Documents"
        "400":
          description: Bad Request
        "500":
          description: Internal Server Error
    post:
      tags:
        - Documents
      operationId: Create Document
      description: Create a new document
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                document_name:
                  type: string
                document_type:
                  type: string
                agreement_id:
                  type: integer
                  format: int32
                document_size:
                  type: number
              required:
                - document_name
                - document_type
                - agreement_id
                - document_size
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                  uuid:
                    type: string
        "400":
          description: Bad Request
        "500":
          description: Internal Server Error
  /documents/{document_id}:
    patch:
      tags:
        - Documents
      description: Update a document
      parameters:
        - in: path
          name: document_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                agreement_id:
                  type: integer
                  format: int32
                status:
                  type: string
              required:
                - agreement_id
                - status
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        "400":
          description: Bad Request
        "500":
          description: Internal Server Error
  /research-methodologies/:
    get:
      tags:
        - Research Methodologies
      operationId: getResearchMethodologies
      description: Get Research Methodologies
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: query
          name: limit
          schema:
            type: integer
            description: Maximum number of items to return
            minimum: 1
            maximum: 50
            default: 10
          example: 1
        - in: query
          name: offset
          schema:
            type: integer
            description: Number of items to skip
            minimum: 0
            default: 0
          example: 0
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ResearchMethodology"
  /research-methodologies/{id}:
    get:
      tags:
        - Research Methodologies
      operationId: getResearchMethodologyById
      description: Get Research Methodology by id
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResearchMethodology"
  /special-topics/:
    get:
      tags:
        - Special Topics
      operationId: getSpecialTopics
      description: Get Special Topics
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: query
          name: limit
          schema:
            type: integer
            description: Maximum number of items to return
            minimum: 1
            maximum: 50
            default: 10
          example: 1
        - in: query
          name: offset
          schema:
            type: integer
            description: Number of items to skip
            minimum: 0
            default: 0
          example: 0
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SpecialTopic"
  /special-topics/{id}:
    get:
      tags:
        - Special Topics
      operationId: getSpecialTopicById
      description: Get Special Topic by id
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Id
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SpecialTopic"
  /lookups/agreement-types/:
    get:
      tags:
        - Lookups
      operationId: getLookupAgreementTypes
      description: Get a list of all agreement type enum values
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  enum:
                    - CONTRACT
                    - GRANT
                    - DIRECT_OBLIGATION
                    - IAA
                    - AA
                example:
                  - CONTRACT
                  - GRANT
                  - DIRECT_OBLIGATION
                  - IAA
                  - AA
        "401":
          description: Unauthorized
  /lookups/agreement-reasons/:
    get:
      tags:
        - Lookups
      operationId: getLookupAgreementReasons
      description: Get a list of all agreement reason enum values
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  enum:
                    - NEW_REQ
                    - RECOMPETE
                    - LOGICAL_FOLLOW_ON
                example:
                  - NEW_REQ
                  - RECOMPETE
                  - LOGICAL_FOLLOW_ON
        "401":
          description: Unauthorized
  /lookups/research-types/:
    get:
      tags:
        - Lookups
      operationId: getLookupResearchTypes
      description: Get a mapping of research type enum names to their integer values
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: integer
                example:
                  APPLIED_RESEARCH: 1
                  EVALUATIVE_RESEARCH: 2
                  PROGRAM_SUPPORT: 3
        "401":
          description: Unauthorized
  /lookups/portfolio-status/:
    get:
      tags:
        - Lookups
      operationId: getLookupPortfolioStatuses
      description: Get a list of all portfolio status enum values
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  enum:
                    - IN_PROCESS
                    - NOT_STARTED
                    - SANDBOX
                example:
                  - IN_PROCESS
                  - NOT_STARTED
                  - SANDBOX
        "401":
          description: Unauthorized
  /lookups/portfolio-status/{id}:
    get:
      tags:
        - Lookups
      operationId: getLookupPortfolioStatusById
      description: Get a single portfolio status enum value by its integer ID
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Portfolio status enum ID
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 3
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: string
                enum:
                  - IN_PROCESS
                  - NOT_STARTED
                  - SANDBOX
                example: IN_PROCESS
        "401":
          description: Unauthorized
  /divisions/:
    get:
      tags:
        - Divisions
      operationId: getAllDivisions
      summary: Get all Divisions
      description: Get a list of all divisions
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Division"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
  /divisions/{id}:
    get:
      tags:
        - Divisions
      operationId: getDivisionById
      summary: Get a Division by ID
      description: Get a single division by its ID
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Division ID
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Division"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
  /product-service-codes/:
    get:
      tags:
        - Product Service Codes
      operationId: getAllProductServiceCodes
      summary: Get all Product Service Codes
      description: Get a list of all product service codes
      parameters:
        - $ref: "#/components/parameters/simulatedError"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ProductServiceCode"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
  /product-service-codes/{id}:
    get:
      tags:
        - Product Service Codes
      operationId: getProductServiceCodeById
      summary: Get a Product Service Code by ID
      description: Get a single product service code by its ID
      parameters:
        - $ref: "#/components/parameters/simulatedError"
        - in: path
          name: id
          description: Product Service Code ID
          required: true
          schema:
            type: integer
            format: int32
            minimum: 1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductServiceCode"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
  /health/:
    get:
      tags:
        - Infrastructure
      operationId: getHealthCheck
      summary: Health check
      description: Returns the health status of the API and its dependencies
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - OK
                      - Maybe problems
                      - BAD
                  alarm_level:
                    type: integer
                  checks:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        alarm_level:
                          type: integer
                example:
                  status: OK
                  alarm_level: 0
                  checks:
                    database:
                      alarm_level: 0
  /version/:
    get:
      tags:
        - Infrastructure
      operationId: getVersion
      summary: Get API version
      description: Returns the current API version from the OpenAPI spec
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                example:
                  version: "1.0.0"
  /azure/sas-token/:
    get:
      tags:
        - Infrastructure
      operationId: getAzureSasToken
      summary: Get Azure Blob Storage SAS token
      description: Generates a short-lived SAS token for uploading files to Azure Blob Storage
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  sas_token:
                    type: string
                example:
                  sas_token: "se=2026-03-11T10%3A00%3A00Z&sp=w&sv=2021-08-06&sr=b&sig=..."
        "401":
          description: Unauthorized
components:
  parameters:
    created_by:
      description: The user id of the user who created the object
      name: created_by
      in: query
      schema:
        type: integer
    updated_by:
      description: The user id of the user who last updated the object
      name: updated_by
      in: query
      schema:
        type: integer
    created_on:
      description: The timestamp of when the object was created
      name: created_on
      in: query
      schema:
        type: string
        format: date-time
    updated_on:
      description: The timestamp of when the object was last updated
      name: updated_on
      in: query
      schema:
        type: string
        format: date-time
    created_by_user:
      description: A minimal representation of the user who created the object
      name: created_by_user
      in: query
      schema:
        $ref: "#/components/schemas/SafeUser"
    updated_by_user:
      description: A minimal representation of the user who last updated the object
      name: updated_by_user
      in: query
      schema:
        $ref: "#/components/schemas/SafeUser"
    simulatedError:
      name: simulatedError
      in: query
      schema:
        type: integer
      example: ""
      description: >-
        Simulate an error response, set the value to either `true` to get a 500
        status code, or to a specific status code number (e.g.: `400`).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    CountGroup:
      type: object
      properties:
        total:
          type: integer
        types:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              count:
                type: integer
    CANFundingAmounts:
      type: object
      description: Funding totals for a CAN or aggregate of CANs
      properties:
        total_funding:
          type: number
          format: float
        available_funding:
          type: number
          format: float
        carry_forward_funding:
          type: number
          format: float
        new_funding:
          type: number
          format: float
        expected_funding:
          type: number
          format: float
        received_funding:
          type: number
          format: float
        planned_funding:
          type: number
          format: float
        obligated_funding:
          type: number
          format: float
        in_execution_funding:
          type: number
          format: float
        in_draft_funding:
          type: number
          format: float
    CANFundingDetail:
      type: object
      description: CAN metadata returned in funding responses
      properties:
        id:
          type: integer
        number:
          type: string
        display_name:
          type: string
          nullable: true
        nick_name:
          type: string
          nullable: true
        portfolio_id:
          type: integer
        portfolio:
          type: string
          nullable: true
        active_period:
          type: integer
          nullable: true
        appropriation_date:
          type: integer
          nullable: true
        carry_forward_label:
          type: string
          nullable: true
        expiration_date:
          type: string
          nullable: true
    BasicCAN:
      description: >-
        A simple version of the Common Accounting Number (CAN) Object.
        This object is intended to be used in the schemas nested within the CAN object.
      properties:
        active_period:
          type: integer
        funding_method:
          type: string
        funding_frequency:
          type: string
        funding_type:
          type: string
        display_name:
          type: string
        nick_name:
          type: string
        number:
          type: string
        portfolio_id:
          type: integer
        description:
          type: string
        id:
          type: integer
      required:
        - number
        - portfolio_id
        - id
    CreateUpdateCANRequestSchema:
      description: The request object for creating a new Common Accounting Number (CAN) object.
      properties:
        nick_name:
          type: string
        number:
          type: string
        description:
          type: string
        portfolio_id:
          type: integer
        funding_details_id:
          type: integer
      required:
        - number
        - portfolio_id
        - nick_name
    CAN:
      description: Common Accounting Number (CAN) Object
      type: object
      properties:
        is_expired:
          type: boolean
        active_period:
          type: integer
        funding_method:
          type: string
        funding_frequency:
          type: string
        funding_type:
          type: string
        budget_line_items:
          type: array
          items:
            $ref: "#/components/schemas/BudgetLineItem"
        description:
          type: string
        display_name:
          type: string
        funding_budgets:
          type: array
          items:
            $ref: "#/components/schemas/FundingBudget"
        funding_details:
          type: object
          items:
            $ref: "#/components/schemas/FundingDetails"
        funding_details_id:
          type: integer
        funding_received:
          type: array
          items:
            $ref: "#/components/schemas/FundingReceived"
        id:
          type: integer
        nick_name:
          type: string
        number:
          type: string
        obligate_by:
          type: integer
        portfolio:
          type: integer
        portfolio_id:
          type: integer
        projects:
          type: array
          items:
            $ref: "#/components/schemas/Project"
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"
      required:
        - id
        - portfolio_id
        - number
    CANList:
      description: Common Accounting Number (CAN) Object for List responses (simplified)
      type: object
      properties:
        is_expired:
          type: boolean
        active_period:
          type: integer
        funding_method:
          type: string
        funding_frequency:
          type: string
        funding_type:
          type: string
        budget_line_items:
          type: array
          description: Simplified budget line items with only IDs
          items:
            type: object
            properties:
              id:
                type: integer
        description:
          type: string
        display_name:
          type: string
        funding_budgets:
          type: array
          items:
            $ref: "#/components/schemas/FundingBudget"
        funding_details:
          type: object
          items:
            $ref: "#/components/schemas/FundingDetails"
        funding_details_id:
          type: integer
        funding_received:
          type: array
          items:
            $ref: "#/components/schemas/FundingReceived"
        id:
          type: integer
        nick_name:
          type: string
        number:
          type: string
        obligate_by:
          type: integer
        portfolio:
          type: integer
        portfolio_id:
          type: integer
        projects:
          type: array
          items:
            $ref: "#/components/schemas/Project"
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"
      required:
        - id
        - portfolio_id
        - number
    CANHistoryList:
      description: A list of CAN objects with their history
      type: array
      items:
        anyOf:
          - $ref: "#/components/schemas/CANHistoryItem"
    CANHistoryItem:
      description: A single CAN object with its history
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier for the history record.
          example: 2
        can_id:
          type: integer
          description: FK to the CAN object that the history record is associated with.
          example: 3
        ops_event_id:
          type: integer
          description: FK to the OPS event that triggered the history record.
          example: 4
        history_title:
          type: string
          description: The title of the history event in Markdown format.
          example: "Nickname Edited"
        history_message:
          type: string
          description: The message that describes the history event in Markdown format.
          example: "Omkar Kuber edited the nickname from 'CAN 1' to 'CAN 2'"
        timestamp:
          type: string
          description: The timestamp of when the history event was created (different than created_on).
          format: date-time
          example: "2023-09-01T00:00:00.000000Z"
        history_type:
          type: string
          enum:
            - CAN_DATA_IMPORT
            - CAN_NICKNAME_EDITED
            - CAN_DESCRIPTION_EDITED
            - CAN_FUNDING_CREATED
            - CAN_RECEIVED_CREATED
            - CAN_FUNDING_EDITED
            - CAN_RECEIVED_EDITED
            - CAN_FUNDING_DELETED
            - CAN_RECEIVED_DELETED
            - CAN_PORTFOLIO_CREATED
            - CAN_PORTFOLIO_DELETED
            - CAN_PORTFOLIO_EDITED
            - CAN_DIVISION_CREATED
            - CAN_DIVISION_DELETED
            - CAN_DIVISION_EDITED
            - CAN_CARRY_FORWARD_CALCULATED
          example: "CAN_NICKNAME_EDITED"
      required:
        - id
        - can_id
        - ops_event_id
    FundingReceived:
      description: Funding Received Object
      type: object
      properties:
        can:
          type: integer
        can_id:
          type: integer
        display_name:
          type: string
        fiscal_year:
          type: integer
        funding:
          type: number
        id:
          type: integer
        notes:
          type: string
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"
      required:
        - id
        - can_id
        - fiscal_year
    FundingReceivedList:
      description: Lightweight Funding Received Object for list endpoints (excludes expensive nested relationships)
      type: object
      properties:
        id:
          type: integer
        can_id:
          type: integer
        fiscal_year:
          type: integer
        funding:
          type: number
        notes:
          type: string
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
      required:
        - id
        - can_id
        - fiscal_year
    CreateUpdateFundingReceived:
      description: A request object for the creation or updating of a FundingReceived
      type: object
      properties:
        fiscal_year:
          type: integer
        can_id:
          type: integer
        funding:
          type: number
        notes:
          type: string
      required:
        - fiscal_year
        - can_id
        - funding
    CreateUpdateFundingDetails:
      description: A request object for the creation or updating of a FundingDetails object
      type: object
      properties:
        allotment:
          type: string
        allowance:
          type: string
        appropriation:
          description: The TAS number for the associated CAN.
          type: string
        display_name:
          type: string
        fiscal_year:
          type: integer
        fund_code:
          type: string
        funding_partner:
          type: string
        funding_source:
          type: string
          enum:
            - OPRE
            - ACF
            - ACF_MOU
            - HHS
            - OTHER
        method_of_transfer:
          type: string
          enum:
            - DIRECT
            - COST_SHARE
            - IAA
            - IDDA
            - OTHER
        sub_allowance:
          type: string
    FundingDetailsList:
      description: Lightweight Funding Details Object for list endpoints (excludes expensive nested relationships)
      type: object
      properties:
        id:
          type: integer
        fiscal_year:
          type: integer
        fund_code:
          type: string
        active_period:
          type: integer
        funding_method:
          type: string
        funding_received:
          type: string
        funding_type:
          type: string
        allotment:
          type: string
        allowance:
          type: string
        appropriation:
          description: The TAS number for the associated CAN.
          type: string
        display_name:
          type: string
        funding_partner:
          type: string
        funding_source:
          type: string
          enum:
            - OPRE
            - ACF
            - ACF_MOU
            - HHS
            - OTHER
        method_of_transfer:
          type: string
          enum:
            - DIRECT
            - COST_SHARE
            - IAA
            - IDDA
            - OTHER
        obligate_by:
          type: integer
        sub_allowance:
          type: string
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
      required:
        - id
        - fiscal_year
        - fund_code
    FundingDetails:
      description: Funding Detail Object
      type: object
      properties:
        allotment:
          type: string
        allowance:
          type: string
        appropriation:
          description: The TAS number for the associated CAN.
          type: string
        display_name:
          type: string
        fiscal_year:
          type: integer
        fund_code:
          type: string
        funding_partner:
          type: string
        funding_source:
          type: string
          enum:
            - OPRE
            - ACF
            - ACF_MOU
            - HHS
            - OTHER
        id:
          type: integer
        method_of_transfer:
          type: string
          enum:
            - DIRECT
            - COST_SHARE
            - IAA
            - IDDA
            - OTHER
        sub_allowance:
          type: string
        active_period:
          type: integer
        funding_method:
          type: string
        funding_received:
          type: string
        funding_type:
          type: string
        obligate_by:
          type: integer
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"
      required:
        - fiscal_year
        - fund_code
        - id
    CreateUpdateCANFundingBudgetRequest:
      description: A request object for the creation or updating of a FundingBudget
      type: object
      properties:
        fiscal_year:
          type: integer
        can_id:
          type: integer
        budget:
          type: number
        notes:
          type: string
      required:
        - fiscal_year
        - can_id
        - budget
    FundingBudget:
      description: Funding Budget Object
      type: object
      properties:
        budget:
          type: number
        can:
          $ref: "#/components/schemas/BasicCAN"
        can_id:
          type: integer
        display_name:
          type: string
        fiscal_year:
          type: integer
        id:
          type: integer
        notes:
          type: string
        versions:
          type: array
          items:
            $ref: "#/components/schemas/FundingBudgetVersion"
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"
      required:
        - id
        - can_id
        - fiscal_year
    FundingBudgetList:
      description: Lightweight Funding Budget Object for list endpoints (excludes expensive nested relationships)
      type: object
      properties:
        id:
          type: integer
        can_id:
          type: integer
        fiscal_year:
          type: integer
        budget:
          type: number
        notes:
          type: string
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
      required:
        - id
        - can_id
        - fiscal_year
    FundingBudgetVersion:
      description: SQLAlchemy Continuum Version for Funding Budget
      type: object
      properties:
        budget:
          type: number
        can:
          type: integer
        can_id:
          type: integer
        display_name:
          type: string
        fiscal_year:
          type: integer
        id:
          type: integer
        notes:
          type: string
        transaction_id:
          type: integer
        end_transation_id:
          type: integer
        operation_type:
          type: integer
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"
    Portfolio:
      description: Portfolio Object
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        abbreviation:
          type: string
        status:
          type: string
          enum:
            - IN_PROCESS
            - NOT_STARTED
            - SANDBOX
        cans:
          type: array
          items:
            $ref: "#/components/schemas/CAN"
        division_id:
          type: integer
        urls:
          type: array
          items:
            $ref: "#/components/schemas/PortfolioUrl"
        team_leaders:
          type: array
          items:
            $ref: "#/components/schemas/SafeUser"
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"
      required:
        - id
        - division_id
        - abbreviation
    PortfolioUrl:
      description: Used to list the URL/links associated with the Portfolio
      type: object
      properties:
        id:
          type: integer
        portfolio_id:
          type: integer
        url:
          type: string
          format: uri
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
      required:
        - id
        - portfolio_id
        - url
    CreateUpdatePortfolioUrl:
      description: A request object for the creation or updating of a PortfolioUrl
      type: object
      properties:
        portfolio_id:
          type: integer
        url:
          type: string
          format: uri
      required:
        - portfolio_id
        - url
    PortfolioFundingSummary:
      description: Portfolio funding summary
      type: object
      properties:
        total_funding:
          $ref: "#/components/schemas/FundingLineItem"
        carry_forward_funding:
          $ref: "#/components/schemas/FundingLineItem"
        draft_funding:
          $ref: "#/components/schemas/FundingLineItem"
        planned_funding:
          $ref: "#/components/schemas/FundingLineItem"
        obligated_funding:
          $ref: "#/components/schemas/FundingLineItem"
        in_execution_funding:
          $ref: "#/components/schemas/FundingLineItem"
        available_funding:
          $ref: "#/components/schemas/FundingLineItem"
        new_funding:
          $ref: "#/components/schemas/FundingLineItem"
    FundingLineItem:
      description: Portfolio funding object
      type: object
      properties:
        amount:
          type: number
        percentage:
          type: string
    User:
      description: OPRE User Object
      type: object
      properties:
        division:
          type: integer
        oidc_id:
          type: string
        full_name:
          type: string
        roles:
          $ref: "#/components/schemas/Roles"
        last_name:
          type: string
        id:
          type: integer
        first_name:
          type: string
        email:
          type: string
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
            - LOCKED
        hhs_id:
          type: string
        display_name:
          type: string
        is_superuser:
          type: boolean
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"
    SafeUser:
      description: A minimal OPRE User Object
      type: object
      properties:
        id:
          type: integer
        full_name:
          type: string
    Roles:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          enum:
            - SYSTEM_OWNER
            - BUDGET_TEAM
            - REVIEWER_APPROVER
            - USER_ADMIN
            - VIEWER_EDITOR
            - PROCUREMENT_TEAM
        is_superuser:
          type: boolean
    ProjectFunding:
      description: Funding summary for a project
      type: object
      properties:
        funding_by_portfolio:
          type: array
          items:
            type: object
            required:
              - portfolio_id
              - portfolio
              - amount
            properties:
              portfolio_id:
                type: integer
                example: 1
              portfolio:
                type: string
                example: "Child Welfare"
              amount:
                type: number
                format: double
                example: 123.456
              abbreviation:
                type: string
                nullable: true
                example: "CW"
        funding_by_can:
          type: object
          required:
            - total
            - carry_forward_funding
            - new_funding
          properties:
            total:
              type: number
              format: double
              example: 246.912
            carry_forward_funding:
              type: number
              format: double
              example: 0
            new_funding:
              type: number
              format: double
              example: 246.912
        funding_by_fiscal_year:
          type: array
          items:
            type: object
            required:
              - fiscal_year
              - amount
            properties:
              fiscal_year:
                type: integer
                example: 2024
              amount:
                type: number
                format: double
                example: 123.456
        cans:
          type: array
          items:
            $ref: "#/components/schemas/ProjectFundingCAN"
    ProjectFundingCAN:
      description: CAN funding detail within a project funding summary
      type: object
      required:
        - id
        - number
        - portfolio_id
        - portfolio
        - active_period
        - fy_funding
        - lifetime_funding
      properties:
        id:
          type: integer
          example: 1
        number:
          type: string
          example: "CAN123"
        portfolio_id:
          type: integer
          example: 1
        portfolio:
          type: string
          nullable: true
          example: "Child Welfare"
        active_period:
          type: integer
          nullable: true
          description: Active period in years
          example: 1
        fy_funding:
          type: number
          format: double
          description: Funding received in the current fiscal year
          example: 123.456
        lifetime_funding:
          type: number
          format: double
          description: Total funding over the lifetime of the CAN
          example: 123.456
    ProjectSpendingMetadata:
      description: Project spending metadata including totals and fiscal year breakdowns
      type: object
      required:
        - total
        - total_by_fiscal_year
        - spending_type_by_fiscal_year
        - agreements_by_fy
      properties:
        total:
          type: string
          description: Total spending across all agreements (Decimal as string for precision)
          example: "150000.00"
        total_by_fiscal_year:
          type: object
          description: Spending totals by fiscal year
          additionalProperties:
            type: string
            description: Decimal amount as string
          example:
            "2023": "50000.00"
            "2024": "75000.00"
            "2025": "25000.00"
        spending_type_by_fiscal_year:
          type: object
          description: Spending breakdown by type (contract, grant, partner, direct_obligation) for each fiscal year
          additionalProperties:
            $ref: "#/components/schemas/SpendingTypeBreakdown"
          example:
            "2023":
              contract: "30000.00"
              grant: "20000.00"
              partner: "0.00"
              direct_obligation: "0.00"
            "2024":
              contract: "75000.00"
              grant: "0.00"
              partner: "0.00"
              direct_obligation: "0.00"
        agreements_by_fy:
          type: object
          description: Agreement IDs grouped by fiscal year
          additionalProperties:
            type: array
            items:
              type: integer
          example:
            "2023": [1, 2]
            "2024": [1]
            "2025": [2]
    AgreementName:
      description: Agreement identifier with ID and name (nick_name preferred over title)
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          description: Agreement ID
          example: 1
        name:
          type: string
          description: Agreement name (nick_name if available, otherwise title)
          example: "Research Agreement 2023"
    SpendingTypeBreakdown:
      description: Spending amounts by agreement type for a fiscal year
      type: object
      required:
        - contract
        - grant
        - partner
        - direct_obligation
      properties:
        contract:
          type: string
          description: Contract spending (Decimal as string)
          example: "30000.00"
        grant:
          type: string
          description: Grant spending (Decimal as string)
          example: "20000.00"
        partner:
          type: string
          description: Partner agreement spending - AA and IAA (Decimal as string)
          example: "0.00"
        direct_obligation:
          type: string
          description: Direct obligation spending (Decimal as string)
          example: "0.00"
    TeamLeader:
      type: object
      properties:
        division:
          type: integer
        email:
          type: string
        first_name:
          type: string
        full_name:
          type: string
        id:
          type: integer
        last_name:
          type: string
        oidc_id:
          type: string
        role:
          type: string
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"
    ResearchProjectListItem:
      type: object
      description: Lightweight schema for list endpoint
      properties:
        id:
          type: integer
          example: 1
        title:
          type: string
          example: African American Child and Family Research Center
        short_title:
          type: string
        description:
          type: string
        url:
          type: string
          example: >-
            https://acf.gov/opre/project/african-american-child-and-family-research-center
        origination_date:
          type: string
          format: date
          example: "2022-01-01"
        created_on:
          type: string
          format: date-time
          example: "2023-04-06T20:33:38.292475Z"
        updated_on:
          type: string
          format: date-time
          example: "2023-04-06T20:33:38.292475Z"
        project_type:
          type: string
          enum: [RESEARCH, ADMINISTRATIVE_AND_SUPPORT]
          example: RESEARCH
        start_date:
          type: string
          format: date
          nullable: true
          description: Earliest period_start across all services_components in all agreements
          example: "2023-01-01"
        end_date:
          type: string
          format: date
          nullable: true
          description: Latest period_end across all services_components in all agreements
          example: "2024-12-31"
        fiscal_year_totals:
          type: object
          nullable: true
          description: Dictionary mapping fiscal year to total BLI value for that year (non-DRAFT BLIs only)
          additionalProperties:
            type: string
          example:
            "2023": "1000.00"
            "2024": "2000.00"
        project_total:
          type: string
          nullable: true
          description: Total value of all agreements in the project (sum of agreement_total for each)
          example: "3000.00"
        agreement_name_list:
          type: array
          nullable: true
          description: List of agreements associated with this project (id and name, where name prefers nick_name over title)
          items:
            type: object
            properties:
              id:
                type: integer
                description: Agreement ID
                example: 1
              name:
                type: string
                description: Agreement name (nick_name if available, otherwise title)
                example: "HSS-2023"
            required:
              - id
              - name
          example:
            - id: 1
              name: "Contract #1: African American Child and Family Research Center"
            - id: 2
              name: "HSS-2023"
      required:
        - title
    ProjectListItem:
      type: object
      description: Lightweight schema for list endpoint (Administrative/Support projects)
      properties:
        id:
          type: integer
          example: 2
        title:
          type: string
          example: IT Infrastructure Support
        short_title:
          type: string
          example: IT-INFRA
        description:
          type: string
          example: Infrastructure support project
        url:
          type: string
          nullable: true
          example: https://example.com
        created_on:
          type: string
          format: date-time
          example: "2023-04-06T20:33:38.292475Z"
        updated_on:
          type: string
          format: date-time
          example: "2023-04-06T20:33:38.292475Z"
        project_type:
          type: string
          enum: [RESEARCH, ADMINISTRATIVE_AND_SUPPORT]
          example: ADMINISTRATIVE_AND_SUPPORT
        start_date:
          type: string
          format: date
          nullable: true
          description: Earliest period_start across all services_components in all agreements
          example: "2023-01-01"
        end_date:
          type: string
          format: date
          nullable: true
          description: Latest period_end across all services_components in all agreements
          example: "2024-12-31"
        fiscal_year_totals:
          type: object
          nullable: true
          description: Dictionary mapping fiscal year to total BLI value for that year (non-DRAFT BLIs only)
          additionalProperties:
            type: string
          example:
            "2023": "1000.00"
            "2024": "2000.00"
        project_total:
          type: string
          nullable: true
          description: Total value of all agreements in the project (sum of agreement_total for each)
          example: "3000.00"
        agreement_name_list:
          type: array
          nullable: true
          description: List of agreements associated with this project (id and name, where name prefers nick_name over title)
          items:
            type: object
            properties:
              id:
                type: integer
                description: Agreement ID
                example: 1
              name:
                type: string
                description: Agreement name (nick_name if available, otherwise title)
                example: "Admin Contract 2024"
            required:
              - id
              - name
          example:
            - id: 3
              name: "IT-Support-2024"
            - id: 4
              name: "Infrastructure Contract"
      required:
        - title
    ResearchProject:
      type: object
      description: Full schema for detail endpoint - includes all relationships
      properties:
        id:
          type: integer
          example: 1
        title:
          type: string
          example: African American Child and Family Research Center
        short_title:
          type: string
        description:
          type: string
        url:
          type: string
          example: >-
            https://acf.gov/opre/project/african-american-child-and-family-research-center
        origination_date:
          type: string
          format: date
          example: "2022-01-01"
        team_leaders:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              full_name:
                type: string
              email:
                type: string
            example:
              {
                "id": 1,
                "full_name": "Chris Fortunato",
                "email": "chris.fortunato@example.com"
              }
        division_directors:
          type: array
          description: List of division directors from all agreements in the project
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: integer
              name:
                type: string
          example:
            - id: 500
              name: "Jane Smith"
            - id: 501
              name: "John Doe"
        project_officers:
          type: array
          description: List of project officers from all agreements in the project
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: integer
              name:
                type: string
          example:
            - id: 500
              name: "Jane Smith"
            - id: 501
              name: "John Doe"
        alternate_project_officers:
          type: array
          description: List of alternate project officers from all agreements in the project
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: integer
              name:
                type: string
          example:
            - id: 500
              name: "Jane Smith"
            - id: 501
              name: "John Doe"
        created_on:
          type: string
          format: date-time
          example: "2023-04-06T20:33:38.292475Z"
        updated_on:
          type: string
          format: date-time
          example: "2023-04-06T20:33:38.292475Z"
        created_by:
          type: integer
          example: 1
        project_type:
          type: string
          enum: [RESEARCH, ADMINISTRATIVE_AND_SUPPORT]
          example: RESEARCH
      required:
        - title
    ResearchProjects:
      description: OPS List of Research Projects (lightweight schema)
      type: array
      items:
        $ref: "#/components/schemas/ResearchProjectListItem"
    AgreementHistory:
      description: List of Agreement History records
      type: array
      items:
        anyOf:
          - $ref: "#/components/schemas/AgreementHistoryItem"
    AgreementHistoryItem:
      type: object
      properties:
        id:
          type: integer
          example: 2
        agreement_id:
          type: integer
          example: 3
        agreement_id_record:
          type: integer
          example: 3
        ops_event_id:
          type: integer
          example: 5
        budget_line_id:
          type: integer
          example: 1
        budget_line_id_record:
          type: integer
          example: 1
        history_title:
          type: string
          example: "Budget Line Item Added"
        history_message:
          type: string
          example: "Chris Fortunato added a new budget line item to Agreement 3"
        timestamp:
          type: string
          format: date-time
          example: "2023-09-01T00:00:00.000000Z"
        history_type:
          type: string
          enum:
            - AGREEMENT_CREATED
            - AGREEMENT_UPDATED
            - AGREEMENT_DELETED
            - BUDGET_LINE_ITEM_CREATED
            - BUDGET_LINE_ITEM_UPDATED
            - BUDGET_LINE_ITEM_DELETED
            - CHANGE_REQUEST_CREATED
            - CHANGE_REQUEST_UPDATED
            - CHANGE_REQUEST_DELETED
            - PROCUREMENT_SHOP_UPDATED
            - SERVICE_COMPONENT_CREATED
            - SERVICE_COMPONENT_UPDATED
            - SERVICE_COMPONENT_DELETED
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"

    OpsDbHistoryItem:
      type: object
      properties:
        id:
          type: integer
          example: 2
        class_name:
          type: string
          example: ContractAgreement
        row_key:
          type: string
          example: "21"
        event_details:
          description: JSON copy of the relevant object after editing or some JSON message
          type: object
        changes:
          description: JSON for the changeset
          type: object
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"

    BudgetLineItems:
      description: OPS List of Budget Line Items
      type: array
      items:
        anyOf:
          - $ref: "#/components/schemas/BudgetLineItemListItem"

    BudgetLineItemCANList:
      description: Minimal CAN schema for list responses - only fields used by UI
      type: object
      properties:
        id:
          type: integer
          example: 1
        display_name:
          type: string
        number:
          type: string
        portfolio_id:
          type: integer
          example: 1
      required:
        - id
        - display_name
        - number
        - portfolio_id

    BudgetLineItemListItem:
      description: Optimized BudgetLineItem schema for list responses (excludes unused fields)
      type: object
      properties:
        id:
          type: integer
          example: 1
        budget_line_item_type:
          type: string
          example: "CONTRACT"
        agreement_id:
          type: integer
          example: 1
        can_id:
          type: integer
          example: 1
        can:
          $ref: "#/components/schemas/BudgetLineItemCANList"
        services_component_id:
          type: integer
          nullable: true
          description: ID of the associated services component
        amount:
          type: number
          format: float
          example: 1000000
          description: BLI amount represented as a floating-point number
        total:
          type: number
          format: float
          description: Total BLI amount including fees (amount + fees)
        comments:
          type: string
        date_needed:
          type: string
          example: "2023-05-06"
        line_description:
          type: string
        proc_shop_fee_percentage:
          type: number
          example: 100.2
        procurement_shop_fee_id:
          type: integer
          description: ID reference to the procurement shop fee
        procurement_shop_fee:
          $ref: "#/components/schemas/ProcurementShopFee"
          description: The associated procurement shop fee object
        status:
          type: string
          example: PLANNED
        is_obe:
          type: boolean
          example: false
        portfolio_id:
          type: integer
          example: 1
        fiscal_year:
          type: integer
          example: 1
        in_review:
          type: boolean
          description: Whether this budget line item has change requests in review
        change_requests_in_review:
          type: array
          nullable: true
          description: BLI-level and agreement-level change requests in review (GenericChangeRequest supports both)
          items:
            $ref: "#/components/schemas/GenericChangeRequest"
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        agreement:
          $ref: "#/components/schemas/SimpleAgreementSchema"
        fees:
          type: number
          format: float
          description: BLI fee amount represented as a floating-point number
        _meta:
          $ref: "#/components/schemas/BudgetLineItemMeta"

    BudgetLineItem:
      description: |
        Full BudgetLineItem schema used for single-item responses (GET /budget-line-items/{id}).
        Includes all fields including team_members, portfolio_team_leaders, and full CAN details.
        For list responses, see BudgetLineItemListItem which excludes unused fields for performance.
      type: object
      properties:
        id:
          type: integer
          example: 1
        budget_line_item_type:
          type: string
          example: "CONTRACT"
        agreement_id:
          type: integer
          example: 1
        can_id:
          type: integer
          example: 1
        can:
          $ref: "#/components/schemas/BudgetLineItemCAN"
        services_component_id:
          type: integer
          nullable: true
          description: ID of the associated services component
        amount:
          type: number
          format: float
          example: 1000000
          description: BLI amount represented as a floating-point number
        total:
          type: number
          format: float
          description: Total BLI amount including fees (amount + fees)
        comments:
          type: string
        date_needed:
          type: string
          example: "2023-05-06"
        line_description:
          type: string
        procurement_action_id:
            type: integer
            example: 1
        proc_shop_fee_percentage:
          type: number
          example: 100.2
        procurement_shop_fee_id:
          type: integer
          description: ID reference to the procurement shop fee
        procurement_shop_fee:
          $ref: "#/components/schemas/ProcurementShopFee"
          description: The associated procurement shop fee object
        status:
          type: string
          example: PLANNED
        is_obe:
          type: boolean
          example: false
        portfolio_id:
          type: integer
          example: 1
        fiscal_year:
          type: integer
          example: 1
        team_members:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              full_name:
                type: string
              email:
                type: string
            example:
              [
                {"id": 1, "full_name": "Chris Fortunato", "email": "chris.fortunato@example.com"},
                {"id": 2, "full_name": "Amy Madigan", "email": "Amy.Madigan@example.com"},
                {
                  "id": 3,
                  "full_name": "Ivelisse Martinez-Beck",
                  "email": "Ivelisse.Martinez-Beck@example.com",
                },
              ]
        portfolio_team_leaders:
          type: array
          nullable: true
          items:
            type: object
            properties:
              id:
                type: integer
              full_name:
                type: string
              email:
                type: string
          description: Portfolio team leaders associated with this budget line item
        in_review:
          type: boolean
          description: Whether this budget line item has change requests in review
        change_requests_in_review:
          type: array
          nullable: true
          description: BLI-level and agreement-level change requests in review (GenericChangeRequest supports both)
          items:
            $ref: "#/components/schemas/GenericChangeRequest"
        clin_id:
          type: integer
          example: 1
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"
        requestor_notes:
          description: optional notes added to a Change Request when a PATCH is made that creates a CR
          type: string
          writeOnly: true
        agreement:
          $ref: "#/components/schemas/SimpleAgreementSchema"
        fees:
          type: number
          format: float
          description: BLI fee amount represented as a floating-point number

    SimpleAgreementSchema:
      type: object
      properties:
        id:
          type: integer
          example: 1
        agreement_type:
          type: string
          example: 'AgreementType.DIRECT_ALLOCATION'
        name:
          type: string
          example: 'DIRECT ALLOCATION #2: African American Child and Family Research Center'
        awarding_entity_id:
          type: integer
          example: 3
        project:
          $ref: "#/components/schemas/SimpleProjectSchema"
      required:
        - id
        - agreement_type
        - name
        - project
    SimpleProjectSchema:
      type: object
      properties:
        id:
          type: integer
          example: 1
        title:
          type: string
          example: "African American Child and Family Research Center"
      required:
        - id
        - title
    BudgetLineItemCAN:
      type: object
      properties:
        id:
          type: integer
          example: 1
        portfolio:
          $ref: "#/components/schemas/PortfolioBLISchema"
        portfolio_id:
          type: integer
          example: 1
        display_name:
          type: string
        nick_name:
          type: string
        number:
          type: string
        description:
          type: string
        active_period:
          type: integer
        funding_method:
          type: string
        funding_frequency:
          type: string
        funding_type:
          type: string
        expiration_date:
          type: integer
        appropriation_date:
          type: integer
    Division:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        abbreviation:
          type: string
        division_director_id:
          type: integer
        deputy_division_director_id:
          type: integer
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
    PortfolioBLISchema:
      type: object
      properties:
        division_id:
          type: integer
        division:
          $ref: "#/components/schemas/Division"
    BudgetLineItemRequest:
      type: object
      properties:
        agreement_id:
          type: integer
          example: 1
        amount:
          type: number
          example: 1000000
        can_id:
          type: integer
          example: 1
        comments:
          type: string
        date_needed:
          type: string
          example: "2023-05-06"
        line_description:
          type: string
        proc_shop_fee_percentage:
          type: number
          example: 100.2
        status:
          type: string
          example: PLANNED
        clin_id:
          type: integer
          example: 1
        services_component_id:
          type: integer
          example: 1
        requestor_notes:
          description: optional notes added to a Change Request when a POST is made that creates a CR
          type: string
      required:
        - agreement_id

    GenericChangeRequest:
      type: object
      properties:
        id:
          type: integer
          example: 1
        change_request_type:
          type: string
          example: "BUDGET_LINE_ITEM_CHANGE_REQUEST"
        status:
          type: string
          example: "IN_REVIEW"
        requested_change_data:
          description: JSON for the request changes
          type: object
        requested_change_diff:
          description: JSON for the request changes with new and old values at request time
          type: object
        requestor_notes:
          description: notes from the requestor (aka submitter notes)
          type: string
        created_by:
          $ref: "#/components/parameters/created_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        created_on:
          $ref: "#/components/parameters/created_on"
        reviewed_by:
          type: integer
        reviewed_on:
          type: string
          format: date-time
        reviewer_notes:
          type: string
        updated_by:
          $ref: "#/components/parameters/updated_by"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        agreement_id:
          type: integer
          example: 1
        budget_line_item_id:
          type: integer
          nullable: true
          description: Present for BUDGET_LINE_ITEM_CHANGE_REQUEST; null for AGREEMENT_CHANGE_REQUEST
          example: 1
        has_budget_change:
          type: boolean
          example: true
        has_status_change:
          type: boolean
          example: false
        has_proc_shop_change:
          type: boolean
          example: false
          description: Present for AGREEMENT_CHANGE_REQUEST; false for BLI-only change requests

    AgreementChangeRequest:
      allOf:
        - $ref: "#/components/schemas/GenericChangeRequest"
        - type: object
          properties:
            has_proc_shop_change:
              type: boolean

      AgreementChangeRequests:
        type: array
        items:
          $ref: "#/components/schemas/AgreementChangeRequest"
        description: List of Agreement Change Requests

    ResearchProjectRequest:
      type: object
      properties:
        project_type:
          type: string
          enum: [RESEARCH, ADMINISTRATIVE_AND_SUPPORT]
          example: RESEARCH
        title:
          type: string
          example: "Research Project #1"
        short_title:
          type: string
          example: RP#1
        description:
          type: string
          example: "Description #1"
        url:
          type: string
          example: https://example.com
        origination_date:
          type: string
          format: date
          example: "2023-05-06"
        team_leaders:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              full_name:
                type: string
              email:
                type: string
          example:
            - id: 1
              full_name: "Chris Fortunato"
              email: "chris.fortunato@example.com"
      required:
        - title
    Notifications:
      description: OPS List of Notifications
      type: array
      items:
        anyOf:
          - $ref: "#/components/schemas/Notification"
    Notification:
      type: object
      properties:
        id:
          type: integer
          example: 1
        notification_type:
          type: string
          example: "CHANGE_REQUEST_NOTIFICATION"
        title:
          type: string
          example: "Notification #1"
        is_read:
          type: boolean
          example: true
        message:
          type: string
          example: "Message #1"
        expires:
          type: string
          example: "2023-04-06"
        change_request:
          $ref: "#/components/schemas/GenericChangeRequest"
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"
    NotificationRequest:
      type: object
      properties:
        is_read:
          type: boolean
          example: true
        title:
          type: string
          example: "Notification #1"
        message:
          type: string
          example: "Message #1"
        recipient_id:
          type: integer
          example: 1
    ServicesComponents:
      description: OPS List of Services Components
      type: array
      items:
        anyOf:
          - $ref: "#/components/schemas/ServicesComponent"
    ServicesComponent:
      type: object
      properties:
        id:
          type: integer
          example: 1
        agreement_id:
          type: integer
          example: 1
        number:
          type: integer
          example: 1
        optional:
          type: boolean
          example: false
        sub_component:
          type: string
          example: SC1.1
        description:
          type: string
        display_title:
          type: string
        display_name:
          type: string
        period_start:
          type: string
          example: "2023-05-06"
        period_end:
          type: string
          example: "2023-06-30"
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
        created_by_user:
          $ref: "#/components/parameters/created_by_user"
        updated_by_user:
          $ref: "#/components/parameters/updated_by_user"
    ServicesComponentRequest:
      type: object
      properties:
        agreement_id:
          type: integer
          example: 1
        number:
          type: integer
          example: 1
        optional:
          type: boolean
          example: false
        description:
          type: string
        display_title:
          type: string
        display_name:
          type: string
        clin_id:
          type: integer
          example: 1
        period_start:
          type: string
          example: "2023-05-06"
        period_end:
          type: string
          example: "2023-06-30"
      required:
        - contract_agreement_id
        - number
        - optional
    ServicesComponentRequestPost:
      allOf:
        - $ref: "#/components/schemas/ServicesComponentRequest"
    ProcurementShop:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        abbr:
          type: string
        procurement_shop_fees:
          type: array
          items:
            $ref: "#/components/schemas/ProcurementShopFee"
        fee_percentage:
          type: number
          format: float
          description: The currently active fee percentage as a decimal (e.g., 0.05 for 5%)
        current_fee:
          $ref: "#/components/schemas/ProcurementShopFee"
          nullable: true
          description: The currently active fee object, or null if no fee is active
        created_on:
          type: string
          format: date-time
          readOnly: true
        updated_on:
          type: string
          format: date-time
          readOnly: true
        created_by:
          type: integer
          readOnly: true
        updated_by:
          type: integer
          readOnly: true
      required:
        - id
        - name
        - abbr
        - procurement_shop_fees
        - fee_percentage
    ProcurementShopFee:
      type: object
      properties:
        id:
          type: integer
        procurement_shop_id:
          type: integer
        procurement_shop:
          $ref: "#/components/schemas/ProcurementShop"
        fee:
          type: number
          format: float
          description: The fee percentage as a decimal (e.g., 0.05 for 5%)
        start_date:
          type: string
          format: date
          nullable: true
          description: Start date when this fee becomes active
        end_date:
          type: string
          format: date
          nullable: true
          description: End date when this fee expires (null for indefinite)
        created_on:
          type: string
          format: date-time
          readOnly: true
        updated_on:
          type: string
          format: date-time
          readOnly: true
        created_by:
          type: integer
          readOnly: true
        updated_by:
          type: integer
          readOnly: true
      required:
        - id
        - procurement_shop_id
        - procurement_shop
        - fee

    ProcurementShopFeeRequest:
      type: object
      properties:
        procurement_shop_id:
          type: integer
          description: ID of the procurement shop this fee applies to
        fee:
          type: number
          format: float
          description: The fee percentage as a decimal (e.g., 0.05 for 5%)
        start_date:
          type: string
          format: date
          description: Start date when this fee becomes active
        end_date:
          type: string
          format: date
          nullable: true
          description: End date when this fee expires (null for indefinite)
      required:
        - procurement_shop_id
        - fee
        - start_date
    AwardType:
      type: string
      enum:
        - NEW_AWARD
        - MODIFICATION
        - NEW_TASK_ORDER
        - EXERCISE_OPTION_AS_IS
        - FOLLOW_ON
        - SIMPLIFIED_ACQUISITION
        - MICRO_PURCHASE
        - ADMINISTRATIVE
      description: Type of award for the procurement action
    ModType:
      type: string
      enum:
        - NEW
        - ADMIN
        - AMOUNT_TBD
        - AS_IS
        - REPLACEMENT_AMOUNT_FINAL
      description: Type of modification for the procurement action
    ProcurementActionStatus:
      type: string
      enum:
        - PLANNED
        - REQUISITION_SUBMITTED
        - IN_PROCESS
        - AWARDED
        - CERTIFIED
        - CANCELLED
      description: Status of the procurement action
    RequisitionType:
      type: string
      enum:
        - INITIAL
        - FINAL
      description: Type of requisition (Initial or Final submission)
    Requisition:
      type: object
      properties:
        id:
          type: integer
        procurement_action_id:
          type: integer
          nullable: true
        type:
          $ref: "#/components/schemas/RequisitionType"
          nullable: true
        zero_number:
          type: string
          nullable: true
          description: Initial requisition number
        zero_date:
          type: string
          format: date
          nullable: true
          description: Initial requisition date
        number:
          type: string
          nullable: true
          description: Final requisition number
        date:
          type: string
          format: date
          nullable: true
          description: Final requisition date
        group:
          type: integer
          nullable: true
          description: >-
            Requisition group number for grouping related budget lines
        check:
          type: string
          nullable: true
        created_on:
          type: string
          format: date-time
        updated_on:
          type: string
          format: date-time
        created_by:
          type: integer
        updated_by:
          type: integer
      required:
        - id
    AgreementMod:
      type: object
      description: Agreement modification details
      properties:
        id:
          type: integer
        agreement_id:
          type: integer
        mod_type:
          allOf:
            - $ref: "#/components/schemas/ModType"
          nullable: true
        number:
          type: string
          nullable: true
          description: Modification number
        mod_date:
          type: string
          format: date
          nullable: true
          description: Date of the modification
      required:
        - id
        - agreement_id
    ProcurementActionResponse:
      type: object
      properties:
        id:
          type: integer
        agreement_id:
          type: integer
        agreement:
          allOf:
            - $ref: "#/components/schemas/BasicAgreement"
          nullable: true
        agreement_mod_id:
          type: integer
          nullable: true
        agreement_mod:
          allOf:
            - $ref: "#/components/schemas/AgreementMod"
          nullable: true
          description: Nested agreement modification details
        award_type:
          allOf:
            - $ref: "#/components/schemas/AwardType"
          nullable: true
        mod_type:
          allOf:
            - $ref: "#/components/schemas/ModType"
          nullable: true
        status:
          allOf:
            - $ref: "#/components/schemas/ProcurementActionStatus"
          nullable: true
        procurement_shop_id:
          type: integer
          nullable: true
        procurement_shop:
          allOf:
            - $ref: "#/components/schemas/ProcurementShop"
          nullable: true
          description: Nested procurement shop details
        psc_action_number:
          type: string
          nullable: true
        need_by_date:
          type: string
          format: date
          nullable: true
        requisition_deadline:
          type: string
          format: date
          nullable: true
          description: Deadline for requisition submission
        date_awarded_obligated:
          type: string
          format: date
          nullable: true
          description: Date when the procurement action was awarded/obligated
        desired_days_on_street:
          type: integer
          nullable: true
          description: Desired number of days for solicitation to be on the street
        action_description:
          type: string
          nullable: true
        comments:
          type: string
          nullable: true
        psc_fee_percentage:
          type: string
          nullable: true
          description: PSC fee percentage as decimal string
        award_total:
          type: string
          nullable: true
          description: Official award amount for this procurement action (decimal as string)
        agreement_total:
          type: string
          nullable: true
          description: Cumulative agreement total after this action (decimal as string)
        display_name:
          type: string
          description: Computed display name showing action type and agreement
        mod_number:
          type: string
          nullable: true
          description: Modification number if this is a modification
        is_modification:
          type: boolean
          description: Whether this procurement action is for a modification
        budget_lines_total:
          type: string
          description: Sum of budget line amounts (decimal as string)
        totals_match:
          type: boolean
          description: Whether award_total matches budget_lines_total
        budget_line_items:
          type: array
          items:
            $ref: "#/components/schemas/BudgetLineItem"
          nullable: true
          description: Budget line items associated with this procurement action
        requisitions:
          type: array
          items:
            $ref: "#/components/schemas/Requisition"
          nullable: true
          description: >-
            Requisitions associated with this procurement action
            (tracks workflow from Initial to Final)
        created_by:
          type: integer
          nullable: true
        updated_by:
          type: integer
          nullable: true
        created_on:
          type: string
          format: date-time
          nullable: true
        updated_on:
          type: string
          format: date-time
          nullable: true
      required:
        - id
        - agreement_id
        - display_name
        - is_modification
        - budget_lines_total
        - totals_match
    BasicAgreement:
      type: object
      description: A simplified version of Agreement for nested responses
      properties:
        id:
          type: integer
        name:
          type: string
        display_name:
          type: string
          description: Computed display name for the agreement
        agreement_type:
          type: string
      required:
        - id
        - name
        - display_name
    ProcurementTrackerStatus:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
        - COMPLETED
      description: Status of the procurement tracker
    ProcurementTrackerType:
      type: string
      enum:
        - DEFAULT
      description: Type of procurement tracker workflow
    ProcurementTrackerStepType:
      type: string
      enum:
        - ACQUISITION_PLANNING
        - PRE_SOLICITATION
        - SOLICITATION
        - EVALUATION
        - PRE_AWARD
        - AWARD
      description: Type of procurement workflow step
    ProcurementTrackerStepStatus:
      type: string
      enum:
        - PENDING
        - ACTIVE
        - COMPLETED
        - SKIPPED
      description: Status of an individual tracker step
    ProcurementTrackerStep:
      type: object
      description: Base procurement tracker step with common fields for all step types
      properties:
        id:
          type: integer
          description: Unique identifier for the step
        procurement_tracker_id:
          type: integer
          description: ID of the procurement tracker this step belongs to
        step_number:
          type: integer
          description: Sequential order of this step in the workflow
        step_type:
          $ref: "#/components/schemas/ProcurementTrackerStepType"
        status:
          $ref: "#/components/schemas/ProcurementTrackerStepStatus"
        step_start_date:
          type: string
          format: date
          nullable: true
          description: Date when this step was started
        step_completed_date:
          type: string
          format: date
          nullable: true
          description: Date when this step was completed
      required:
        - id
        - procurement_tracker_id
        - step_number
        - step_type
        - status
    ProcurementTrackerAcquisitionPlanningStep:
      allOf:
        - $ref: "#/components/schemas/ProcurementTrackerStep"
        - type: object
          description: Acquisition Planning step with additional fields
          properties:
            task_completed_by:
              type: integer
              nullable: true
              description: User ID of the person who completed this step
            date_completed:
              type: string
              format: date
              nullable: true
              description: >-
                Date when this step was completed. Must be current date
                or past date.
            notes:
              type: string
              nullable: true
              description: Additional notes about this step
    ProcurementTrackerPreSolicitationStep:
      allOf:
        - $ref: "#/components/schemas/ProcurementTrackerStep"
        - type: object
          description: Pre-Solicitation step with additional fields
          properties:
            target_completion_date:
              type: string
              format: date
              nullable: true
              description: >-
                Target date for completing pre-solicitation activities.
                Must be current date or future date.
            task_completed_by:
              type: integer
              nullable: true
              description: User ID of the person who completed this step
            date_completed:
              type: string
              format: date
              nullable: true
              description: >-
                Date when this step was completed. Must be current date
                or past date.
            notes:
              type: string
              nullable: true
              description: Additional notes about this step
            draft_solicitation_date:
              type: string
              format: date
              nullable: true
              description: >-
                Date when the draft solicitation was completed. Must be
                current date or future date.
    ProcurementTrackerSolicitationStep:
      allOf:
        - $ref: "#/components/schemas/ProcurementTrackerStep"
        - type: object
          description: Solicitation step with additional fields
          properties:
            task_completed_by:
              type: [integer, "null"]
              description: User ID of the person who completed this step
            date_completed:
              type: [string, "null"]
              format: date
              description: >-
                Date when this step was completed. Must be current date
                or past date.
            notes:
              type: [string, "null"]
              description: Additional notes about this step
            solicitation_period_start_date:
              type: [string, "null"]
              format: date
              description: >-
                Date when the solicitation was issued. Must be current date
                or past date.
            solicitation_period_end_date:
              type: [string, "null"]
              format: date
              description: >-
                Date when the solicitation period ended. Must be current date
                or past date.
    ProcurementTrackerEvaluationStep:
      allOf:
        - $ref: "#/components/schemas/ProcurementTrackerStep"
        - type: object
          description: Evaluation step with additional fields
          properties:
            target_completion_date:
              type: string
              format: date
              nullable: true
              description: >-
                Target date for completing evaluation activities.
                Must be current date or future date.
            task_completed_by:
              type: integer
              nullable: true
              description: User ID of the person who completed this step
            date_completed:
              type: string
              format: date
              nullable: true
              description: >-
                Date when this step was completed. Must be current date
                or past date.
            notes:
              type: string
              nullable: true
              description: Additional notes about this step
    ProcurementTrackerPreAwardStep:
      allOf:
        - $ref: "#/components/schemas/ProcurementTrackerStep"
        - type: object
          description: Pre-Award step with additional fields for approval workflow
          properties:
            target_completion_date:
              type: string
              format: date
              nullable: true
              description: >-
                Target date for completing pre-award activities.
                Must be current date or future date.
            task_completed_by:
              type: integer
              nullable: true
              description: User ID of the person who completed this step
            date_completed:
              type: string
              format: date
              nullable: true
              description: >-
                Date when this step was completed. Must be current date
                or past date.
            notes:
              type: string
              nullable: true
              description: Additional notes about this step
            approval_requested:
              type: boolean
              nullable: true
              description: Whether pre-award approval has been requested
            approval_requested_date:
              type: string
              format: date
              nullable: true
              description: Date when pre-award approval was requested
            approval_requested_by:
              type: integer
              nullable: true
              description: User ID of the person who requested approval
            requestor_notes:
              type: string
              nullable: true
              description: Notes from the agreement manager requesting approval (max 150 characters)
            approval_status:
              type: string
              nullable: true
              enum:
                - PENDING
                - APPROVED
                - DECLINED
              description: Current status of the approval request
            approval_responded_by:
              type: integer
              nullable: true
              description: User ID of the approver who responded (Division Director, Budget Team, or System Owner)
            approval_responded_date:
              type: string
              format: date
              nullable: true
              description: Date when the approval request was responded to
            reviewer_notes:
              type: string
              nullable: true
              description: Notes from the approver (max 150 characters, required when declining)
    UpdateProcurementTrackerStepRequest:
      type: object
      description: Request schema for updating a procurement tracker step. All fields are optional for PATCH operations.
      properties:
        status:
          $ref: "#/components/schemas/ProcurementTrackerStepStatus"
        task_completed_by:
          type: integer
          nullable: true
          description: >-
            User ID of the person who completed this step
            (ACQUISITION_PLANNING, PRE_SOLICITATION, SOLICITATION, and EVALUATION steps)
        date_completed:
          type: string
          format: date
          nullable: true
          description: >-
            Date when this step was completed (ACQUISITION_PLANNING,
            PRE_SOLICITATION, SOLICITATION, and EVALUATION steps). Must be current date or
            past date.
        notes:
          type: string
          nullable: true
          description: >-
            Additional notes about this step (ACQUISITION_PLANNING,
            PRE_SOLICITATION, SOLICITATION, and EVALUATION steps)
        target_completion_date:
          type: string
          format: date
          nullable: true
          description: >-
            Target date for completing activities
            (PRE_SOLICITATION and EVALUATION steps). Must be current date or
            future date.
        draft_solicitation_date:
          type: string
          format: date
          nullable: true
          description: >-
            Date when the draft solicitation was completed
            (PRE_SOLICITATION steps only). Must be current date or
            future date.
        solicitation_period_start_date:
          type: string
          format: date
          nullable: true
          description: >-
            Date when the solicitation was issued
            (SOLICITATION steps only). Must be current date or past date.
        solicitation_period_end_date:
          type: string
          format: date
          nullable: true
          description: >-
            Date when the solicitation period ended
            (SOLICITATION steps only). Must be current date or past date.
        approval_status:
          type: string
          nullable: true
          enum:
            - APPROVED
            - DECLINED
          description: >-
            Approval status for PRE_AWARD steps. Server-controlled fields
            (approval_responded_by, approval_responded_date) are set automatically.
        reviewer_notes:
          type: string
          nullable: true
          description: >-
            Notes from the approver for PRE_AWARD steps (max 150 characters).
            Required when approval_status is DECLINED.
    ProcurementTrackerResponse:
      type: object
      description: Procurement tracker tracking workflow progress. New trackers are initialized with active_step_number set to 1, step 1 in ACTIVE status, and step 1's step_start_date set to the current date.
      properties:
        id:
          type: integer
          description: Unique identifier for the procurement tracker
        agreement_id:
          type: integer
          description: Associated agreement ID
        status:
          $ref: "#/components/schemas/ProcurementTrackerStatus"
        procurement_action:
          type: integer
          nullable: true
          description: Associated procurement action ID
        tracker_type:
          $ref: "#/components/schemas/ProcurementTrackerType"
        active_step_number:
          type: integer
          nullable: true
          description: The currently active step number in the workflow. Initialized to 1 for new trackers.
        steps:
          type: array
          items:
            anyOf:
              - $ref: "#/components/schemas/ProcurementTrackerStep"
              - $ref: "#/components/schemas/ProcurementTrackerAcquisitionPlanningStep"
              - $ref: "#/components/schemas/ProcurementTrackerPreSolicitationStep"
              - $ref: "#/components/schemas/ProcurementTrackerSolicitationStep"
              - $ref: "#/components/schemas/ProcurementTrackerEvaluationStep"
              - $ref: "#/components/schemas/ProcurementTrackerPreAwardStep"
          description: Array of workflow steps associated with this tracker. Different step types include additional fields - ACQUISITION_PLANNING (task_completed_by, date_completed, notes), PRE_SOLICITATION (target_completion_date, task_completed_by, date_completed, notes, draft_solicitation_date), SOLICITATION (task_completed_by, date_completed, notes, solicitation_period_start_date, solicitation_period_end_date), EVALUATION (target_completion_date, task_completed_by, date_completed, notes), PRE_AWARD (target_completion_date, task_completed_by, date_completed, notes, approval_requested, approval_requested_date, approval_requested_by, requestor_notes, approval_status, approval_responded_by, approval_responded_date, reviewer_notes). For new trackers, step 1 is initialized to ACTIVE status with step_start_date set to the current date, while all other steps are PENDING.
      required:
        - id
        - agreement_id
        - status
        - tracker_type
        - steps
    ProductServiceCode:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Code ABC
        naics:
          type: integer
          example: 3
        support_code:
          type: string
          example: Example Support Code
        description:
          type: string
          example: Description of the product service code
      required:
        - id
        - name
    Project:
      type: object
      description: Full schema for Administrative/Support projects (detail endpoint)
      properties:
        id:
          type: integer
          example: 1
        project_type:
          type: string
          enum:
            - RESEARCH
            - ADMINISTRATIVE_AND_SUPPORT
          example: ADMINISTRATIVE_AND_SUPPORT
        title:
          type: string
          example: Example Project Title
        short_title:
          type: string
          example: Short Title
        description:
          type: string
          example: A short description about the project
        url:
          type: string
          nullable: true
          example: www.example.com
        created_by:
          type: integer
          example: 1
        team_leaders:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              full_name:
                type: string
              email:
                type: string
          example:
            - id: 500
              full_name: "Jane Smith"
              email: "jane.smith@example.com"
        division_directors:
          type: array
          description: List of division directors from all agreements in the project
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: integer
              name:
                type: string
          example:
            - id: 500
              name: "Jane Smith"
            - id: 501
              name: "John Doe"
        project_officers:
          type: array
          description: List of project officers from all agreements in the project
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: integer
              name:
                type: string
          example:
            - id: 500
              name: "Jane Smith"
            - id: 501
              name: "John Doe"
        alternate_project_officers:
          type: array
          description: List of alternate project officers from all agreements in the project
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: integer
              name:
                type: string
          example:
            - id: 500
              name: "Jane Smith"
            - id: 501
              name: "John Doe"
        created_on:
          type: string
          format: date-time
          example: "2023-04-06T20:33:38.292475Z"
        updated_on:
          type: string
          format: date-time
          example: "2023-04-06T20:33:38.292475Z"
      required:
        - id
        - project_type
        - title
        - short_title
        - description
    DocumentResponse:
      type: object
      properties:
        url:
          type: string
        documents:
          $ref: "#/components/schemas/Documents"
    Documents:
      type: object
      properties:
        agreement_id:
          type: integer
          format: int32
        document_id:
          type: string
        document_type:
          type: string
        document_name:
          type: string
        document_size:
          type: number
          description: precision number with 10 digits and 2 decimal places
        status:
          type: string
        created_on:
          $ref: "#/components/parameters/created_on"
        updated_on:
          $ref: "#/components/parameters/updated_on"
        created_by:
          $ref: "#/components/parameters/created_by"
        updated_by:
          $ref: "#/components/parameters/updated_by"
    BudgetLineItemMeta:
      type: object
      properties:
        isEditable:
          type: boolean
          description: Whether the budget line item is associated with an agreement and can be edited
        total_count:
          type: integer
          description: Total number of budget line items in the system matching the query
        number_of_pages:
          type: integer
          description: Number of pages available based on limit
        limit:
          type: integer
          description: Maximum number of items per page
        offset:
          type: integer
          description: Number of items skipped
        query_parameters:
          type: object
          description: The query parameters used for the request
        total_amount:
          type: number
          description: Total amount for all budget line items matching the query
        total_draft_amount:
          type: number
          description: Total amount for all draft budget line items matching the query
        total_planned_amount:
          type: number
          description: Total amount for all planned budget line items matching the query
        total_in_execution_amount:
          type: number
          description: Total amount for all in-execution budget line items matching the query
        total_obligated_amount:
          type: number
          description: Total amount for all obligated budget line items matching the query
        total_overcome_by_events_amount:
          type: number
          description: Total amount for all overcome by events budget line items matching the query
    TeamMembers:
      type: object
      properties:
        id:
          type: integer
        full_name:
          type: string
        email:
          type: string
    AgreementData:
      type: object
      properties:
        name:
          type: string
          description: Agreement name
        nick_name:
          type: string
          description: Optional nickname for the agreement
        agreement_type:
          type: string
          enum: [CONTRACT, GRANT, DIRECT, IAA, IAA_AA]
        service_requirement_type:
          type: string
        description:
          type: string
        product_service_code_id:
          type: integer
        agreement_reason:
          type: string
        project_officer_id:
          type: integer
        alternate_project_officer_id:
          type: integer
        team_members:
          type: array
          items:
            $ref: "#/components/schemas/TeamMembers"
        project_id:
          type: integer
        awarding_entity_id:
          type: integer
        notes:
          type: string
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        maps_sys_id:
          type: integer
          description: Unique identifier for the agreement in the MAPS system
        budget_line_items:
          type: array
          description: |
            Optional array of budget line items to create atomically with the agreement.
            All items created in a single transaction - if any fails, all are rolled back.
          items:
            $ref: "#/components/schemas/NestedBudgetLineItemData"
        services_components:
          type: array
          description: |
            Optional array of services components to create atomically with the agreement.
            All items created in a single transaction - if any fails, all are rolled back.
          items:
            $ref: "#/components/schemas/NestedServicesComponentData"
        research_methodologies:
          type: array
          items:
            $ref: "#/components/schemas/ResearchMethodology"
        special_topics:
          type: array
          items:
            $ref: "#/components/schemas/SpecialTopic"

      required:
        - name
        - agreement_type
    ContractAgreementData:
      allOf:
        - $ref: "#/components/schemas/AgreementData"
        - type: object
          properties:
            contract_number:
              type: string
            vendor:
              type: string
            delivered_status:
              type: boolean
              default: false
            contract_type:
              type: string
            support_contacts:
              type: array
              items:
                $ref: "#/components/schemas/TeamMembers"
            task_order_number:
              type: string
            po_number:
              type: string
            acquisition_type:
              type: string
            contract_category:
              type: string
            psc_contract_specialist:
              type: string
            cotr_id:
              type: integer

    GrantAgreementData:
      allOf:
        - $ref: "#/components/schemas/AgreementData"
        - type: object
          properties:
            foa:
              type: string

    DirectAgreementData:
      allOf:
        - $ref: "#/components/schemas/AgreementData"

    IaaAgreementData:
      allOf:
        - $ref: "#/components/schemas/AgreementData"
        - type: object
          properties:
            iaa:
              type: string

    AaAgreementData:
      allOf:
        - $ref: "#/components/schemas/ContractAgreementData"
        - type: object
          properties:
            requesting_agency:
              $ref: "#/components/schemas/AgreementAgency"
            servicing_agency:
              $ref: "#/components/schemas/AgreementAgency"
          required:
            - requesting_agency
            - servicing_agency

    MetaSchema:
      type: object
      properties:
        isEditable:
          type: boolean
          default: false
        immutable_awarded_fields:
          type: array
          items:
            type: string
          nullable: true
          example:
            - name
            - contract_type
            - service_requirement_type
            - product_service_code_id
            - awarding_entity_id
            - agreement_reason

    AgreementResponse:
      allOf:
        - $ref: "#/components/schemas/AgreementData"
        - type: object
          properties:
            id:
              type: integer
            project:
              $ref: "#/components/schemas/Project"
            product_service_code:
              $ref: "#/components/schemas/ProductServiceCode"
            budget_line_items:
              type: array
              items:
                $ref: "#/components/schemas/BudgetLineItem"
            procurement_shop:
              $ref: "#/components/schemas/ProcurementShop"
            display_name:
              type: string
            division_directors:
              type: array
              description: List of division directors from budget line items (ID and name)
              items:
                type: string
            team_leaders:
              type: array
              items:
                type: string
            in_review:
              type: boolean
            authorized_user_ids:
              type: array
              items:
                type: integer
            change_requests_in_review:
              type: array
              nullable: true
              items:
                $ref: "#/components/schemas/AgreementChangeRequest"
              description: List of change requests currently in review
            created_by:
              $ref: "#/components/parameters/created_by"
            updated_by:
              $ref: "#/components/parameters/updated_by"
            created_on:
              $ref: "#/components/parameters/created_on"
            updated_on:
              $ref: "#/components/parameters/updated_on"
            award_type:
              type: string
              nullable: true
              description: >-
                Classification of the agreement for Budget Team reporting.
                Returns "NEW" if the agreement has non-Draft BLIs and is either
                not yet awarded, was awarded in the current fiscal year, or is
                considered awarded but has no recorded award date (fallback).
                Returns "CONTINUING" if the agreement has been awarded and the
                current fiscal year is after the award fiscal year.
                Returns null if the agreement has no non-Draft BLIs.
              enum:
                - NEW
                - CONTINUING
            _meta:
              $ref: "#/components/schemas/MetaSchema"
          required:
            - id
            - display_name
            - _meta
            - division_directors
            - team_leaders

    ContractAgreementResponse:
      allOf:
        - $ref: "#/components/schemas/AgreementResponse"
        - type: object
          properties:
            contract_number:
              type: string
            vendor_id:
              type: integer
            vendor:
              type: string
            delivered_status:
              type: boolean
              default: false
            contract_type:
              type: string
            service_requirement_type:
              type: string
            support_contacts:
              type: array
              items:
                $ref: "#/components/schemas/TeamMembers"
            task_order_number:
              type: string
            po_number:
              type: string
            acquisition_type:
              type: string
            contract_category:
              type: string
            psc_contract_specialist:
              type: string
            cotr_id:
              type: integer
            is_awarded:
              type: boolean
              description: Indicates whether the assisted acquisition agreement has been officially awarded.

    GrantAgreementResponse:
      allOf:
        - $ref: "#/components/schemas/AgreementResponse"
        - type: object
          properties:
            foa:
              type: string

    DirectAgreementResponse:
      allOf:
        - $ref: "#/components/schemas/AgreementResponse"

    IaaAgreementResponse:
      allOf:
        - $ref: "#/components/schemas/AgreementResponse"
        - type: object
          properties:
            iaa:
              type: string
          required:
            - iaa

    AgreementAgency:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "Agency Name"
        abbreviation:
          type: string
          example: "AGY"
        requesting:
          type: boolean
          example: true
        servicing:
          type: boolean
          example: false

    AaAgreementResponse:
      allOf:
        - $ref: "#/components/schemas/ContractAgreementResponse"
        - type: object
          properties:
            requesting_agency:
              $ref: "#/components/schemas/AgreementAgency"
            servicing_agency:
              $ref: "#/components/schemas/AgreementAgency"
            is_awarded:
              type: boolean
              description: Indicates whether the assisted acquisition agreement has been officially awarded.
          required:
            - requesting_agency
            - servicing_agency

    LoginRequest:
      type: object
      properties:
        code:
          type: string
          description: Authentication code from provider
        provider:
          type: string
          enum: [fakeauth, logingov, hhsams]
          description: Authentication provider to use
      required:
        - code
        - provider

    LoginResponse:
      type: object
      properties:
        access_token:
          type: string
          description: JWT access token
        refresh_token:
          type: string
          description: JWT refresh token
        user:
          type: object
          description: User information
          properties:
            id:
              type: integer
              description: User ID
            oidc_id:
              type: string
              format: uuid
              description: Provider user identifier
            status:
              type: string
              enum: [ACTIVE, INACTIVE, LOCKED]
              description: User status
            hhs_id:
              type: string
              nullable: true
              description: HHS identifier (optional)
            email:
              type: string
              format: email
              description: User email
            first_name:
              type: string
              nullable: true
              description: User's first name
            last_name:
              type: string
              nullable: true
              description: User's last name
            full_name:
              type: string
              nullable: true
              description: User's full name (first and last)
            division:
              type: integer
              nullable: true
              description: Division ID (optional)
            roles:
              type: array
              description: List of role names
              items:
                type: string
            display_name:
              type: string
              description: Display name (usually full name, or email)

    LoginErrorResponse:
      type: object
      properties:
        error_type:
          type: string
          enum: [USER_NOT_FOUND, USER_INACTIVE, USER_LOCKED, AUTHN_ERROR, AUTHZ_ERROR, PROVIDER_ERROR, UNKNOWN_ERROR]
          description: Type of login error
        message:
          type: string
          description: Error message

    ResearchMethodology:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "Knowledge Development (Lit Review, Expert Consultations)"
        detailed_name:
          type: string
          example: "Knowledge Development (Lit Review, Expert Consultations)"
      required:
        - id
        - name
        - detailed_name
    SpecialTopic:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "Special Topic 1"
    NestedBudgetLineItemData:
      type: object
      description: |
        Budget line item data for nested creation within agreement requests.
        Excludes agreement_id (set automatically) and adds services_component_ref
        for referencing services components created in the same request.
      required:
        - line_description
        - amount
        - can_id
        - status
      properties:
        line_description:
          type: string
          description: Description of the budget line item
        amount:
          type: number
          format: float
          description: Budget line item amount in dollars
        can_id:
          type: integer
          description: CAN (Contract Account Number) ID
        status:
          type: string
          enum: [DRAFT, PLANNED, IN_EXECUTION, OBLIGATED]
          description: Status of the budget line item
        date_needed:
          type: string
          format: date
          description: Date when funding is needed
        services_component_id:
          type: integer
          description: |
            Reference to an existing services component by database ID.
            Cannot be used with services_component_ref.
          nullable: true
        services_component_ref:
          type: string
          description: |
            Reference to a services component being created in the same request.
            Matches the 'ref' field in the services_components array.
            If the services component has no 'ref', use its array index as a string ("0", "1", etc.).
            Cannot be used with services_component_id.
          nullable: true
        comments:
          type: string
          description: Additional comments about the budget line item
          nullable: true

    NestedServicesComponentData:
      type: object
      description: |
        Services component data for nested creation within agreement requests.
        Excludes agreement_id (set automatically) and adds 'ref' field for
        referencing by budget line items.
      required:
        - number
        - optional
      properties:
        ref:
          type: string
          description: |
            Temporary reference identifier for this services component.
            Budget line items can reference this using 'services_component_ref'.
            If not provided, the array index (as a string) will be used.
          nullable: true
        number:
          type: integer
          description: Sequence number of the services component
        optional:
          type: boolean
          description: Whether this is an optional services component (option period)
        description:
          type: string
          description: Description of the services component
          nullable: true
        period_start:
          type: string
          format: date
          description: Start date of the period
          nullable: true
        period_end:
          type: string
          format: date
          description: End date of the period
          nullable: true


  examples:
    CAN:
      value:
        - is_expired: true
        - appropriation_date: "2023-09-01T00:00:00.000000Z"
        - appropriation_term: 1
        - arrangement_type_id: 2
        - authorizer_id: 23
        - description: Healthy Marriages Responsible Fatherhood - OFA
        - expiration_date: "2023-09-01T00:00:00.000000Z"
        - id: 10
        - managing_portfolio_id: 6
        - managing_project_id: null
        - nickname: HMRF-OFA
        - number: G99XXX3
        - purpose: ""
    Portfolio:
      value: |
        {
          "cans": [
              {
                  "appropriation_date": "2023-09-01T00:00:00.000000Z",
                  "appropriation_term": 1,
                  "arrangement_type_id": 3,
                  "authorizer_id": 26,
                  "description": "Incoming Interagency Agreements",
                  "expiration_date": "2023-09-01T00:00:00.000000Z",
                  "id": 2,
                  "managing_portfolio_id": 1,
                  "managing_project_id": null,
                  "nickname": "IAA-Incoming",
                  "number": "G99IA14",
                  "purpose": "",
                  "created_on": "2023-04-06T20:33:38.292475",
                  "updated_on": "2023-04-06T20:33:38.292475",
                  "created_by": 1,
                  "updated_by": 1
              },
              {
                  "appropriation_date": "2023-09-01T00:00:00.000000Z",
                  "appropriation_term": 1,
                  "arrangement_type_id": 4,
                  "authorizer_id": 26,
                  "description": "Child Development Research Fellowship Grant Program",
                  "expiration_date": "2023-09-01T00:00:00.000000Z",
                  "id": 4,
                  "managing_portfolio_id": 1,
                  "managing_project_id": 1,
                  "nickname": "ASPE SRCD-IDDA",
                  "number": "G990136",
                  "purpose": "",
                  "created_on": "2023-04-06T20:33:38.292475",
                  "updated_on": "2023-04-06T20:33:38.292475",
                  "created_by": 1,
                  "updated_by": 1
              }
          ],
          "description": "The promotion of childrens safety, ... to the attention of child welfare.",
          "division": {
              "abbreviation": "DCFD",
              "id": 1,
              "name": "Division of Child and Family Development"
              "division_director_id": "522"
              "deputy_division_director_id": "520"
              "created_on": "2024-11-14 20:20:55.176355"
              "updated_on": "2024-11-14 20:20:55.176355"
              "created_by": 1,
              "updated_by": 1
          },
          "division_id": 1,
          "id": 1,
          "name": "Child Welfare Research",
          "status": "Active",
          "status_id": 1,
          "team_leaders": [
              {
                  "date_joined": "2023-04-06T20:33:38.292475",
                  "division": 1,
                  "email": "emily.ball@example.com",
                  "first_name": "Emily",
                  "full_name": "(no name) (no name)",
                  "id": 1,
                  "last_name": "Ball",
                  "oidc_id": "00000000-0000-1111-a111-000000000001",
                  "role": "COR",
                  "updated": null
              }
          ],
          "urls": [
              {
                  "id": 1,
                  "portfolio_id": 1,
                  "url": "https://acf.gov/opre/topic/overview/abuse-neglect-adoption-foster-care"
              }
          ],
          "created_on": "2023-04-06T20:33:38.292475",
          "updated_on": "2023-04-06T20:33:38.292475",
          "created_by": 1,
          "updated_by": 1
        }
    PortfolioUrl:
      value: |
        {
          "id": 1,
          "portfolio_id": 1,
          "url": "https://acf.gov/opre/topic/overview/abuse-neglect-adoption-foster-care",
          "updated_by": 1,
          "created_by": 1,
          "created_on": "2023-04-06T20:33:38.292475",
          "updated_on": "2023-04-06T20:33:38.292475",
        }
    CreateUpdatePortfolioUrl:
      value: |
        {
          "portfolio_id": 1,
          "url": "https://acf.gov/opre/topic/overview/abuse-neglect-adoption-foster-care",
        }
    User:
      value:
        id: 5
        oidc_id: "00000000-aaaa-bbbb-0000-000000000001"
        status: "ACTIVE"
        hhs_id: "123456"
        email: "user@email.com"
        first_name: "Jon"
        last_name: "Doe"
        full_name: "Jon Doe"
        display_name: "Jon Doe"
        division: 3
        is_superuser: true
        roles:
          - id: 1
            name: "SUPER USER"
            is_superuser: true
        created_by: 1
        updated_by: 1
        created_on: "2023-04-06T20:33:38.292475"
        updated_on: "2023-04-06T20:33:38.292475"
    ResearchProjects:
      value: |
        [
          {
            "id": 1,
            "title": "African American Child and Family Research Center",
            "short_title": "AACFRC",
            "description": "The National African American Child and Family Research Center, supported by a five-year OPRE grant (2021-2026), will provide national leadership and excellence by investigating the assets, needs, and experiences of the diverse population of African American families and children served (or potentially served) by ACF programs, as well as promising approaches to address economic and social inequities and, ultimately, promote social and economic well-being. The primary focus of this Center will be on childcare assistance, TANF, and Head Start and Early Head Start programs and the populations they serve. The work of the Center will draw on interdisciplinary approaches to accomplish the three goals listed below.\n\n1. Advance Research: The Center will plan, initiate, and maintain a community-engaged, focused, and high-caliber research program. The Center's program of research will build on the existing literature related to African American children and families and should be directly relevant to the needs and interests of ACF areas of programmatic concern.\n\n2. Build Research Capacity: The Center will build research capacity and infrastructure to conduct research relevant to ACF program and policy goals that is culturally rigorous and informed by an understanding of current and historical circumstances that shape the experiences of African Americans. In addition, the Center will contribute to the development and expansion of the pool of researchers reflective of the communities being studied by the Center.\n\n3. Communicate Research: The Center will develop and implement a dissemination strategy that broadly and efficiently communicates findings from research conducted within and outside of the Center and increases the use of research, data, and relevant resources for a wide audience including researchers, federal and state policymakers, ACF grantees, program administrators, and communities participating in the research.\n\nThe Center is led by the Morehouse School of Medicine.\n\nThe OPRE point of contact is Megan Reid.",
            "url": "https://acf.gov/opre/project/african-american-child-and-family-research-center",
            "origination_date": "2022-01-01",
            "created_on": "2023-04-06T20:33:38.292475Z",
            "updated_on": "2023-04-06T20:33:38.292475Z",
            "project_type": "RESEARCH"
          }
        ]
    AGREEMENTS:
      value: |
        [
           {
               "id": 1,
               "created_on": "2023-04-06T20:33:38.292475",
               "updated_on": "2023-04-06T20:33:38.292475",
               "created_by": 1,
               "updated_by": 1,
               "name": "Using Innovative Data to Explore Racial and Ethnic Disparities in Human Services",
               "project_id": 1,
               "description": "This will be a contract to continue planned analyses to explore disparities.",
               "agreement_type": "CONTRACT",
               "project_officer": "Ivelisse Martinez-Beck",
               "alternate_project_officer": "Ivelisse Martinez-Beck",
               "period_of_performance_start": "2021-01-01",
               "period_of_performance_end": "2021-12-31",
               procurement_shop: {
                   id: 2,
                   name: "Government Contracting Services",
                   fee: 0,
               },
               budget_line_items: [
                   {
                       id: 123456,
                       line_description: "LI 1",
                       comments: "",
                       can_id: 5,
                       can_number: "G994426",
                       agreement_id: 1,
                       amount: 1000000.0,
                       status: "EXECUTING",
                       date_needed: "2111-1-11",
                       proc_shop_fee_percentage: 0,
                       created_by: "Carolyn Hsu",
                       created_on: "2023-4-5",
                       updated_on: "2023-4-15",
                   },
                   {
                       id: 123457,
                       line_description: "LI 2",
                       comments: "",
                       can_id: 5,
                       can_number: "G994426",
                       agreement_id: 1,
                       amount: 1000000.0,
                       status: "OBLIGATED",
                       date_needed: "2222-2-22",
                       proc_shop_fee_percentage: 0,
                       created_by: "Carolyn Hsu",
                       created_on: "2023-4-1",
                       updated_on: "2023-4-15",
                   },
                   {
                       id: 123458,
                       line_description: "LI 3",
                       comments: "",
                       can_id: 5,
                       can_number: "G994426",
                       agreement_id: 1,
                       amount: 1000000.0,
                       status: "PLANNED",
                       date_needed: "2333-3-13",
                       proc_shop_fee_percentage: 0,
                       created_by: "Carolyn Hsu",
                       created_on: "2023-3-11",
                       updated_on: "2023-4-15",
                   },
                 ],
           },

         ];
    Agreements:
      value: |
        [{
          "agreement_type": "CONTRACT",
          "created_on": "2023-04-06T20:33:38.292475",
          "updated_on": "2023-04-06T20:33:38.292475",
          "created_by": 1,
          "updated_by": 1
          "id": 2,
          "name": "Contract #2: African American Child and Family Research Center",
          "project_id": 1,
           cans: [],
           budget_line_items: [
            {
                line_description: "LI 1",
                comments: "",
                can_id: 5,
                agreement_id: 1,
                amount: 1000000.0,
                status: "EXECUTING",
                date_needed: "2111-1-11",
                proc_shop_fee_percentage: 0.5,
            },
            {
                line_description: "LI 2",
                comments: "",
                can_id: 5,
                agreement_id: 1,
                amount: 1000000.0,
                status: "OBLIGATED",
                date_needed: "2222-2-22",
                proc_shop_fee_percentage: 0.5,
            },
            {
                line_description: "LI 3",
                comments: "",
                can_id: 5,
                agreement_id: 1,
                amount: 1000000.0,
                status: "PLANNED",
                date_needed: "2333-3-13",
                proc_shop_fee_percentage: 0.5,
            },
        ],
        }]
    Agreement:
      value: |
        {
          "agreement_type": "CONTRACT",
          "created_on": "2023-04-06T20:33:38.292475",
          "updated_on": "2023-04-06T20:33:38.292475",
          "created_by": 1,
          "updated_by": 1
          "id": 2,
          "name": "Contract #2: African American Child and Family Research Center",
          "project_id": 1,
          cans: [],
          budget_line_items: [
            {
                line_description: "LI 1",
                comments: "",
                can_id: 5,
                agreement_id: 2,
                amount: 1000000.0,
                status: "EXECUTING",
                date_needed: "2111-1-11",
                proc_shop_fee_percentage: 0.5,
            },
            {
                line_description: "LI 2",
                comments: "",
                can_id: 5,
                agreement_id: 2,
                amount: 1000000.0,
                status: "OBLIGATED",
                date_needed: "2222-2-22",
                proc_shop_fee_percentage: 0.5,
            },
            {
                line_description: "LI 3",
                comments: "",
                can_id: 5,
                agreement_id: 2,
                amount: 1000000.0,
                status: "PLANNED",
                date_needed: "2333-3-13",
                proc_shop_fee_percentage: 0.5,
            },
        ],
        }
    BudgetLineItems:
      value: |
        [
          {
              "agreement_id": 1,
              "amount": 1000000.0,
              "can_id": 5,
              "comments": "",
              "date_needed": "2023-05-06",
              "id": 1,
              "line_description": "LI 1",
              "proc_shop_fee_percentage": null,
              "procurement_shop_fee_id": 3,
              "procurement_shop_fee": {
                "id": 3,
                "procurement_shop_id": 2,
                "fee": 5.75,
                "start_date": "2023-01-01",
                "end_date": "2023-12-31"
              },
              "status": "PLANNED",
              "is_obe": false,
              "created_on": "2023-04-06T20:33:38.292475",
              "updated_on": "2023-04-06T20:33:38.292475",
              "created_by": 1,
              "updated_by": 1
          },
          {
              "agreement_id": 1,
              "amount": 1000000.0,
              "can_id": 5,
              "procurement_shop_fee_id": 3,
              "procurement_shop_fee": {
                "id": 3,
                "procurement_shop_id": 2,
                "fee": 5.75,
                "start_date": "2023-01-01",
                "end_date": "2023-12-31"
              }
          }
        ]
    CreateUpdateCANRequestSchema:
      value: |
        {
          nick_name: "Very Good CAN",
          number: "G998235",
          portfolio_id: 6,
          description: "A very good CAN to use for examples."
        }
    CreateUpdateFundingReceived:
      value: |
        {
          can_id: 500,
          fiscal_year: 2024,
          funding: 123456,
          notes: "A new test Funding Budget"
        }
    FundingReceived:
      value: |
        {
          funding: 1234567.89
          can: {}
          can_id: 500
          display_name: CANFundingBudget.1
          fiscal_year: 2024
          id: 1
          notes: "A funding budget"
          versions: {}
    CreateUpdateCANFundingBudgetRequest:
      value: |
        {
          can_id: 500,
          fiscal_year: 2024,
          budget: 123456,
          notes: "A new test Funding Funding"
        }

    CreateUpdateFundingDetails:
      value: |
        {
          allotment: "Allotment"
          allowance: "Allowance"
          display_name: "Display name"
          fiscal_year: 2024
          fund_code: "AAXXXX20231DAD"
          funding_partner: "OPRE Partner"
          funding_source: "OPRE"
          method_of_transfer: "DIRECT"
          sub_allowance: "Money"
        }
    FundingBudget:
      value: |
        {
          budget: 1234567.89
          can: {}
          can_id: 500
          display_name: CANFundingBudget.1
          fiscal_year: 2024
          id: 1
          notes: "A funding budget"
          versions: {}
    Notifications:
      value: |
        [
        ]
    AgreementAgency:
      value: |
        {
          "id": 1,
          "name": "Agency Name",
          "abbreviation": "AG",
          "requesting": true,
          "servicing": false
        }

    simple_agreement:
      summary: Simple agreement without nested entities
      description: Backward compatible - creates only the agreement
      value:
        name: "Simple Contract"
        agreement_type: "CONTRACT"
        project_id: 1000
        agreement_reason: "NEW_REQ"
        description: "A simple agreement"

    with_budget_line_items:
      summary: Agreement with budget line items
      description: Creates agreement and budget line items atomically
      value:
        name: "Multi-Year Grant"
        agreement_type: "GRANT"
        project_id: 1000
        agreement_reason: "NEW_REQ"
        foa: "HHS-2025-ACF-OPRE-FR-0001"
        budget_line_items:
          - line_description: "Year 1 Research"
            amount: 750000.00
            can_id: 500
            status: "PLANNED"
            date_needed: "2025-10-01"
          - line_description: "Year 2 Research"
            amount: 800000.00
            can_id: 501
            status: "PLANNED"
            date_needed: "2026-10-01"

    full_atomic_creation:
      summary: Agreement with services components and budget line items
      description: Creates all entities atomically with BLIs referencing new SCs
      value:
        name: "Full Multi-Year Contract"
        agreement_type: "CONTRACT"
        project_id: 1000
        agreement_reason: "NEW_REQ"
        contract_number: "75FCMC18D0030"
        vendor: "Acme Corporation"
        services_components:
          - ref: "base_period"
            number: 1
            optional: false
            description: "Base Period - FY25"
            period_start: "2025-10-01"
            period_end: "2026-09-30"
          - ref: "option_year_1"
            number: 2
            optional: true
            description: "Option Year 1 - FY26"
            period_start: "2026-10-01"
            period_end: "2027-09-30"
        budget_line_items:
          - line_description: "Base Period Budget"
            amount: 1000000.00
            can_id: 500
            status: "PLANNED"
            date_needed: "2025-10-01"
            services_component_ref: "base_period"
          - line_description: "Option Year 1 Budget"
            amount: 1050000.00
            can_id: 501
            status: "PLANNED"
            date_needed: "2026-10-01"
            services_component_ref: "option_year_1"

    ProcurementActionInProcess:
      summary: Procurement action in process
      description: >-
        Example showing a NEW_AWARD procurement action with IN_PROCESS
        status for an active procurement tracker
      value:
        id: 1
        agreement_id: 1
        agreement: null
        agreement_mod_id: null
        agreement_mod: null
        award_type: "NEW_AWARD"
        mod_type: null
        status: "IN_PROCESS"
        procurement_shop_id: 1
        procurement_shop: null
        psc_action_number: "PSC-2026-001"
        need_by_date: "2026-06-01"
        requisition_deadline: "2026-03-15"
        date_awarded_obligated: null
        desired_days_on_street: 30
        action_description: "New contract award for research services"
        comments: "Procurement in progress"
        psc_fee_percentage: "0.05"
        award_total: null
        agreement_total: null
        display_name: "New Award for Agreement #1"

    ProcurementActionAwarded:
      summary: Awarded procurement action
      description: >-
        Example showing a NEW_AWARD procurement action with AWARDED status
        for a completed procurement tracker
      value:
        id: 5
        agreement_id: 2
        agreement: null
        agreement_mod_id: null
        agreement_mod: null
        award_type: "NEW_AWARD"
        mod_type: null
        status: "AWARDED"
        procurement_shop_id: 1
        procurement_shop: null
        psc_action_number: "PSC-2025-042"
        need_by_date: "2025-12-01"
        requisition_deadline: "2025-10-15"
        date_awarded_obligated: "2026-01-05"
        desired_days_on_street: 30
        action_description: "New contract award for research services"
        comments: "Successfully awarded and obligated"
        psc_fee_percentage: "0.05"
        award_total: "500000.00"
        agreement_total: "500000.00"
        display_name: "New Award for Agreement #2"

    ProcurementTrackerStepExample:
      summary: Standard procurement tracker step
      description: >-
        Example showing a basic tracker step without acquisition planning
        fields
      value:
        id: 2
        procurement_tracker_id: 1
        step_number: 2
        step_type: "PRE_SOLICITATION"
        status: "ACTIVE"
        step_start_date: "2026-01-02"
        step_completed_date: null

    ProcurementTrackerAcquisitionPlanningStepExample:
      summary: Acquisition planning tracker step
      description: >-
        Example showing an acquisition planning step with additional fields
        (task_completed_by, date_completed, notes)
      value:
        id: 1
        procurement_tracker_id: 1
        step_number: 1
        step_type: "ACQUISITION_PLANNING"
        status: "COMPLETED"
        task_completed_by: 521
        date_completed: "2026-01-01"
        notes: "Acquisition planning completed on schedule."
        step_start_date: "2025-12-01"
        step_completed_date: "2026-01-01"

    UpdateProcurementTrackerStepAcquisitionPlanningRequest:
      summary: PATCH request to complete acquisition planning step
      description: >-
        Example PATCH request body for updating an acquisition planning
        step to COMPLETED status with all additional fields. All fields
        are optional. Date field (date_completed) must be current date
        or past date.
      value:
        status: "COMPLETED"
        task_completed_by: 521
        date_completed: "2026-01-01"
        notes: >-
          Acquisition planning completed on schedule. All requirements
          reviewed and approved.

    ProcurementTrackerPreSolicitationStepExample:
      summary: Pre-solicitation tracker step
      description: >-
        Example showing a pre-solicitation step with additional fields
        (target_completion_date, task_completed_by, date_completed,
        notes, draft_solicitation_date)
      value:
        id: 2
        procurement_tracker_id: 1
        step_number: 2
        step_type: "PRE_SOLICITATION"
        status: "ACTIVE"
        target_completion_date: "2026-02-15"
        task_completed_by: null
        date_completed: null
        notes: "Working on draft solicitation document."
        draft_solicitation_date: null
        step_start_date: "2026-01-02"
        step_completed_date: null

    ProcurementTrackerSolicitationStepExample:
      summary: Solicitation tracker step
      description: >-
        Example showing a solicitation step with additional fields
        (solicitation_period_start_date, solicitation_period_end_date, task_completed_by, date_completed,
        notes)
      value:
        id: 2
        procurement_tracker_id: 1
        step_number: 2
        step_type: "SOLICITATION"
        status: "ACTIVE"
        solicitation_period_start_date: "2026-01-02"
        solicitation_period_end_date: "2026-02-15"
        task_completed_by: null
        date_completed: null
        notes: "Working on solicitation document."
        step_start_date: "2026-01-02"
        step_completed_date: null

    ProcurementTrackerPreAwardStepExample:
      summary: Pre-Award tracker step with approval workflow
      description: >-
        Example showing a pre-award step with approval request and response fields
        (approval_requested, approval_requested_date, approval_requested_by, requestor_notes,
        approval_status, approval_responded_by, approval_responded_date, reviewer_notes)
      value:
        id: 25
        procurement_tracker_id: 5
        step_number: 5
        step_type: "PRE_AWARD"
        status: "IN_PROGRESS"
        step_start_date: "2026-04-05"
        step_completed_date: null
        target_completion_date: "2026-04-15"
        task_completed_by: null
        date_completed: null
        notes: null
        approval_requested: true
        approval_requested_date: "2026-04-05"
        approval_requested_by: 42
        requestor_notes: "Urgent approval needed for Q2 budget execution"
        approval_status: "APPROVED"
        approval_responded_by: 100
        approval_responded_date: "2026-04-06"
        reviewer_notes: "Approved - all budget lines reviewed and verified"

    UpdateProcurementTrackerStepPreSolicitationRequest:
      summary: PATCH request to complete pre-solicitation step
      description: >-
        Example PATCH request body for updating a pre-solicitation
        step to COMPLETED status with all additional fields. All fields
        are optional. Date fields (target_completion_date,
        draft_solicitation_date) must be current date or future date.
      value:
        status: "COMPLETED"
        target_completion_date: "2026-02-15"
        task_completed_by: 521
        date_completed: "2026-02-10"
        draft_solicitation_date: "2026-02-08"
        notes: >-
          Pre-solicitation phase completed. Draft solicitation reviewed
          and approved by all stakeholders.

    UpdateProcurementTrackerStepSolicitationRequest:
      summary: PATCH request to complete Solicitation step
      description: >-
        Example showing a solicitation step with additional fields
        (solicitation_period_start_date, solicitation_period_end_date, task_completed_by, date_completed,
        notes) and a PATCH request to complete the step. All fields in the PATCH request are optional.
        Date fields (solicitation_period_start_date, solicitation_period_end_date) must be current date or future date.
      value:
        status: "COMPLETED"
        solicitation_period_start_date: "2026-01-02"
        solicitation_period_end_date: "2026-02-15"
        task_completed_by: 521
        date_completed: "2026-02-10"
        notes: "Solicitation phase completed."

    UpdateProcurementTrackerStepPreAwardRequest:
      summary: PATCH request to approve/decline pre-award approval
      description: >-
        Example PATCH request body for approvers to respond to a pre-award
        approval request. The approval_status field must be either APPROVED
        or DECLINED. The reviewer_notes field is optional when approving
        but required when declining (max 150 characters). Server-controlled
        fields (approval_responded_by, approval_responded_date) are set
        automatically from the current user and timestamp.
      value:
        approval_status: "APPROVED"
        reviewer_notes: "All budget lines verified and approved for execution"

    ProcurementTracker:
      summary: Single procurement tracker with mixed step types
      description: >-
        Example showing a tracker with ACQUISITION_PLANNING step (with
        extra fields) and other steps (without extra fields)
      value:
        id: 1
        agreement_id: 1
        status: "ACTIVE"
        procurement_action: 1
        tracker_type: "DEFAULT"
        active_step_number: 2
        steps:
          - id: 1
            procurement_tracker_id: 1
            step_number: 1
            step_type: "ACQUISITION_PLANNING"
            status: "COMPLETED"
            task_completed_by: 521
            date_completed: "2026-01-01"
            notes: "Acquisition planning completed on schedule."
            step_start_date: "2025-12-01"
            step_completed_date: "2026-01-01"
          - id: 2
            procurement_tracker_id: 1
            step_number: 2
            step_type: "PRE_SOLICITATION"
            status: "ACTIVE"
            target_completion_date: "2026-02-15"
            task_completed_by: null
            date_completed: null
            notes: "Working on draft solicitation document."
            draft_solicitation_date: null
            step_start_date: "2026-01-02"
            step_completed_date: null
          - id: 3
            procurement_tracker_id: 1
            step_number: 3
            step_type: "SOLICITATION"
            status: "PENDING"
            solicitation_period_start_date: null
            solicitation_period_end_date: null
            task_completed_by: null
            date_completed: null
            notes: null
            step_start_date: null
            step_completed_date: null
          - id: 4
            procurement_tracker_id: 1
            step_number: 4
            step_type: "EVALUATION"
            status: "PENDING"
            step_start_date: null
            step_completed_date: null
          - id: 5
            procurement_tracker_id: 1
            step_number: 5
            step_type: "PRE_AWARD"
            status: "PENDING"
            step_start_date: null
            step_completed_date: null
          - id: 6
            procurement_tracker_id: 1
            step_number: 6
            step_type: "AWARD"
            status: "PENDING"
            step_start_date: null
            step_completed_date: null

    ProcurementTrackerNewlyInitialized:
      summary: Newly initialized procurement tracker
      description: >-
        Example showing a newly created tracker in its initial state. Step 1
        (ACQUISITION_PLANNING) is ACTIVE with step_start_date set to the current
        date, while all other steps are PENDING. The active_step_number is set to 1.
      value:
        id: 1
        agreement_id: 1
        status: "ACTIVE"
        procurement_action: 1
        tracker_type: "DEFAULT"
        active_step_number: 1
        steps:
          - id: 1
            procurement_tracker_id: 1
            step_number: 1
            step_type: "ACQUISITION_PLANNING"
            status: "ACTIVE"
            task_completed_by: null
            date_completed: null
            notes: null
            step_start_date: "2026-01-27"
            step_completed_date: null
          - id: 2
            procurement_tracker_id: 1
            step_number: 2
            step_type: "PRE_SOLICITATION"
            status: "PENDING"
            step_start_date: null
            step_completed_date: null
          - id: 3
            procurement_tracker_id: 1
            step_number: 3
            step_type: "SOLICITATION"
            status: "PENDING"
            step_start_date: null
            step_completed_date: null
          - id: 4
            procurement_tracker_id: 1
            step_number: 4
            step_type: "EVALUATION"
            status: "PENDING"
            step_start_date: null
            step_completed_date: null
          - id: 5
            procurement_tracker_id: 1
            step_number: 5
            step_type: "PRE_AWARD"
            status: "PENDING"
            step_start_date: null
            step_completed_date: null
          - id: 6
            procurement_tracker_id: 1
            step_number: 6
            step_type: "AWARD"
            status: "PENDING"
            step_start_date: null
            step_completed_date: null

    ProcurementTrackersList:
      summary: Paginated list of procurement trackers
      description: Example showing multiple trackers with pagination metadata
      value:
        data:
          - id: 1
            agreement_id: 1
            status: "ACTIVE"
            procurement_action: 1
            tracker_type: "DEFAULT"
            active_step_number: 2
            steps:
              - id: 1
                procurement_tracker_id: 1
                step_number: 1
                step_type: "ACQUISITION_PLANNING"
                status: "COMPLETED"
                task_completed_by: 521
                date_completed: "2026-01-01"
                notes: "Completed on time."
                step_start_date: "2025-12-01"
                step_completed_date: "2026-01-01"
              - id: 2
                procurement_tracker_id: 1
                step_number: 2
                step_type: "PRE_SOLICITATION"
                status: "ACTIVE"
                step_start_date: "2026-01-02"
                step_completed_date: null
              - id: 3
                procurement_tracker_id: 1
                step_number: 3
                step_type: "SOLICITATION"
                status: "PENDING"
                step_start_date: null
                step_completed_date: null
              - id: 4
                procurement_tracker_id: 1
                step_number: 4
                step_type: "EVALUATION"
                status: "PENDING"
                step_start_date: null
                step_completed_date: null
              - id: 5
                procurement_tracker_id: 1
                step_number: 5
                step_type: "PRE_AWARD"
                status: "PENDING"
                step_start_date: null
                step_completed_date: null
              - id: 6
                procurement_tracker_id: 1
                step_number: 6
                step_type: "AWARD"
                status: "PENDING"
                step_start_date: null
                step_completed_date: null
          - id: 2
            agreement_id: 2
            status: "COMPLETED"
            procurement_action: 5
            tracker_type: "DEFAULT"
            active_step_number: null
            steps:
              - id: 7
                procurement_tracker_id: 2
                step_number: 1
                step_type: "ACQUISITION_PLANNING"
                status: "COMPLETED"
                task_completed_by: 520
                date_completed: "2025-11-15"
                notes: "Fast-tracked acquisition planning."
                step_start_date: "2025-11-01"
                step_completed_date: "2025-11-15"
              - id: 8
                procurement_tracker_id: 2
                step_number: 2
                step_type: "PRE_SOLICITATION"
                status: "COMPLETED"
                step_start_date: "2025-11-16"
                step_completed_date: "2025-11-30"
              - id: 9
                procurement_tracker_id: 2
                step_number: 3
                step_type: "SOLICITATION"
                status: "COMPLETED"
                step_start_date: "2025-12-01"
                step_completed_date: "2025-12-15"
              - id: 10
                procurement_tracker_id: 2
                step_number: 4
                step_type: "EVALUATION"
                status: "COMPLETED"
                step_start_date: "2025-12-16"
                step_completed_date: "2025-12-22"
              - id: 11
                procurement_tracker_id: 2
                step_number: 5
                step_type: "PRE_AWARD"
                status: "COMPLETED"
                step_start_date: "2025-12-23"
                step_completed_date: "2025-12-30"
              - id: 12
                procurement_tracker_id: 2
                step_number: 6
                step_type: "AWARD"
                status: "COMPLETED"
                step_start_date: "2025-12-31"
                step_completed_date: "2026-01-05"
        count: 15
        limit: 10
        offset: 0

security:
  - bearerAuth: []