openapi.generated.yml

info:
  description: '

    Back end API for simpler.grants.gov.


    This API is an ALPHA VERSION! Its current form is primarily for testing and feedback.
    Features are still under heavy development, and subject to change. Not for production
    use.


    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 API
  version: v0
tags:
- name: Health
- name: Opportunity v1
- name: Extract v1
- name: Agency v1
- name: User v1
servers: .
paths:
  /health:
    get:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthcheckResponse'
          description: Successful response
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service Unavailable
      tags:
      - Health
      summary: Health
  /v1/extracts:
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractMetadataListResponse'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
      tags:
      - Extract v1
      summary: Extract Metadata Get
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractMetadataRequest'
            examples:
              example1:
                summary: No filters
                value:
                  pagination:
                    order_by: created_at
                    page_offset: 1
                    page_size: 25
                    sort_direction: descending
      security:
      - ApiKeyAuth: []
  /v1/agencies:
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgencyListResponse'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
      tags:
      - Agency v1
      summary: Agencies Get
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgencyListRequest'
            examples:
              example1:
                summary: No filters
                value:
                  pagination:
                    order_by: created_at
                    page_offset: 1
                    page_size: 25
                    sort_direction: descending
      security:
      - ApiKeyAuth: []
  /v1/users/login:
    get:
      parameters: []
      responses:
        '302':
          content:
            application/json:
              schema: {}
          description: Found
      tags:
      - User v1
      summary: User Login
      description: '

        To use this endpoint, click [this link](/v1/users/login) which will redirect

        you to an OAuth provider where you can sign into an account.


        Do not try to use the execute option below as OpenAPI will not redirect your
        browser for you.


        The token you receive can then be set to the X-SGG-Token header for authenticating
        with endpoints.

        '
  /v1/users/token/logout:
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserTokenLogoutResponse'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
      tags:
      - User v1
      summary: User Token Logout
      security:
      - ApiJwtAuth: []
  /v1/users/token/refresh:
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserTokenRefreshResponse'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
      tags:
      - User v1
      summary: User Token Refresh
      security:
      - ApiJwtAuth: []
  /v1/opportunities/search:
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunitySearchResponseV1'
            application/octet-stream: {}
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
      tags:
      - Opportunity v1
      summary: Opportunity Search
      description: '

        __ALPHA VERSION__


        This endpoint in its current form is primarily for testing and feedback.


        Features in this endpoint are still under heavy development, and subject to
        change. Not for production use.


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

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpportunitySearchRequestV1'
            examples:
              example1:
                summary: No filters
                value:
                  pagination:
                    order_by: opportunity_id
                    page_offset: 1
                    page_size: 25
                    sort_direction: ascending
              example2:
                summary: All filters
                value:
                  query: research
                  filters:
                    agency:
                      one_of:
                      - USAID
                      - DOC
                    applicant_type:
                      one_of:
                      - state_governments
                      - county_governments
                      - individuals
                    funding_category:
                      one_of:
                      - recovery_act
                      - arts
                      - natural_resources
                    funding_instrument:
                      one_of:
                      - cooperative_agreement
                      - grant
                    opportunity_status:
                      one_of:
                      - forecasted
                      - posted
                    post_date:
                      start_date: '2024-01-01'
                      end_date: '2024-02-01'
                    close_date:
                      start_date: '2024-01-01'
                  pagination:
                    order_by: opportunity_id
                    page_offset: 1
                    page_size: 25
                    sort_direction: descending
              example3:
                summary: Query & opportunity_status filters
                value:
                  query: research
                  filters:
                    opportunity_status:
                      one_of:
                      - forecasted
                      - posted
                  pagination:
                    order_by: opportunity_id
                    page_offset: 1
                    page_size: 25
                    sort_direction: descending
              example4:
                summary: CSV file response
                value:
                  format: csv
                  filters:
                    opportunity_status:
                      one_of:
                      - forecasted
                      - posted
                  pagination:
                    order_by: opportunity_id
                    page_offset: 1
                    page_size: 100
                    sort_direction: ascending
              example5:
                summary: Filter by award fields
                value:
                  filters:
                    expected_number_of_awards:
                      min: 5
                    award_floor:
                      min: 10000
                    award_ceiling:
                      max: 1000000
                    estimated_total_program_funding:
                      min: 100000
                      max: 250000
                  pagination:
                    order_by: opportunity_id
                    page_offset: 1
                    page_size: 25
                    sort_direction: descending
              example6:
                summary: FIlter by assistance listing numbers
                value:
                  filters:
                    assistance_listing_number:
                      one_of:
                      - '43.001'
                      - '47.049'
                  pagination:
                    order_by: opportunity_id
                    page_offset: 1
                    page_size: 25
                    sort_direction: descending
      security:
      - ApiKeyAuth: []
  /v1/users/{user_id}:
    get:
      parameters:
      - in: path
        name: user_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGetResponse'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
      tags:
      - User v1
      summary: User Get
      security:
      - ApiJwtAuth: []
  /v1/opportunities/{opportunity_id}:
    get:
      parameters:
      - in: path
        name: opportunity_id
        schema:
          type: integer
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunityGetResponseV1'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
      tags:
      - Opportunity v1
      summary: Opportunity Get
      description: '

        __ALPHA VERSION__


        This endpoint in its current form is primarily for testing and feedback.


        Features in this endpoint are still under heavy development, and subject to
        change. Not for production use.


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

        '
      security:
      - ApiKeyAuth: []
  /v1/users/{user_id}/saved-searches:
    get:
      parameters:
      - in: path
        name: user_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSavedSearchesResponse'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
      tags:
      - User v1
      summary: User Get Saved Searches
      security:
      - ApiJwtAuth: []
    post:
      parameters:
      - in: path
        name: user_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSaveSearchResponse'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
      tags:
      - User v1
      summary: User Save Search
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSaveSearchRequest'
      security:
      - ApiJwtAuth: []
  /v1/users/{user_id}/saved-opportunities:
    get:
      parameters:
      - in: path
        name: user_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSavedOpportunitiesResponse'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
      tags:
      - User v1
      summary: User Get Saved Opportunities
      security:
      - ApiJwtAuth: []
    post:
      parameters:
      - in: path
        name: user_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSaveOpportunityResponse'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
      tags:
      - User v1
      summary: User Save Opportunity
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSaveOpportunityRequest'
      security:
      - ApiJwtAuth: []
  /v1/opportunities/{opportunity_id}/versions:
    get:
      parameters:
      - in: path
        name: opportunity_id
        schema:
          type: integer
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunityVersionsGetResponseV1'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
      tags:
      - Opportunity v1
      summary: Opportunity Versions Get
      description: '

        __ALPHA VERSION__


        This endpoint in its current form is primarily for testing and feedback.


        Features in this endpoint are still under heavy development, and subject to
        change. Not for production use.


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

        '
      security:
      - ApiKeyAuth: []
  /v1/users/{user_id}/saved-searches/{saved_search_id}:
    delete:
      parameters:
      - in: path
        name: user_id
        schema:
          type: string
        required: true
      - in: path
        name: saved_search_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDeleteSavedSearchResponse'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
      tags:
      - User v1
      summary: User Delete Saved Search
      security:
      - ApiJwtAuth: []
  /v1/users/{user_id}/saved-opportunities/{opportunity_id}:
    delete:
      parameters:
      - in: path
        name: user_id
        schema:
          type: string
        required: true
      - in: path
        name: opportunity_id
        schema:
          type: integer
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDeleteSavedOpportunityResponse'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
      tags:
      - User v1
      summary: User Delete Saved Opportunity
      security:
      - ApiJwtAuth: []
openapi: 3.1.0
components:
  schemas:
    HealthcheckMetadata:
      type: object
      properties:
        commit_sha:
          type: string
          description: The github commit sha for the latest deployed commit
          example: ffaca647223e0b6e54344122eefa73401f5ec131
        commit_link:
          type: string
          description: A github link to the latest deployed commit
          example: https://github.com/HHS/simpler-grants-gov/commit/main
        release_notes_link:
          type: string
          description: A github link to the release notes - direct if the latest deploy
            was a release
          example: https://github.com/HHS/simpler-grants-gov/releases
        last_deploy_time:
          type: string
          format: date-time
          description: Latest deploy time in US/Eastern timezone
        deploy_whoami:
          type: string
          description: The latest user to deploy the application
          example: runner
    HealthcheckResponse:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/HealthcheckMetadata'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    ValidationIssue:
      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
    ErrorResponse:
      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
            allOf:
            - $ref: '#/components/schemas/ValidationIssue'
        internal_request_id:
          type: string
          description: An internal tracking ID
          example: 550e8400-e29b-41d4-a716-446655440000
    DateRange:
      type: object
      properties:
        start_date:
          type:
          - string
          - 'null'
          format: date
        end_date:
          type:
          - string
          - 'null'
          format: date
      required:
      - end_date
      - start_date
    ExtractMetadataFilterV1:
      type: object
      properties:
        extract_type:
          description: The type of extract to filter by
          example: opportunities_json
          enum:
          - opportunities_json
          - opportunities_csv
          type:
          - string
          - 'null'
          - 'null'
        created_at:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/DateRange'
    ExtractMetadataPaginationV1:
      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
        page_size:
          type: integer
          minimum: 1
          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:
      - order_by
      - page_offset
      - page_size
      - sort_direction
    ExtractMetadataRequest:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          description: The REST resource object
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
        filters:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/ExtractMetadataFilterV1'
        pagination:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/ExtractMetadataPaginationV1'
      required:
      - pagination
    PaginationInfo:
      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
        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
    ExtractMetadataResponse:
      type: object
      properties:
        download_path:
          type: string
          description: The file's download path
        file_size_bytes:
          type: integer
          description: The size of the file in bytes
          example: 1024
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        extract_metadata_id:
          type: integer
          description: The ID of the extract metadata
          example: 1
        extract_type:
          type: string
          description: The type of extract
          example: opportunity_data_extract
    ExtractMetadataListResponse:
      type: object
      properties:
        pagination_info:
          description: The pagination information for paginated endpoints
          type: &id001
          - object
          allOf:
          - $ref: '#/components/schemas/PaginationInfo'
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type: array
          description: A list of extract metadata records
          items:
            type:
            - object
            allOf:
            - $ref: '#/components/schemas/ExtractMetadataResponse'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    AgencyFilterV1:
      type: object
      properties:
        agency_id:
          type: integer
    AgencyPaginationV1:
      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
        page_size:
          type: integer
          minimum: 1
          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:
      - order_by
      - page_offset
      - page_size
      - sort_direction
    AgencyListRequest:
      type: object
      properties:
        filters:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/AgencyFilterV1'
        pagination:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/AgencyPaginationV1'
      required:
      - pagination
    AgencyContactInfo:
      type: object
      properties:
        contact_name:
          type: string
          description: Full name of the agency contact person
        address_line_1:
          type: string
          description: Primary street address of the agency
        address_line_2:
          type:
          - string
          - 'null'
          description: Additional address information (suite, unit, etc.)
        city:
          type: string
          description: City where the agency is located
        state:
          type: string
          description: State where the agency is located
        zip_code:
          type: string
          description: Postal code for the agency address
        phone_number:
          type: string
          description: Contact phone number for the agency
        primary_email:
          type: string
          description: Main email address for agency communications
        secondary_email:
          type:
          - string
          - 'null'
          description: Alternative email address for agency communications
    AgencyResponse:
      type: object
      properties:
        agency_id:
          type: integer
        agency_name:
          type: string
        agency_code:
          type: string
        sub_agency_code:
          type:
          - string
          - 'null'
        assistance_listing_number:
          type: string
        agency_submission_notification_setting:
          type: string
        top_level_agency:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/AgencyResponse'
        agency_contact_info:
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/AgencyContactInfo'
          - type: 'null'
        agency_download_file_types:
          type: array
          description: List of download file types supported by the agency
          items:
            enum:
            - xml
            - pdf
            type:
            - string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    AgencyListResponse:
      type: object
      properties:
        pagination_info:
          description: The pagination information for paginated endpoints
          type: *id001
          allOf:
          - $ref: '#/components/schemas/PaginationInfo'
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type: array
          description: A list of agency records
          items:
            type:
            - object
            allOf:
            - $ref: '#/components/schemas/AgencyResponse'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    UserTokenLogoutResponse:
      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
    UserTokenRefreshResponse:
      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
    FundingInstrumentFilterV1:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            enum:
            - cooperative_agreement
            - grant
            - procurement_contract
            - other
            type:
            - string
    FundingCategoryFilterV1:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            enum:
            - recovery_act
            - agriculture
            - arts
            - business_and_commerce
            - community_development
            - consumer_protection
            - disaster_prevention_and_relief
            - education
            - employment_labor_and_training
            - energy
            - environment
            - food_and_nutrition
            - health
            - housing
            - humanities
            - infrastructure_investment_and_jobs_act
            - information_and_statistics
            - income_security_and_social_services
            - law_justice_and_legal_services
            - natural_resources
            - opportunity_zone_benefits
            - regional_development
            - science_technology_and_other_research_and_development
            - transportation
            - affordable_care_act
            - other
            type:
            - string
    ApplicantTypeFilterV1:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            enum:
            - state_governments
            - county_governments
            - city_or_township_governments
            - special_district_governments
            - independent_school_districts
            - public_and_state_institutions_of_higher_education
            - private_institutions_of_higher_education
            - federally_recognized_native_american_tribal_governments
            - other_native_american_tribal_organizations
            - public_and_indian_housing_authorities
            - nonprofits_non_higher_education_with_501c3
            - nonprofits_non_higher_education_without_501c3
            - individuals
            - for_profit_organizations_other_than_small_businesses
            - small_businesses
            - other
            - unrestricted
            type:
            - string
    OpportunityStatusFilterV1:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            enum:
            - forecasted
            - posted
            - closed
            - archived
            type:
            - string
    AgencySearchFilterV1:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 2
            example: USAID
    AssistanceListingNumberFilterV1:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            type: string
            pattern: ^\d{2}\.\d{2,3}$
            example: '45.149'
    IsCostSharingFilterV1:
      type: object
      properties:
        one_of:
          type:
          - array
          - 'null'
          items:
            type: boolean
            example: true
    ExpectedNumberAwardsFilterV1:
      type: object
      properties:
        min:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 0
        max:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 25
    AwardFloorFilterV1:
      type: object
      properties:
        min:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 0
        max:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 10000
    AwardCeilingFilterV1:
      type: object
      properties:
        min:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 0
        max:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 10000000
    EstimatedTotalProgramFundingFilterV1:
      type: object
      properties:
        min:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 0
        max:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 10000000
    PostDateFilterV1:
      type: object
      properties:
        start_date:
          type:
          - string
          - 'null'
          format: date
        end_date:
          type:
          - string
          - 'null'
          format: date
    CloseDateFilterV1:
      type: object
      properties:
        start_date:
          type:
          - string
          - 'null'
          format: date
        end_date:
          type:
          - string
          - 'null'
          format: date
    OpportunitySearchFilterV1:
      type: object
      properties:
        funding_instrument:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/FundingInstrumentFilterV1'
        funding_category:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/FundingCategoryFilterV1'
        applicant_type:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/ApplicantTypeFilterV1'
        opportunity_status:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/OpportunityStatusFilterV1'
        agency:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/AgencySearchFilterV1'
        assistance_listing_number:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/AssistanceListingNumberFilterV1'
        is_cost_sharing:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/IsCostSharingFilterV1'
        expected_number_of_awards:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/ExpectedNumberAwardsFilterV1'
        award_floor:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/AwardFloorFilterV1'
        award_ceiling:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/AwardCeilingFilterV1'
        estimated_total_program_funding:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/EstimatedTotalProgramFundingFilterV1'
        post_date:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/PostDateFilterV1'
        close_date:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/CloseDateFilterV1'
    ExperimentalV1:
      type: object
      properties:
        scoring_rule:
          default: !!python/object/apply:src.services.opportunities_v1.experimental_constant.ScoringRule
          - default
          description: Scoring rule to query against OpenSearch
          enum:
          - default
          - expanded
          - agency
          type:
          - string
    OpportunityPaginationV1:
      type: object
      properties:
        order_by:
          type: string
          enum:
          - relevancy
          - opportunity_id
          - opportunity_number
          - opportunity_title
          - post_date
          - close_date
          - agency_code
          description: The field to sort the response by
        sort_direction:
          description: Whether to sort the response ascending or descending
          enum:
          - ascending
          - descending
          type:
          - string
        page_size:
          type: integer
          minimum: 1
          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:
      - order_by
      - page_offset
      - page_size
      - sort_direction
    OpportunitySearchRequestV1:
      type: object
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 100
          description: Query string which searches against several text fields
          example: research
        filters:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/OpportunitySearchFilterV1'
        experimental:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/ExperimentalV1'
        pagination:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/OpportunityPaginationV1'
        format:
          default: !!python/object/apply:src.api.opportunities_v1.opportunity_schemas.SearchResponseFormat
          - json
          description: The format of the response
          enum:
          - json
          - csv
          type:
          - string
      required:
      - pagination
    OpportunityAssistanceListingV1:
      type: object
      properties:
        program_title:
          type:
          - string
          - 'null'
          description: The name of the program, see https://sam.gov/content/assistance-listings
            for more detail
          example: Space Technology
        assistance_listing_number:
          type:
          - string
          - 'null'
          description: The assistance listing number, see https://sam.gov/content/assistance-listings
            for more detail
          example: '43.012'
    OpportunitySummaryV1:
      type: object
      properties:
        summary_description:
          type:
          - string
          - 'null'
          description: The summary of the opportunity
          example: This opportunity aims to unravel the mysteries of the universe.
        is_cost_sharing:
          type:
          - boolean
          - 'null'
          description: Whether or not the opportunity has a cost sharing/matching
            requirement
        is_forecast:
          type: boolean
          description: Whether the opportunity is forecasted, that is, the information
            is only an estimate and not yet official
          example: false
        close_date:
          type:
          - string
          - 'null'
          format: date
          description: The date that the opportunity will close - only set if is_forecast=False
        close_date_description:
          type:
          - string
          - 'null'
          description: Optional details regarding the close date
          example: Proposals are due earlier than usual.
        post_date:
          type:
          - string
          - 'null'
          format: date
          description: The date the opportunity was posted
        archive_date:
          type:
          - string
          - 'null'
          format: date
          description: When the opportunity will be archived
        expected_number_of_awards:
          type:
          - integer
          - 'null'
          description: The number of awards the opportunity is expected to award
          example: 10
        estimated_total_program_funding:
          type:
          - integer
          - 'null'
          description: The total program funding of the opportunity in US Dollars
          example: 10000000
        award_floor:
          type:
          - integer
          - 'null'
          description: The minimum amount an opportunity would award
          example: 10000
        award_ceiling:
          type:
          - integer
          - 'null'
          description: The maximum amount an opportunity would award
          example: 100000
        additional_info_url:
          type:
          - string
          - 'null'
          description: A URL to a website that can provide additional information
            about the opportunity
          example: grants.gov
        additional_info_url_description:
          type:
          - string
          - 'null'
          description: The text to display for the additional_info_url link
          example: Click me for more info
        forecasted_post_date:
          type:
          - string
          - 'null'
          format: date
          description: Forecasted opportunity only. The date the opportunity is expected
            to be posted, and transition out of being a forecast
        forecasted_close_date:
          type:
          - string
          - 'null'
          format: date
          description: Forecasted opportunity only. The date the opportunity is expected
            to be close once posted.
        forecasted_close_date_description:
          type:
          - string
          - 'null'
          description: Forecasted opportunity only. Optional details regarding the
            forecasted closed date.
          example: Proposals will probably be due on this date
        forecasted_award_date:
          type:
          - string
          - 'null'
          format: date
          description: Forecasted opportunity only. The date the grantor plans to
            award the opportunity.
        forecasted_project_start_date:
          type:
          - string
          - 'null'
          format: date
          description: Forecasted opportunity only. The date the grantor expects the
            award recipient should start their project
        fiscal_year:
          type:
          - integer
          - 'null'
          description: Forecasted opportunity only. The fiscal year the project is
            expected to be funded and launched
        funding_category_description:
          type:
          - string
          - 'null'
          description: Additional information about the funding category
          example: Economic Support
        applicant_eligibility_description:
          type:
          - string
          - 'null'
          description: Additional information about the types of applicants that are
            eligible
          example: All types of domestic applicants are eligible to apply
        agency_contact_description:
          type:
          - string
          - 'null'
          description: Information regarding contacting the agency who owns the opportunity
          example: For more information, reach out to Jane Smith at agency US-ABC
        agency_email_address:
          type:
          - string
          - 'null'
          description: The contact email of the agency who owns the opportunity
          example: fake_email@grants.gov
        agency_email_address_description:
          type:
          - string
          - 'null'
          description: The text for the link to the agency email address
          example: Click me to email the agency
        version_number:
          type: integer
          description: The version number of the opportunity summary
          example: 1
        funding_instruments:
          type: array
          items:
            enum:
            - cooperative_agreement
            - grant
            - procurement_contract
            - other
            type:
            - string
        funding_categories:
          type: array
          items:
            enum:
            - recovery_act
            - agriculture
            - arts
            - business_and_commerce
            - community_development
            - consumer_protection
            - disaster_prevention_and_relief
            - education
            - employment_labor_and_training
            - energy
            - environment
            - food_and_nutrition
            - health
            - housing
            - humanities
            - infrastructure_investment_and_jobs_act
            - information_and_statistics
            - income_security_and_social_services
            - law_justice_and_legal_services
            - natural_resources
            - opportunity_zone_benefits
            - regional_development
            - science_technology_and_other_research_and_development
            - transportation
            - affordable_care_act
            - other
            type:
            - string
        applicant_types:
          type: array
          items:
            enum:
            - state_governments
            - county_governments
            - city_or_township_governments
            - special_district_governments
            - independent_school_districts
            - public_and_state_institutions_of_higher_education
            - private_institutions_of_higher_education
            - federally_recognized_native_american_tribal_governments
            - other_native_american_tribal_organizations
            - public_and_indian_housing_authorities
            - nonprofits_non_higher_education_with_501c3
            - nonprofits_non_higher_education_without_501c3
            - individuals
            - for_profit_organizations_other_than_small_businesses
            - small_businesses
            - other
            - unrestricted
            type:
            - string
        created_at:
          type: string
          format: date-time
          description: When the opportunity summary was created
        updated_at:
          type: string
          format: date-time
          description: When the opportunity summary was last updated
    OpportunityV1:
      type: object
      properties:
        opportunity_id:
          type: integer
          description: The internal ID of the opportunity
          example: 12345
        opportunity_number:
          type:
          - string
          - 'null'
          description: The funding opportunity number
          example: ABC-123-XYZ-001
        opportunity_title:
          type:
          - string
          - 'null'
          description: The title of the opportunity
          example: Research into conservation techniques
        agency:
          type:
          - string
          - 'null'
          description: 'DEPRECATED - use: agency_code'
          example: US-ABC
        agency_code:
          type:
          - string
          - 'null'
          description: The agency who created the opportunity
          example: US-ABC
        agency_name:
          type:
          - string
          - 'null'
          description: The name of the agency who created the oppportunity
          example: Department of Examples
        top_level_agency_name:
          type:
          - string
          - 'null'
          description: The name of the top level agency who created the oppportunity
          example: Department of Examples
        category:
          description: The opportunity category
          example: !!python/object/apply:src.constants.lookup_constants.OpportunityCategory
          - discretionary
          enum: &id002
          - discretionary
          - mandatory
          - continuation
          - earmark
          - other
          type:
          - string
          - 'null'
          - 'null'
        category_explanation:
          type:
          - string
          - 'null'
          description: Explanation of the category when the category is 'O' (other)
          example: null
        opportunity_assistance_listings:
          type: array
          items:
            type: &id003
            - object
            allOf:
            - $ref: '#/components/schemas/OpportunityAssistanceListingV1'
        summary:
          type: &id004
          - object
          allOf:
          - $ref: '#/components/schemas/OpportunitySummaryV1'
        opportunity_status:
          description: The current status of the opportunity
          example: !!python/object/apply:src.constants.lookup_constants.OpportunityStatus
          - posted
          enum: &id005
          - forecasted
          - posted
          - closed
          - archived
          type: &id006
          - string
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
    OpportunityFacetV1:
      type: object
      properties:
        opportunity_status:
          type: object
          description: The counts of opportunity_status values in the full response
          example:
            posted: 1
            forecasted: 2
          additionalProperties:
            type: integer
        applicant_type:
          type: object
          description: The counts of applicant_type values in the full response
          example:
            state_governments: 3
            county_governments: 2
            city_or_township_governments: 1
          additionalProperties:
            type: integer
        funding_instrument:
          type: object
          description: The counts of funding_instrument values in the full response
          example:
            cooperative_agreement: 4
            grant: 3
          additionalProperties:
            type: integer
        funding_category:
          type: object
          description: The counts of funding_category values in the full response
          example:
            recovery_act: 2
            arts: 3
            agriculture: 5
          additionalProperties:
            type: integer
        agency:
          type: object
          description: The counts of agency values in the full response
          example:
            USAID: 4
            DOC: 3
          additionalProperties:
            type: integer
    OpportunitySearchResponseV1:
      type: object
      properties:
        pagination_info:
          description: The pagination information for paginated endpoints
          type: *id001
          allOf:
          - $ref: '#/components/schemas/PaginationInfo'
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type: array
          items:
            $ref: '#/components/schemas/OpportunityV1'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
        facet_counts:
          description: Counts of filter/facet values in the full response
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/OpportunityFacetV1'
    User:
      type: object
      properties:
        user_id:
          type: string
          description: The internal ID of a user
          example: 861a0148-cf2c-432b-b0b3-690016299ab1
        email:
          type: string
          description: The email address returned from Oauth2 provider
          example: user@example.com
        external_user_type:
          description: The Oauth2 provider through which a user was authenticated
          example: !!python/object/apply:src.constants.lookup_constants.ExternalUserType
          - login_gov
          enum:
          - login_gov
          type:
          - string
    UserGetResponse:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/User'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    OpportunityAttachmentV1:
      type: object
      properties:
        download_path:
          type: string
          description: The file's download path
        file_size_bytes:
          type: integer
          description: The size of the file in bytes
          example: 1024
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        mime_type:
          type: string
          description: The MIME type of the attachment
          example: application/pdf
        file_name:
          type: string
          description: The name of the attachment file
          example: my_NOFO.pdf
        file_description:
          type: string
          description: A description of the attachment
          example: The full announcement NOFO
        opportunity_attachment_type:
          description: The type of attachment
          example: !!python/object/apply:src.constants.lookup_constants.OpportunityAttachmentType
          - notice_of_funding_opportunity
          enum:
          - notice_of_funding_opportunity
          - other
          type:
          - string
    OpportunityWithAttachmentsV1:
      type: object
      properties:
        opportunity_id:
          type: integer
          description: The internal ID of the opportunity
          example: 12345
        opportunity_number:
          type:
          - string
          - 'null'
          description: The funding opportunity number
          example: ABC-123-XYZ-001
        opportunity_title:
          type:
          - string
          - 'null'
          description: The title of the opportunity
          example: Research into conservation techniques
        agency:
          type:
          - string
          - 'null'
          description: 'DEPRECATED - use: agency_code'
          example: US-ABC
        agency_code:
          type:
          - string
          - 'null'
          description: The agency who created the opportunity
          example: US-ABC
        agency_name:
          type:
          - string
          - 'null'
          description: The name of the agency who created the oppportunity
          example: Department of Examples
        top_level_agency_name:
          type:
          - string
          - 'null'
          description: The name of the top level agency who created the oppportunity
          example: Department of Examples
        category:
          description: The opportunity category
          example: !!python/object/apply:src.constants.lookup_constants.OpportunityCategory
          - discretionary
          enum: *id002
          type:
          - string
          - 'null'
          - 'null'
        category_explanation:
          type:
          - string
          - 'null'
          description: Explanation of the category when the category is 'O' (other)
          example: null
        opportunity_assistance_listings:
          type: array
          items:
            type: *id003
            allOf:
            - $ref: '#/components/schemas/OpportunityAssistanceListingV1'
        summary:
          type: *id004
          allOf:
          - $ref: '#/components/schemas/OpportunitySummaryV1'
        opportunity_status:
          description: The current status of the opportunity
          example: !!python/object/apply:src.constants.lookup_constants.OpportunityStatus
          - posted
          enum: *id005
          type: *id006
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        attachments:
          type: array
          description: List of attachments associated with the opportunity
          items:
            type:
            - object
            allOf:
            - $ref: '#/components/schemas/OpportunityAttachmentV1'
    OpportunityGetResponseV1:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/OpportunityWithAttachmentsV1'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    SavedSearchResponse:
      type: object
      properties:
        saved_search_id:
          type: string
          format: uuid
          description: The ID of the saved search
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: Name of the saved search
          example: Grant opportunities in California
        search_query:
          description: The saved search query parameters
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/OpportunitySearchRequestV1'
        created_at:
          type: string
          format: date-time
          description: When the search was saved
          example: '2024-01-01T00:00:00Z'
    UserSavedSearchesResponse:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type: array
          description: List of saved searches
          items:
            type:
            - object
            allOf:
            - $ref: '#/components/schemas/SavedSearchResponse'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    UserSaveSearchRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the saved search
          example: Example search
        search_query:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/OpportunitySearchRequestV1'
      required:
      - name
    UserSaveSearchResponse:
      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
    SavedOpportunitySummaryV1:
      type: object
      properties:
        post_date:
          type: string
          format: date
          description: The date the opportunity was posted
          example: '2024-01-01'
        close_date:
          type: string
          format: date
          description: The date the opportunity will close
          example: '2024-01-01'
        is_forecast:
          type: boolean
          description: Whether the opportunity is forecasted
          example: false
    SavedOpportunityResponseV1:
      type: object
      properties:
        opportunity_id:
          type: integer
          description: The ID of the saved opportunity
          example: 1234
        opportunity_title:
          type:
          - string
          - 'null'
          description: The title of the opportunity
          example: my title
        opportunity_status:
          description: The current status of the opportunity
          example: !!python/object/apply:src.constants.lookup_constants.OpportunityStatus
          - posted
          enum:
          - forecasted
          - posted
          - closed
          - archived
          type:
          - string
        summary:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/SavedOpportunitySummaryV1'
    UserSavedOpportunitiesResponse:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type: array
          description: List of saved opportunities
          items:
            type:
            - object
            allOf:
            - $ref: '#/components/schemas/SavedOpportunityResponseV1'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    UserSaveOpportunityRequest:
      type: object
      properties:
        opportunity_id:
          type: integer
      required:
      - opportunity_id
    UserSaveOpportunityResponse:
      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
    OpportunityVersionV1:
      type: object
      properties:
        opportunity:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/OpportunityV1'
        forecasts:
          type: array
          items:
            $ref: '#/components/schemas/OpportunitySummaryV1'
        non_forecasts:
          type: array
          items:
            $ref: '#/components/schemas/OpportunitySummaryV1'
    OpportunityVersionsGetResponseV1:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type:
          - object
          allOf:
          - $ref: '#/components/schemas/OpportunityVersionV1'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    UserDeleteSavedSearchResponse:
      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
    UserDeleteSavedOpportunityResponse:
      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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Auth
    ApiJwtAuth:
      type: apiKey
      in: header
      name: X-SGG-Token