openapi: 3.1.0
info:
  description: '

    Back end API for simpler.grants.gov.


    This API is in active development as we build out new functionalities for Simpler.Grants.gov. It is currently stable for everyday use, and will be versioned with advance notice for any breaking changes.


    Learn more in our [API documentation](https://wiki.simpler.grants.gov/product/api).

    See [Release Phases](https://github.com/github/roadmap?tab=readme-ov-file#release-phases) for further details.

    '
  contact:
    name: Simpler Grants.gov
    url: https://simpler.grants.gov/
    email: simpler@grants.gov
  title: Simpler Grants Award Recommendation Alpha API
  version: v0
servers: .
tags:
- name: Award Recommendation Alpha
paths:
  /alpha/award-recommendations:
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationGetResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not Found
      tags:
      - Award Recommendation Alpha
      summary: Create Award Recommendation
      description: Create a new award recommendation for an opportunity, linking application submissions and audit data.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationCreateRequestSchema'
      security:
      - ApiJwtAuth: &id001 []
      - ApiUserKeyAuth: *id001
  /alpha/award-recommendations/list:
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationListResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not Found
      tags:
      - Award Recommendation Alpha
      summary: List Award Recommendations
      description: Get paginated list of award recommendations filtered by agency.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationListRequestSchema'
      security:
      - ApiJwtAuth: &id002 []
      - ApiUserKeyAuth: *id002
  /alpha/award-recommendations/{award_recommendation_id}:
    get:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationGetResponseSchema'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Award Recommendation Alpha
      summary: Get Award Recommendation
      description: Retrieve an award recommendation by ID, including opportunity details, attachments, and reviews.
      security:
      - ApiJwtAuth: &id003 []
      - ApiUserKeyAuth: *id003
    put:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationGetResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Award Recommendation Alpha
      summary: Update Award Recommendation
      description: Update an existing award recommendation with new values for fields.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationUpdateRequestSchema'
      security:
      - ApiJwtAuth: &id004 []
      - ApiUserKeyAuth: *id004
  /alpha/award-recommendations/{award_recommendation_id}/risks:
    post:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationRiskResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Award Recommendation Alpha
      summary: Create Award Recommendation Risk
      description: Create a risk for an award recommendation, linking it to application submissions.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationRiskRequestSchema'
      security:
      - ApiJwtAuth: &id005 []
      - ApiUserKeyAuth: *id005
  /alpha/award-recommendations/{award_recommendation_id}/risks/list:
    post:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationRiskListResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Award Recommendation Alpha
      summary: List Award Recommendation Risks
      description: Get paginated list of risks for an award recommendation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationRiskListRequestSchema'
      security:
      - ApiJwtAuth: &id006 []
      - ApiUserKeyAuth: *id006
  /alpha/award-recommendations/{award_recommendation_id}/audit_history:
    post:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationAuditResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Award Recommendation Alpha
      summary: List Award Recommendation Audit History
      description: Get paginated audit history for an award recommendation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationAuditRequestSchema'
      security:
      - ApiJwtAuth: &id007 []
      - ApiUserKeyAuth: *id007
  /alpha/award-recommendations/{award_recommendation_id}/submissions/list:
    post:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationSubmissionListResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Award Recommendation Alpha
      summary: List Award Recommendation Submissions
      description: Get paginated list of application submissions for an award recommendation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationSubmissionListRequestSchema'
      security:
      - ApiJwtAuth: &id008 []
      - ApiUserKeyAuth: *id008
  /alpha/award-recommendations/{award_recommendation_id}/submission-details:
    put:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationSubmissionDetailsBatchUpdateResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Internal Server Error
      tags:
      - Award Recommendation Alpha
      summary: Batch Update Award Recommendation Submission Details
      description: Update multiple submission details for an award recommendation in a single operation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationSubmissionDetailsBatchUpdateRequestSchema'
      security:
      - ApiJwtAuth: &id009 []
      - ApiUserKeyAuth: *id009
  /alpha/award-recommendations/{award_recommendation_id}/risks/{award_recommendation_risk_id}:
    put:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      - in: path
        name: award_recommendation_risk_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationRiskResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Award Recommendation Alpha
      summary: Update Award Recommendation Risk
      description: Update a risk on an award recommendation, including linked application submissions.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationRiskRequestSchema'
      security:
      - ApiJwtAuth: &id010 []
      - ApiUserKeyAuth: *id010
    delete:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      - in: path
        name: award_recommendation_risk_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationRiskDeleteResponseSchema'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Award Recommendation Alpha
      summary: Delete Award Recommendation Risk
      description: Soft delete a risk for an award recommendation.
      security:
      - ApiJwtAuth: &id011 []
      - ApiUserKeyAuth: *id011
  /alpha/award-recommendations/{award_recommendation_id}/reviews/{award_recommendation_review_id}:
    put:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      - in: path
        name: award_recommendation_review_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationReviewUpdateResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Award Recommendation Alpha
      summary: Update Award Recommendation Review
      description: Update a review on an award recommendation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRecommendationReviewUpdateRequestSchema'
      security:
      - ApiJwtAuth: &id012 []
      - ApiUserKeyAuth: *id012
  /alpha/award-recommendations/{award_recommendation_id}/attachments/{award_recommendation_attachment_id}:
    delete:
      parameters:
      - in: path
        name: award_recommendation_id
        schema:
          type: string
        required: true
      - in: path
        name: award_recommendation_attachment_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AwardRecommendationAttachmentDeleteResponseSchema'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Award Recommendation Alpha
      summary: Delete Award Recommendation Attachment
      description: Soft delete an attachment for an award recommendation.
      security:
      - ApiJwtAuth: &id013 []
      - ApiUserKeyAuth: *id013
components:
  schemas:
    SimpleUserSchema:
      type: object
      properties:
        user_id:
          type: string
          format: uuid
          description: ID of the user
          example: 123e4567-e89b-12d3-a456-426614174000
        email:
          type: string
          description: Email address of the user
          example: example@example.com
        first_name:
          type:
          - string
          - 'null'
          description: Users first name
          example: John
        last_name:
          type:
          - string
          - 'null'
          description: Users last name
          example: Smith
    AwardRecSubmissionTypeFilterSchema:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            enum:
            - recommended_for_funding
            - recommended_without_funding
            - not_recommended
            type:
            - string
    AwardRecSubmissionPaginationSchema:
      type: object
      properties:
        sort_order:
          type: array
          default:
          - order_by: application_submission_number
            sort_direction: ascending
          minItems: 1
          maxItems: 5
          description: The list of sorting rules
          items:
            type:
            - object
            $ref: '#/components/schemas/SortOrderAwardRecSubmissionPaginationSchema'
        page_size:
          type: integer
          minimum: 1
          maximum: 5000
          description: The size of the page to fetch
          example: 25
        page_offset:
          type: integer
          minimum: 1
          description: The page number to fetch, starts counting from 1
          example: 1
      required:
      - page_offset
      - page_size
    SortOrderAwardRecommendationListPaginationSchema:
      type: object
      properties:
        order_by:
          type: string
          enum:
          - created_at
          description: The field to sort the response by
        sort_direction:
          description: Whether to sort the response ascending or descending
          enum:
          - ascending
          - descending
          type:
          - string
      required:
      - order_by
      - sort_direction
    AwardRecommendationRiskListResponseSchema:
      type: object
      properties:
        pagination_info:
          description: The pagination information for paginated endpoints
          type:
          - object
          $ref: '#/components/schemas/PaginationInfoSchema'
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type: array
          description: The list of award recommendation risks
          items:
            type:
            - object
            $ref: '#/components/schemas/AwardRecommendationRiskResponseDataSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    AwardRecommendationReviewSchema:
      type: object
      properties:
        award_recommendation_review_id:
          type: string
          format: uuid
          description: The review's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        award_recommendation_review_type:
          description: The type of the review
          enum:
          - merit_review
          - application_budget_review
          - programmatic_review
          - business_and_risk_review
          type:
          - string
        is_reviewed:
          type: boolean
          description: Whether the review has been completed
    AwardRecommendationRiskDeleteResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          example: null
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    AwardRecommendationAttachmentDeleteResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          example: null
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    AwardRecommendationSubmissionDetailSchema:
      type: object
      properties:
        recommended_amount:
          type:
          - number
          - 'null'
          description: The recommended funding amount
          example: '200000.00'
        scoring_comment:
          type:
          - string
          - 'null'
          description: Comments from the scoring process
        general_comment:
          type:
          - string
          - 'null'
          description: General comments about the submission
        award_recommendation_type:
          description: The recommendation type for this submission
          enum:
          - recommended_for_funding
          - recommended_without_funding
          - not_recommended
          type:
          - string
          - 'null'
          - 'null'
        has_exception:
          type: boolean
          description: Whether the submission has an exception
        exception_detail:
          type:
          - string
          - 'null'
          description: Details about the exception, if any
    AwardRecommendationBaseSchema:
      type: object
      properties:
        award_recommendation_id:
          type: string
          format: uuid
          description: The award recommendation's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        award_recommendation_number:
          type: string
          description: The generated award recommendation number
          example: AR-26-0001
        award_recommendation_status:
          description: The status of the award recommendation
          enum:
          - draft
          - in_review
          - approved
          type:
          - string
        award_selection_method:
          description: The method used to select the award
          enum:
          - merit_review_ranking_only
          - merit_review_ranking_with_other_factors
          - formula
          - single_source
          - sole_source
          - other
          type:
          - string
          - 'null'
          - 'null'
        additional_info:
          type:
          - string
          - 'null'
          description: Additional info about the opportunity
          example: Program office requests expedited processing due to deadline in September.
        selection_method_detail:
          type:
          - string
          - 'null'
          description: Additional detail about the selection method
          example: Selection factors included technical merit, past performance, and cost.
        funding_strategy:
          type:
          - string
          - 'null'
          description: Funding strategy for award recommendations
          example: Full funding for top 10 applications, partial funding for next 15 based on available budget.
        other_key_information:
          type:
          - string
          - 'null'
          description: Other key information
          example: This opportunity aligns with the agency's rural access initiative and requires interagency coordination.
        review_workflow_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The workflow ID for the review process
          example: 123e4567-e89b-12d3-a456-426614174000
        opportunity:
          description: The associated opportunity
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationOpportunitySchema'
        award_recommendation_reviews:
          type: array
          description: Reviews associated with the award recommendation
          items:
            type:
            - object
            $ref: '#/components/schemas/AwardRecommendationReviewSchema'
    AwardRecommendationSubmissionDetailUpdateSchema:
      type: object
      properties:
        recommended_amount:
          type:
          - number
          - 'null'
          description: The recommended funding amount
          example: '200000.00'
        scoring_comment:
          type:
          - string
          - 'null'
          description: Comments from the scoring process
          example: Strong technical approach with clear methodology. Budget well-justified and aligned with project goals.
        general_comment:
          type:
          - string
          - 'null'
          description: General comments about the submission
          example: Applicant has demonstrated successful implementation of similar projects in the past. Team qualifications exceed requirements.
        award_recommendation_type:
          description: The recommendation type for this submission
          enum:
          - recommended_for_funding
          - recommended_without_funding
          - not_recommended
          type:
          - string
          - 'null'
          - 'null'
        has_exception:
          type: boolean
          description: Whether the submission has an exception
        exception_detail:
          type:
          - string
          - 'null'
          description: Details about the exception, if any
          example: Budget exceeds guidelines by 12%. Recommend partial funding with revised scope focusing on core deliverables.
    AwardRecommendationApplicationSchema:
      type: object
      properties:
        application_id:
          type: string
          format: uuid
          description: The application ID
          example: 123e4567-e89b-12d3-a456-426614174000
        competition_id:
          type: string
          format: uuid
          description: The competition ID
          example: 123e4567-e89b-12d3-a456-426614174000
        organization:
          description: The organization that submitted the application
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/AwardRecommendationOrganizationSchema'
          - type: 'null'
    ValidationIssueSchema:
      type: object
      properties:
        type:
          type: string
          description: The type of error
          example: invalid
        message:
          type: string
          description: The message to return
          example: Not a valid string.
        field:
          type: string
          description: The field that failed
          example: summary.summary_description
        value:
          type: string
          description: The value that failed
          example: invalid string
    AwardRecommendationAuditAttachmentSchema:
      type: object
      properties:
        award_recommendation_attachment_id:
          type: string
          format: uuid
          description: The attachment's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        file_name:
          type: string
          description: The file name of the attachment
          example: my_example.pdf
        award_recommendation_attachment_type:
          description: The type of the attachment
          enum:
          - standard_terms
          - standard_conditions
          - program_terms
          - program_conditions
          - other
          type:
          - string
        is_deleted:
          type: boolean
          description: Whether the attachment has been deleted
    AwardRecRiskPaginationSchema:
      type: object
      properties:
        sort_order:
          type: array
          default:
          - order_by: created_at
            sort_direction: ascending
          minItems: 1
          maxItems: 5
          description: The list of sorting rules
          items:
            type:
            - object
            $ref: '#/components/schemas/SortOrderAwardRecRiskPaginationSchema'
        page_size:
          type: integer
          minimum: 1
          maximum: 5000
          description: The size of the page to fetch
          example: 25
        page_offset:
          type: integer
          minimum: 1
          description: The page number to fetch, starts counting from 1
          example: 1
      required:
      - page_offset
      - page_size
    AwardRecommendationSubmissionDataSchema:
      type: object
      properties:
        award_recommendation_application_submission_id:
          type: string
          format: uuid
          description: The award recommendation application submission ID
          example: 123e4567-e89b-12d3-a456-426614174000
        application_submission:
          description: The application submission
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationApplicationSubmissionSchema'
        submission_detail:
          description: The recommendation details for this submission
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationSubmissionDetailSchema'
    AwardRecSubmissionExceptionFilterSchema:
      type: object
      properties:
        one_of:
          type:
          - array
          - 'null'
          items:
            type: boolean
    AwardRecommendationReviewUpdateResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          description: The updated review
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationReviewSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    AwardRecommendationUpdateRequestSchema:
      type: object
      properties:
        award_selection_method:
          description: The method used to select the award
          enum:
          - merit_review_ranking_only
          - merit_review_ranking_with_other_factors
          - formula
          - single_source
          - sole_source
          - other
          type:
          - string
        additional_info:
          type:
          - string
          - 'null'
          description: Additional info about the award recommendation
          example: Program office requests expedited processing due to deadline in September.
        funding_strategy:
          type:
          - string
          - 'null'
          description: Funding strategy information for the award recommendation
          example: Full funding for top 10 applications, partial funding for next 15 based on available budget.
        selection_method_detail:
          type:
          - string
          - 'null'
          description: Additional details about the selection method
          example: Top-ranked applicants based on expert panel scores
        other_key_information:
          type:
          - string
          - 'null'
          description: Other key information for the award recommendation
          example: This opportunity aligns with the agency's rural access initiative and requires interagency coordination.
      required:
      - award_selection_method
    AwardRecommendationOrganizationSchema:
      type: object
      properties:
        organization_id:
          type: string
          format: uuid
          description: The organization ID
          example: 123e4567-e89b-12d3-a456-426614174000
        organization_name:
          type:
          - string
          - 'null'
          description: The organization name
    AwardRecommendationOpportunitySchema:
      type: object
      properties:
        opportunity_id:
          type: string
          format: uuid
          description: The opportunity ID
          example: 123e4567-e89b-12d3-a456-426614174000
        opportunity_number:
          type:
          - string
          - 'null'
          description: The opportunity number
          example: O-BJA-2025-202930-STG
        opportunity_title:
          type:
          - string
          - 'null'
          description: The title of the opportunity
          example: Research into conservation techniques
        summary:
          description: Summary details of the opportunity
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/AwardRecommendationOpportunitySummarySchema'
          - type: 'null'
    PaginationInfoSchema:
      type: object
      properties:
        page_offset:
          type: integer
          description: The page number that was fetched
          example: 1
        page_size:
          type: integer
          description: The size of the page fetched
          example: 25
        total_records:
          type: integer
          description: The total number of records fetchable
          example: 42
        total_pages:
          type: integer
          description: The total number of pages that can be fetched
          example: 2
        sort_order:
          type: array
          description: The sort order passed in originally
          items:
            type:
            - object
            $ref: '#/components/schemas/SortOrderSchema'
    AwardRecommendationSubmissionListRequestSchema:
      type: object
      properties:
        filters:
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationSubmissionFilterSchema'
        pagination:
          type:
          - object
          $ref: '#/components/schemas/AwardRecSubmissionPaginationSchema'
      required:
      - pagination
    AwardRecommendationAuditReviewSchema:
      type: object
      properties:
        award_recommendation_review_id:
          type: string
          format: uuid
          description: The review's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        is_reviewed:
          type: boolean
          description: Whether the review has been completed
    AwardRecommendationListAgencyIdFilterSchema:
      type: object
      properties:
        one_of:
          type:
          - array
          - 'null'
          minItems: 1
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
    AwardRecommendationAuditRequestSchema:
      type: object
      properties:
        filters:
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/AwardRecommendationAuditFilterSchema'
          - type: 'null'
        pagination:
          type:
          - object
          $ref: '#/components/schemas/AwardRecAuditPaginationSchema'
      required:
      - pagination
    AwardRecommendationAuditFilterSchema:
      type: object
      properties:
        award_recommendation_audit_event:
          type:
          - object
          $ref: '#/components/schemas/AwardRecAuditEventFilterSchema'
    AwardRecommendationListRequestSchema:
      type: object
      properties:
        filters:
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationListFilterSchema'
        pagination:
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationListPaginationSchema'
      required:
      - filters
      - pagination
    AwardRecommendationGetResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          description: The award recommendation details
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationWithAttachmentsSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    AwardRecommendationAuditWorkflowApprovalSchema:
      type: object
      properties:
        workflow_approval_id:
          type: string
          format: uuid
          description: The workflow approval's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        workflow_id:
          type: string
          format: uuid
          description: The workflow ID
          example: 123e4567-e89b-12d3-a456-426614174000
        approval_type:
          description: The type of approval
          enum:
          - initial_prototype_approval
          - program_officer_approval
          - budget_officer_approval
          type:
          - string
        approval_response_type:
          description: The approval response type
          enum:
          - approved
          - declined
          - requires_modification
          type:
          - string
    AwardRecommendationAuditRiskSchema:
      type: object
      properties:
        award_recommendation_risk_id:
          type: string
          format: uuid
          description: The risk's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        award_recommendation_risk_type:
          description: The type of risk
          enum:
          - additional_monitoring
          type:
          - string
        award_recommendation_risk_number:
          type: string
          description: The risk number
        is_deleted:
          type: boolean
          description: Whether the risk has been deleted
    SortOrderAwardRecAuditPaginationSchema:
      type: object
      properties:
        order_by:
          type: string
          enum:
          - created_at
          description: The field to sort the response by
        sort_direction:
          description: Whether to sort the response ascending or descending
          enum:
          - ascending
          - descending
          type:
          - string
      required:
      - order_by
      - sort_direction
    AwardRecommendationSubmissionDetailsBatchUpdateRequestSchema:
      type: object
      properties:
        award_recommendation_submissions:
          type: object
          minLength: 1
          description: Dictionary of submission IDs to update details, where keys are award_recommendation_application_submission_id
          additionalProperties:
            type:
            - object
            $ref: '#/components/schemas/AwardRecommendationSubmissionDetailUpdateSchema'
      required:
      - award_recommendation_submissions
    AwardRecommendationOpportunitySummarySchema:
      type: object
      properties:
        opportunity_status:
          description: The status of the opportunity
          enum:
          - forecasted
          - posted
          - closed
          - archived
          type:
          - string
          - 'null'
          - 'null'
        summary_description:
          type:
          - string
          - 'null'
          description: The summary of the opportunity
          example: This opportunity aims to unravel the mysteries of the universe.
    AwardRecommendationSubmissionFilterSchema:
      type: object
      properties:
        award_recommendation_type:
          type:
          - object
          $ref: '#/components/schemas/AwardRecSubmissionTypeFilterSchema'
        has_exception:
          type:
          - object
          $ref: '#/components/schemas/AwardRecSubmissionExceptionFilterSchema'
    AwardRecommendationListPaginationSchema:
      type: object
      properties:
        sort_order:
          type: array
          default:
          - order_by: created_at
            sort_direction: descending
          minItems: 1
          maxItems: 5
          description: The list of sorting rules
          items:
            type:
            - object
            $ref: '#/components/schemas/SortOrderAwardRecommendationListPaginationSchema'
        page_size:
          type: integer
          minimum: 1
          maximum: 5000
          description: The size of the page to fetch
          example: 25
        page_offset:
          type: integer
          minimum: 1
          description: The page number to fetch, starts counting from 1
          example: 1
      required:
      - page_offset
      - page_size
    AwardRecommendationListFilterSchema:
      type: object
      properties:
        agency_id:
          description: Filter award recommendations by agency. The user must have the view_award_recommendation privilege in each agency listed.
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationListAgencyIdFilterSchema'
      required:
      - agency_id
    AwardRecommendationSubmissionListResponseSchema:
      type: object
      properties:
        pagination_info:
          description: The pagination information for paginated endpoints
          type:
          - object
          $ref: '#/components/schemas/PaginationInfoSchema'
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type: array
          description: The list of award recommendation submissions
          items:
            type:
            - object
            $ref: '#/components/schemas/AwardRecommendationSubmissionDataSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    AwardRecommendationWithAttachmentsSchema:
      type: object
      properties:
        award_recommendation_id:
          type: string
          format: uuid
          description: The award recommendation's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        award_recommendation_number:
          type: string
          description: The generated award recommendation number
          example: AR-26-0001
        award_recommendation_status:
          description: The status of the award recommendation
          enum:
          - draft
          - in_review
          - approved
          type:
          - string
        award_selection_method:
          description: The method used to select the award
          enum:
          - merit_review_ranking_only
          - merit_review_ranking_with_other_factors
          - formula
          - single_source
          - sole_source
          - other
          type:
          - string
          - 'null'
          - 'null'
        additional_info:
          type:
          - string
          - 'null'
          description: Additional info about the opportunity
          example: Program office requests expedited processing due to deadline in September.
        selection_method_detail:
          type:
          - string
          - 'null'
          description: Additional detail about the selection method
          example: Selection factors included technical merit, past performance, and cost.
        funding_strategy:
          type:
          - string
          - 'null'
          description: Funding strategy for award recommendations
          example: Full funding for top 10 applications, partial funding for next 15 based on available budget.
        other_key_information:
          type:
          - string
          - 'null'
          description: Other key information
          example: This opportunity aligns with the agency's rural access initiative and requires interagency coordination.
        review_workflow_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The workflow ID for the review process
          example: 123e4567-e89b-12d3-a456-426614174000
        opportunity:
          description: The associated opportunity
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationOpportunitySchema'
        award_recommendation_reviews:
          type: array
          description: Reviews associated with the award recommendation
          items:
            type:
            - object
            $ref: '#/components/schemas/AwardRecommendationReviewSchema'
        award_recommendation_attachments:
          type: array
          description: Attachments associated with the award recommendation
          items:
            type:
            - object
            $ref: '#/components/schemas/AwardRecommendationAttachmentSchema'
    SortOrderAwardRecRiskPaginationSchema:
      type: object
      properties:
        order_by:
          type: string
          enum:
          - created_at
          description: The field to sort the response by
        sort_direction:
          description: Whether to sort the response ascending or descending
          enum:
          - ascending
          - descending
          type:
          - string
      required:
      - order_by
      - sort_direction
    AwardRecommendationRiskResponseDataSchema:
      type: object
      properties:
        award_recommendation_risk_id:
          type: string
          format: uuid
          description: The award recommendation risk ID
          example: 123e4567-e89b-12d3-a456-426614174000
        comment:
          type: string
          description: Summary of the risk
          example: Applicant has unresolved audit findings
        award_recommendation_risk_number:
          type: string
          description: The generated risk number
          example: HHS-00012345
        award_recommendation_risk_type:
          description: The type of risk
          enum:
          - additional_monitoring
          type:
          - string
        award_recommendation_application_submission_ids:
          type: array
          description: List of award recommendation application submission IDs linked to this risk
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
        applications:
          type: array
          description: List of application submissions linked to this risk
          example:
          - application_submission_id: 123e4567-e89b-12d3-a456-426614174000
            application_submission_number: GRANT-2024-001
          items:
            type:
            - object
            $ref: '#/components/schemas/ApplicationSubmissionInfoSchema'
    AwardRecommendationCreateRequestSchema:
      type: object
      properties:
        opportunity_id:
          type: string
          format: uuid
          description: The opportunity ID for the award recommendation
          example: 123e4567-e89b-12d3-a456-426614174000
        award_selection_method:
          description: The method used to select the award
          enum:
          - merit_review_ranking_only
          - merit_review_ranking_with_other_factors
          - formula
          - single_source
          - sole_source
          - other
          type:
          - string
        additional_info:
          type:
          - string
          - 'null'
          description: Additional info about the award recommendation
          example: Program office requests expedited processing due to deadline in September.
        funding_strategy:
          type:
          - string
          - 'null'
          description: Funding strategy information for the award recommendation
          example: Full funding for top 10 applications, partial funding for next 15 based on available budget.
        selection_method_detail:
          type:
          - string
          - 'null'
          description: Additional details about the selection method
          example: Top-ranked applicants based on expert panel scores
        other_key_information:
          type:
          - string
          - 'null'
          description: Other key information for the award recommendation
          example: This opportunity aligns with the agency's rural access initiative and requires interagency coordination.
      required:
      - award_selection_method
      - opportunity_id
    AwardRecAuditEventFilterSchema:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            example:
            - award_recommendation_created
            enum:
            - award_recommendation_created
            - award_recommendation_updated
            - attachment_created
            - attachment_updated
            - attachment_deleted
            - exception_created
            - exception_updated
            - exception_deleted
            - risk_created
            - risk_updated
            - risk_deleted
            - application_submission_updated
            - award_recommendation_submission_updated
            - review_created
            - review_updated
            - review_deleted
            type:
            - string
    AwardRecommendationAttachmentSchema:
      type: object
      properties:
        award_recommendation_attachment_id:
          type: string
          format: uuid
          description: The attachment's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        download_path:
          type: string
          description: The presigned URL to download the attachment
          example: https://s3.amazonaws.com/bucket/path/to/my_example.pdf
        file_name:
          type: string
          description: The file name of the attachment
          example: my_example.pdf
        award_recommendation_attachment_type:
          description: The type of the attachment
          enum:
          - standard_terms
          - standard_conditions
          - program_terms
          - program_conditions
          - other
          type:
          - string
        uploading_user:
          description: The user who uploaded the attachment
          type:
          - object
          $ref: '#/components/schemas/SimpleUserSchema'
        created_at:
          type: string
          format: date-time
          description: When the attachment was created
        updated_at:
          type: string
          format: date-time
          description: When the attachment was last updated
    AwardRecAuditPaginationSchema:
      type: object
      properties:
        sort_order:
          type: array
          default:
          - order_by: created_at
            sort_direction: descending
          minItems: 1
          maxItems: 5
          description: The list of sorting rules
          items:
            type:
            - object
            $ref: '#/components/schemas/SortOrderAwardRecAuditPaginationSchema'
        page_size:
          type: integer
          minimum: 1
          maximum: 5000
          description: The size of the page to fetch
          example: 25
        page_offset:
          type: integer
          minimum: 1
          description: The page number to fetch, starts counting from 1
          example: 1
      required:
      - page_offset
      - page_size
    AwardRecommendationSubmissionDetailsBatchUpdateResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type: array
          description: The updated award recommendation submissions
          items:
            type:
            - object
            $ref: '#/components/schemas/AwardRecommendationSubmissionDataSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    ApplicationSubmissionInfoSchema:
      type: object
      properties:
        award_recommendation_application_submission_id:
          type: string
          format: uuid
          description: The award recommendation application submission ID
          example: 123e4567-e89b-12d3-a456-426614174000
        application_submission_id:
          type: string
          format: uuid
          description: The application submission ID
          example: 123e4567-e89b-12d3-a456-426614174000
        application_submission_number:
          type: string
          description: The application submission number
          example: GRANT-2024-001
    AwardRecommendationRiskRequestSchema:
      type: object
      properties:
        comment:
          type: string
          description: Summary of the risk
          example: Applicant has unresolved audit findings
        award_recommendation_risk_type:
          description: The type of risk
          enum:
          - additional_monitoring
          type:
          - string
        award_recommendation_application_submission_ids:
          type: array
          minItems: 1
          description: List of award recommendation application submission IDs to link to this risk
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
      required:
      - award_recommendation_application_submission_ids
      - award_recommendation_risk_type
      - comment
    AwardRecommendationRiskResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          description: The award recommendation risk
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationRiskResponseDataSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    AwardRecommendationAuditResponseSchema:
      type: object
      properties:
        pagination_info:
          description: The pagination information for paginated endpoints
          type:
          - object
          $ref: '#/components/schemas/PaginationInfoSchema'
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type: array
          items:
            type:
            - object
            $ref: '#/components/schemas/AwardRecommendationAuditDataSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    AwardRecommendationApplicationSubmissionSchema:
      type: object
      properties:
        application_submission_id:
          type: string
          format: uuid
          description: The application submission ID
          example: 123e4567-e89b-12d3-a456-426614174000
        application_submission_number:
          type:
          - string
          - 'null'
          description: The application submission number
          example: SUB-2026-00001
        project_title:
          type:
          - string
          - 'null'
          description: The project title
          example: Rural broadband expansion initiative
        total_requested_amount:
          type:
          - number
          - 'null'
          description: The total requested funding amount
          example: '250000.00'
        application:
          description: The application associated with this submission
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationApplicationSchema'
    AwardRecommendationListResponseSchema:
      type: object
      properties:
        pagination_info:
          description: The pagination information for paginated endpoints
          type:
          - object
          $ref: '#/components/schemas/PaginationInfoSchema'
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type: array
          description: The list of award recommendations
          items:
            type:
            - object
            $ref: '#/components/schemas/AwardRecommendationBaseSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    AwardRecommendationAuditDataSchema:
      type: object
      properties:
        award_recommendation_audit_id:
          type: string
          format: uuid
          description: The ID of the audit event
          example: 123e4567-e89b-12d3-a456-426614174000
        award_recommendation_audit_event:
          description: The type of audit event recorded
          enum:
          - award_recommendation_created
          - award_recommendation_updated
          - attachment_created
          - attachment_updated
          - attachment_deleted
          - exception_created
          - exception_updated
          - exception_deleted
          - risk_created
          - risk_updated
          - risk_deleted
          - application_submission_updated
          - award_recommendation_submission_updated
          - review_created
          - review_updated
          - review_deleted
          type:
          - string
        user:
          description: The user who performed the audited action
          type:
          - object
          $ref: '#/components/schemas/SimpleUserSchema'
        award_recommendation_risk:
          description: The risk affected by this event (if applicable)
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/AwardRecommendationAuditRiskSchema'
          - type: 'null'
        award_recommendation_attachment:
          description: The attachment affected by this event (if applicable)
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/AwardRecommendationAuditAttachmentSchema'
          - type: 'null'
        award_recommendation_review:
          description: The review affected by this event (if applicable)
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/AwardRecommendationAuditReviewSchema'
          - type: 'null'
        award_recommendation_application_submission:
          description: The application submission affected by this event (if applicable)
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/AwardRecommendationAuditAppSubmissionSchema'
          - type: 'null'
        workflow_approval:
          description: The workflow approval affected by this event (if applicable)
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/AwardRecommendationAuditWorkflowApprovalSchema'
          - type: 'null'
        audit_metadata:
          type:
          - object
          - 'null'
          description: Additional metadata about the audit event
          additionalProperties: {}
        created_at:
          type: string
          format: date-time
          description: When the audit event was created
    AwardRecommendationRiskListRequestSchema:
      type: object
      properties:
        pagination:
          type:
          - object
          $ref: '#/components/schemas/AwardRecRiskPaginationSchema'
      required:
      - pagination
    ErrorResponseSchema:
      type: object
      properties:
        data:
          description: Additional data that might be useful in resolving an error (see specific endpoints for details, this is used infrequently)
          example: {}
        message:
          type: string
          description: General description of the error
          example: Error
        status_code:
          type: integer
          description: The HTTP status code of the error
        errors:
          type: array
          example: []
          items:
            type:
            - object
            $ref: '#/components/schemas/ValidationIssueSchema'
        internal_request_id:
          type: string
          description: An internal tracking ID
          example: 550e8400-e29b-41d4-a716-446655440000
    SortOrderAwardRecSubmissionPaginationSchema:
      type: object
      properties:
        order_by:
          type: string
          enum:
          - application_submission_number
          description: The field to sort the response by
        sort_direction:
          description: Whether to sort the response ascending or descending
          enum:
          - ascending
          - descending
          type:
          - string
      required:
      - order_by
      - sort_direction
    SortOrderSchema:
      type: object
      properties:
        order_by:
          type: string
          description: The field that the records were sorted by
          example: id
        sort_direction:
          description: The direction the records are sorted
          enum:
          - ascending
          - descending
          type:
          - string
    AwardRecommendationAuditAppSubmissionSchema:
      type: object
      properties:
        award_recommendation_application_submission_id:
          type: string
          format: uuid
          description: The award recommendation application submission's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        application_submission_id:
          type: string
          format: uuid
          description: The application submission ID
          example: 123e4567-e89b-12d3-a456-426614174000
        application_submission_number:
          type:
          - string
          - 'null'
          description: The application submission number
    AwardRecommendationReviewUpdateRequestSchema:
      type: object
      properties:
        is_reviewed:
          type: boolean
          description: Whether the review has been completed
      required:
      - is_reviewed
  securitySchemes:
    ApiJwtAuth:
      type: apiKey
      in: header
      name: X-SGG-Token
    InternalApiJwtAuth:
      type: apiKey
      in: header
      name: X-SGG-Internal-Token
    ApiUserKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key