openapi: 3.1.0
info:
  description: '

    Back end API for simpler.grants.gov.


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


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

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

    '
  contact:
    name: Simpler Grants.gov
    url: https://simpler.grants.gov/
    email: simpler@grants.gov
  title: Simpler Grants Opportunity v1 API
  version: v0
servers: .
tags:
- name: Opportunity v1
paths:
  /v1/opportunities/search:
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunitySearchResponseV1Schema'
            text/csv: {}
          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
      tags:
      - Opportunity v1
      summary: Search opportunities (JSON or CSV)
      description: '

        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.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpportunitySearchRequestV1Schema'
            examples:
              example1:
                summary: No filters
                value:
                  pagination:
                    sort_order:
                    - order_by: opportunity_id
                      sort_direction: ascending
                    page_offset: 1
                    page_size: 25
              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:
                    sort_order:
                    - order_by: opportunity_id
                      sort_direction: ascending
                    page_offset: 1
                    page_size: 25
              example3:
                summary: Query & opportunity_status filters
                value:
                  query: research
                  filters:
                    opportunity_status:
                      one_of:
                      - forecasted
                      - posted
                  pagination:
                    sort_order:
                    - order_by: opportunity_id
                      sort_direction: ascending
                    page_offset: 1
                    page_size: 25
              example4:
                summary: CSV file response
                value:
                  format: csv
                  filters:
                    opportunity_status:
                      one_of:
                      - forecasted
                      - posted
                  pagination:
                    sort_order:
                    - order_by: opportunity_id
                      sort_direction: ascending
                    page_offset: 1
                    page_size: 100
              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:
                    sort_order:
                    - order_by: opportunity_id
                      sort_direction: ascending
                    page_offset: 1
                    page_size: 25
              example6:
                summary: Filter by assistance listing numbers
                value:
                  filters:
                    assistance_listing_number:
                      one_of:
                      - '43.001'
                      - '47.049'
                  pagination:
                    sort_order:
                    - order_by: opportunity_id
                      sort_direction: ascending
                    page_offset: 1
                    page_size: 25
              example7:
                summary: Primary sort agency_code desc, secondary sort opportunity_id asc
                value:
                  pagination:
                    page_offset: 1
                    page_size: 25
                    sort_order:
                    - order_by: agency_code
                      sort_direction: descending
                    - order_by: opportunity_id
                      sort_direction: ascending
      security:
      - ApiJwtAuth: &id001 []
      - ApiUserKeyAuth: *id001
  /v1/opportunities/search/csv:
    post:
      parameters: []
      responses:
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '200':
          content:
            text/csv: {}
      tags:
      - Opportunity v1
      summary: Opportunity Search Csv
      description: '

        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.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpportunitySearchCSVRequestV1Schema'
            examples:
              example1:
                summary: No filters
                value: {}
              example2:
                summary: Query and filters
                value:
                  query: research
                  query_operator: OR
                  filters:
                    agency:
                      one_of:
                      - USAID
                      - DOC
                    opportunity_status:
                      one_of:
                      - forecasted
                      - posted
      security:
      - ApiJwtAuth: &id002 []
      - ApiUserKeyAuth: *id002
  /v1/opportunities/{opportunity_id}:
    get:
      parameters:
      - in: path
        name: opportunity_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunityGetResponseV1Schema'
          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
      tags:
      - Opportunity v1
      summary: Opportunity Get
      description: '

        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.

        '
      security:
      - ApiJwtAuth: &id003 []
      - ApiUserKeyAuth: *id003
  /v1/opportunities/{legacy_opportunity_id}:
    get:
      parameters:
      - in: path
        name: legacy_opportunity_id
        schema:
          type: integer
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunityGetResponseV1Schema'
          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
      tags:
      - Opportunity v1
      summary: Opportunity Get Legacy
      description: '

        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.

        '
      security:
      - ApiJwtAuth: &id004 []
      - ApiUserKeyAuth: *id004
components:
  schemas:
    IsCostSharingFilterV1Schema:
      type: object
      properties:
        one_of:
          type:
          - array
          - 'null'
          items:
            type: boolean
            example: true
    FormAlphaSchema:
      type: object
      properties:
        form_id:
          type: string
          format: uuid
          description: The primary key ID of the form
          example: 123e4567-e89b-12d3-a456-426614174000
        form_name:
          type: string
          description: The name of the form
          example: ABC Project Form
        short_form_name:
          type: string
          description: The short name of the form used for making files
          example: abc_project
        form_version:
          type: string
          description: The version of the form
          example: '1.0'
        agency_code:
          type: string
          description: The agency code for the form
          example: SGG
        omb_number:
          type:
          - string
          - 'null'
          description: The OMB number for the form
          example: 4040-0001
        legacy_form_id:
          type:
          - integer
          - 'null'
          description: The legacy form ID
          example: 123
        form_json_schema:
          type: object
          description: The JSON Schema representation of the form
          example:
            type: object
            title: Test form for testing
            properties:
              Title:
                title: Title
                type: string
                minLength: 1
                maxLength: 60
              Description:
                title: Description for application
                type: string
                minLength: 0
                maxLength: 15
              ApplicationNumber:
                title: Application number
                type: number
                minLength: 1
                maxLength: 120
              Date:
                title: 'Date of application '
                type: string
                format: date
          additionalProperties: {}
        form_ui_schema:
          description: The UI Schema of the form for front-end rendering
          example:
          - type: field
            definition: /properties/Title
          - type: field
            definition: /properties/Description
          - type: field
            definition: /properties/ApplicationNumber
          - type: field
            definition: /properties/Date
        form_instruction:
          description: The instruction file for the form, if available
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/FormInstructionSchema'
          - type: 'null'
        form_rule_schema:
          type:
          - object
          - 'null'
          description: The rule schema for the form
          additionalProperties: {}
        json_to_xml_schema:
          type:
          - object
          - 'null'
          description: The JSON to XML schema mapping configuration for the form
          additionalProperties: {}
        form_type:
          description: The type of the form
          example:
          - SF424
          enum:
          - SF424
          - SF424A
          - SF424B
          - SF424D
          - SFLLL
          - ProjectNarrativeAttachment
          - BudgetNarrativeAttachment
          - OtherNarrativeAttachment
          - ProjectAbstractSummary
          - ProjectAbstract
          - CD511
          - SupplementaryNEHCoverSheet
          - GGLobbyingForm
          - EPAForm4700-4
          - EPAKeyContacts
          - AttachmentForm
          - ProjectPerformanceSiteLocation
          type:
          - string
          - 'null'
          - 'null'
        sgg_version:
          type:
          - string
          - 'null'
          description: The SGG version of the form
          example: '1.0'
        is_deprecated:
          type:
          - boolean
          - 'null'
          description: Whether the form is deprecated
          example: false
        created_at:
          type: string
          format: date-time
          description: The timestamp when the form was created
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the form was last updated
    CompetitionFormAlphaSchema:
      type: object
      properties:
        is_required:
          type: boolean
          description: Whether the form is required for all applications to the competition
        form:
          description: The form template information for this competition
          type:
          - object
          $ref: '#/components/schemas/FormAlphaSchema'
    FormInstructionSchema:
      type: object
      properties:
        form_instruction_id:
          type: string
          format: uuid
          description: The UUID of the form instruction
          example: 123e4567-e89b-12d3-a456-426614174000
        file_name:
          type: string
          description: The name of the form instruction file
          example: instructions.pdf
        download_path:
          type: string
          description: The download URL for the form instruction file
        created_at:
          type: string
          format: date-time
          description: The timestamp when the form instruction was created
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the form instruction was last updated
    ValidationIssueSchema:
      type: object
      properties:
        type:
          type: string
          description: The type of error
          example: invalid
        message:
          type: string
          description: The message to return
          example: Not a valid string.
        field:
          type: string
          description: The field that failed
          example: summary.summary_description
        value:
          type: string
          description: The value that failed
          example: invalid string
    OpportunityWithAttachmentsV1Schema:
      type: object
      properties:
        opportunity_id:
          type: string
          format: uuid
          description: The internal ID of the opportunity
          example: 123e4567-e89b-12d3-a456-426614174000
        legacy_opportunity_id:
          type:
          - integer
          - 'null'
          description: The internal legacy 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 opportunity
          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:
          - discretionary
          enum:
          - 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:
            - object
            $ref: '#/components/schemas/OpportunityAssistanceListingV1Schema'
        summary:
          type:
          - object
          $ref: '#/components/schemas/OpportunitySummaryV1Schema'
        opportunity_status:
          description: The current status of the opportunity
          example:
          - posted
          enum:
          - forecasted
          - posted
          - closed
          - archived
          type:
          - string
        top_level_agency_code:
          type:
          - string
          - 'null'
          description: The top-level (parent) agency
          example: HHS
        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
            $ref: '#/components/schemas/OpportunityAttachmentV1Schema'
        competitions:
          type: array
          description: List of competitions associated with the opportunity
          items:
            type:
            - object
            $ref: '#/components/schemas/CompetitionAlphaSchema'
    OpportunityAttachmentV1Schema:
      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
        opportunity_attachment_id:
          type: string
          format: uuid
          description: The unique ID of the attachment
          example: 123e4567-e89b-12d3-a456-426614174000
        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
    OpportunitySearchRequestV1Schema:
      type: object
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 100
          description: Query string which searches against several text fields
          example: research
        query_operator:
          default:
          - AND
          description: Query operator for combining search conditions
          example: OR
          enum:
          - AND
          - OR
          type:
          - string
        filters:
          type:
          - object
          $ref: '#/components/schemas/OpportunitySearchFilterV1Schema'
        experimental:
          type:
          - object
          $ref: '#/components/schemas/ExperimentalV1Schema'
        pagination:
          type:
          - object
          $ref: '#/components/schemas/OpportunityPaginationV1Schema'
        format:
          default:
          - json
          description: Response serialization. `json` returns the standard envelope with facet counts. `csv` returns a CSV file; pagination and sort_order match the JSON response for the same request. For a bulk export (up to 5000 rows, fixed sort by post_date descending), use `POST /v1/opportunities/search/csv` instead.
          enum:
          - json
          - csv
          type:
          - string
      required:
      - pagination
    PaginationInfoSchema:
      type: object
      properties:
        page_offset:
          type: integer
          description: The page number that was fetched
          example: 1
        page_size:
          type: integer
          description: The size of the page fetched
          example: 25
        total_records:
          type: integer
          description: The total number of records fetchable
          example: 42
        total_pages:
          type: integer
          description: The total number of pages that can be fetched
          example: 2
        sort_order:
          type: array
          description: The sort order passed in originally
          items:
            type:
            - object
            $ref: '#/components/schemas/SortOrderSchema'
    OpportunitySearchResponseV1Schema:
      type: object
      properties:
        pagination_info:
          description: The pagination information for paginated endpoints
          type:
          - object
          $ref: '#/components/schemas/PaginationInfoSchema'
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type: array
          items:
            $ref: '#/components/schemas/OpportunityV1Schema'
        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
          $ref: '#/components/schemas/OpportunityFacetV1Schema'
    ExperimentalV1Schema:
      type: object
      properties:
        scoring_rule:
          default:
          - default
          description: Scoring rule to query against OpenSearch
          enum:
          - default
          - expanded
          - agency
          type:
          - string
    OpportunityPaginationV1Schema:
      type: object
      properties:
        sort_order:
          type: array
          default:
          - order_by: opportunity_id
            sort_direction: descending
          minItems: 1
          maxItems: 5
          description: The list of sorting rules
          items:
            type:
            - object
            $ref: '#/components/schemas/SortOrderOpportunityPaginationV1Schema'
        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
    OpportunityGetResponseV1Schema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type:
          - object
          $ref: '#/components/schemas/OpportunityWithAttachmentsV1Schema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    OpportunityV1Schema:
      type: object
      properties:
        opportunity_id:
          type: string
          format: uuid
          description: The internal ID of the opportunity
          example: 123e4567-e89b-12d3-a456-426614174000
        legacy_opportunity_id:
          type:
          - integer
          - 'null'
          description: The internal legacy 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 opportunity
          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:
          - discretionary
          enum:
          - 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:
            - object
            $ref: '#/components/schemas/OpportunityAssistanceListingV1Schema'
        summary:
          type:
          - object
          $ref: '#/components/schemas/OpportunitySummaryV1Schema'
        opportunity_status:
          description: The current status of the opportunity
          example:
          - posted
          enum:
          - forecasted
          - posted
          - closed
          - archived
          type:
          - string
        top_level_agency_code:
          type:
          - string
          - 'null'
          description: The top-level (parent) agency
          example: HHS
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
    SortOrderOpportunityPaginationV1Schema:
      type: object
      properties:
        order_by:
          type: string
          enum:
          - relevancy
          - opportunity_id
          - opportunity_number
          - opportunity_title
          - post_date
          - close_date
          - agency_code
          - agency_name
          - top_level_agency_name
          - award_floor
          - award_ceiling
          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
    ApplicantTypeFilterV1Schema:
      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
    OpportunitySummaryV1Schema:
      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
          - 'null'
          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
            - energy_infrastructure_and_critical_mineral_and_materials
            - recreation_and_tourism
            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
    ExpectedNumberAwardsFilterV1Schema:
      type: object
      properties:
        min:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 0
        max:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 25
    CloseDateFilterV1Schema:
      type: object
      properties:
        start_date:
          type:
          - string
          - 'null'
          format: date
        end_date:
          type:
          - string
          - 'null'
          format: date
        start_date_relative:
          type:
          - integer
          - 'null'
          minimum: -1000000
          maximum: 1000000
        end_date_relative:
          type:
          - integer
          - 'null'
          minimum: -1000000
          maximum: 1000000
    EstimatedTotalProgramFundingFilterV1Schema:
      type: object
      properties:
        min:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 0
        max:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 10000000
    PostDateFilterV1Schema:
      type: object
      properties:
        start_date:
          type:
          - string
          - 'null'
          format: date
        end_date:
          type:
          - string
          - 'null'
          format: date
        start_date_relative:
          type:
          - integer
          - 'null'
          minimum: -1000000
          maximum: 1000000
        end_date_relative:
          type:
          - integer
          - 'null'
          minimum: -1000000
          maximum: 1000000
    OpportunityStatusFilterV1Schema:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            enum:
            - forecasted
            - posted
            - closed
            - archived
            type:
            - string
    AwardFloorFilterV1Schema:
      type: object
      properties:
        min:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 0
        max:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 10000
    OpportunityFacetV1Schema:
      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
        is_cost_sharing:
          type: object
          description: The counts of is_cost_sharing values in the full response
          example:
            'true': 1
            'false': 3
          additionalProperties:
            type: integer
        close_date:
          type: object
          description: The counts of close_date values in the full response
          additionalProperties:
            type: integer
        post_date:
          type: object
          description: The counts of post_date values in the full response
          additionalProperties:
            type: integer
    AssistanceListingNumberFilterV1Schema:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            type: string
            pattern: ^\d{2}\.[A-Za-z0-9]{2,3}$
            example: '45.149'
    TopLevelAgencyOppSearchFilterV1Schema:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 2
            example: USAID
    FundingCategoryFilterV1Schema:
      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
            - energy_infrastructure_and_critical_mineral_and_materials
            - recreation_and_tourism
            type:
            - string
    OpportunitySearchCSVRequestV1Schema:
      type: object
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 100
          description: Query string which searches against several text fields
          example: research
        query_operator:
          default:
          - AND
          description: Query operator for combining search conditions
          example: OR
          enum:
          - AND
          - OR
          type:
          - string
        filters:
          type:
          - object
          $ref: '#/components/schemas/OpportunitySearchFilterV1Schema'
      additionalProperties: false
    AwardCeilingFilterV1Schema:
      type: object
      properties:
        min:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 0
        max:
          type:
          - integer
          - 'null'
          minimum: 0
          example: 10000000
    CompetitionAlphaSchema:
      type: object
      properties:
        competition_id:
          type: string
          format: uuid
          description: The competition ID
          example: 123e4567-e89b-12d3-a456-426614174000
        opportunity_id:
          type: string
          format: uuid
          description: The opportunity ID that the competition is associated with
          example: 123e4567-e89b-12d3-a456-426614174000
        competition_forms:
          type: array
          description: List of forms required for this competition
          items:
            type:
            - object
            $ref: '#/components/schemas/CompetitionFormAlphaSchema'
        competition_instructions:
          type: array
          description: List of instruction files associated with this competition
          items:
            type:
            - object
            $ref: '#/components/schemas/CompetitionInstructionAlphaSchema'
        competition_title:
          type:
          - string
          - 'null'
          description: The title of the competition
          example: Proposal for Advanced Research
        opening_date:
          type:
          - string
          - 'null'
          format: date
          description: The opening date of the competition, the first day applications are accepted
        closing_date:
          type:
          - string
          - 'null'
          format: date
          description: The closing date of the competition, the last day applications are accepted
        contact_info:
          type:
          - string
          - 'null'
          description: Contact info getting assistance with the competition
          example: 'Bob Smith

            FakeMail@fake.com'
        opportunity_assistance_listing:
          description: Assistance listing information for this competition
          type:
          - object
          - 'null'
          anyOf:
          - $ref: '#/components/schemas/OpportunityAssistanceListingV1Schema'
          - type: 'null'
        open_to_applicants:
          type: array
          description: List of applicant types who are eligible for this competition
          example:
          - - individual
          - - organization
          items:
            enum:
            - individual
            - organization
            type:
            - string
        is_open:
          type: boolean
          description: Whether the competition is open and accepting applications
        is_simpler_grants_enabled:
          type: boolean
          description: Whether simpler grants are enabled for this competition
    OpportunitySearchFilterV1Schema:
      type: object
      properties:
        funding_instrument:
          type:
          - object
          $ref: '#/components/schemas/FundingInstrumentFilterV1Schema'
        funding_category:
          type:
          - object
          $ref: '#/components/schemas/FundingCategoryFilterV1Schema'
        applicant_type:
          type:
          - object
          $ref: '#/components/schemas/ApplicantTypeFilterV1Schema'
        opportunity_status:
          type:
          - object
          $ref: '#/components/schemas/OpportunityStatusFilterV1Schema'
        agency:
          type:
          - object
          $ref: '#/components/schemas/AgencyOppSearchFilterV1Schema'
        assistance_listing_number:
          type:
          - object
          $ref: '#/components/schemas/AssistanceListingNumberFilterV1Schema'
        is_cost_sharing:
          type:
          - object
          $ref: '#/components/schemas/IsCostSharingFilterV1Schema'
        expected_number_of_awards:
          type:
          - object
          $ref: '#/components/schemas/ExpectedNumberAwardsFilterV1Schema'
        award_floor:
          type:
          - object
          $ref: '#/components/schemas/AwardFloorFilterV1Schema'
        award_ceiling:
          type:
          - object
          $ref: '#/components/schemas/AwardCeilingFilterV1Schema'
        estimated_total_program_funding:
          type:
          - object
          $ref: '#/components/schemas/EstimatedTotalProgramFundingFilterV1Schema'
        post_date:
          type:
          - object
          $ref: '#/components/schemas/PostDateFilterV1Schema'
        close_date:
          type:
          - object
          $ref: '#/components/schemas/CloseDateFilterV1Schema'
        top_level_agency:
          type:
          - object
          $ref: '#/components/schemas/TopLevelAgencyOppSearchFilterV1Schema'
    ErrorResponseSchema:
      type: object
      properties:
        data:
          description: Additional data that might be useful in resolving an error (see specific endpoints for details, this is used infrequently)
          example: {}
        message:
          type: string
          description: General description of the error
          example: Error
        status_code:
          type: integer
          description: The HTTP status code of the error
        errors:
          type: array
          example: []
          items:
            type:
            - object
            $ref: '#/components/schemas/ValidationIssueSchema'
        internal_request_id:
          type: string
          description: An internal tracking ID
          example: 550e8400-e29b-41d4-a716-446655440000
    FundingInstrumentFilterV1Schema:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            enum:
            - cooperative_agreement
            - grant
            - procurement_contract
            - other
            type:
            - string
    CompetitionInstructionAlphaSchema:
      type: object
      properties:
        file_name:
          type: string
          description: The name of the instruction file
          example: competition_instructions.pdf
        download_path:
          type: string
          description: The URL to download the instruction file
          example: https://cdn.example.com/competition-instructions/file.pdf
        created_at:
          type: string
          format: date-time
          description: The date and time when the instruction was created
        updated_at:
          type: string
          format: date-time
          description: The date and time when the instruction was last updated
    SortOrderSchema:
      type: object
      properties:
        order_by:
          type: string
          description: The field that the records were sorted by
          example: id
        sort_direction:
          description: The direction the records are sorted
          enum:
          - ascending
          - descending
          type:
          - string
    OpportunityAssistanceListingV1Schema:
      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'
    AgencyOppSearchFilterV1Schema:
      type: object
      properties:
        one_of:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 2
            example: USAID
  securitySchemes:
    ApiJwtAuth:
      type: apiKey
      in: header
      name: X-SGG-Token
    InternalApiJwtAuth:
      type: apiKey
      in: header
      name: X-SGG-Internal-Token
    ApiUserKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key