HHS (US Department of Health and Human Services) Award Recommendation Alpha API

openapi: 3.2.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: []
      - ApiUserKeyAuth: []
  /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: []
      - ApiUserKeyAuth: []
  /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: []
      - ApiUserKeyAuth: []
    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: []
      - ApiUserKeyAuth: []
  /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: []
      - ApiUserKeyAuth: []
  /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: []
      - ApiUserKeyAuth: []
  /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: []
      - ApiUserKeyAuth: []
  /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: []
      - ApiUserKeyAuth: []
  /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: []
      - ApiUserKeyAuth: []
  /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: []
      - ApiUserKeyAuth: []
    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: []
      - ApiUserKeyAuth: []
  /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: []
      - ApiUserKeyAuth: []
  /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: []
      - ApiUserKeyAuth: []
components:
  schemas:
    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
    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.
    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
    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
    AwardRecommendationListRequestSchema:
      type: object
      properties:
        filters:
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationListFilterSchema'
        pagination:
          type:
          - object
          $ref: '#/components/schemas/AwardRecommendationListPaginationSchema'
      required:
      - filters
      - pagination
    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
    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
    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
    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'
    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
    AwardRecSubmissionTypeFilterSchema:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            enum:
            - recommended_for_funding
            - recommended_without_funding
            - not_recommended
            type:
            - string
    AwardRecommendationReviewUpdateRequestSchema:
      type: object
      properties:
        is_reviewed:
          type: boolean
          description: Whether the review has been completed
      required:
      - is_reviewed
    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
    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
    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
    AwardRecommendationSubmissionFilterSchema:
      type: object
    

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hhs/refs/heads/main/openapi/hhs-award-recommendation-alpha-api-openapi.yml