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 Form Alpha API
  version: v0
servers: .
tags:
- name: Form Alpha
paths:
  /alpha/forms/{form_id}:
    get:
      parameters:
      - in: path
        name: form_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormResponseAlphaSchema'
          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:
      - Form Alpha
      summary: Form Get
      security:
      - ApiUserKeyAuth: []
    put:
      parameters:
      - in: path
        name: form_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormUpdateResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
      tags:
      - Form Alpha
      summary: Form Update
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormUpdateRequestSchema'
      security:
      - ApiUserKeyAuth: []
  /alpha/forms/{form_id}/form_instructions/{form_instruction_id}:
    put:
      parameters:
      - in: path
        name: form_id
        schema:
          type: string
        required: true
      - in: path
        name: form_instruction_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormInstructionUploadResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
      tags:
      - Form Alpha
      summary: Form Instruction Upsert
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FormInstructionUploadRequestSchema'
      security:
      - ApiUserKeyAuth: []
components:
  schemas:
    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
    FormResponseAlphaSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type:
          - object
          $ref: '#/components/schemas/FormAlphaSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
        warnings:
          type: array
          description: A list of warnings - indicating something you may want to be aware of, but did not prevent handling of the request
          items:
            type:
            - object
            $ref: '#/components/schemas/ValidationIssueSchema'
    FormUpdateRequestSchema:
      type: object
      properties:
        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_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The UUID of the form instruction
          example: 123e4567-e89b-12d3-a456-426614174000
        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
      required:
      - agency_code
      - form_json_schema
      - form_name
      - form_ui_schema
      - form_version
      - short_form_name
    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
    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
    FormInstructionUploadResponseSchema:
      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
    FormUpdateResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type:
          - object
          $ref: '#/components/schemas/FormAlphaSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    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
    FormInstructionUploadRequestSchema:
      type: object
      properties:
        file:
          description: The form instruction file to upload
          type: string
          format: binary
      required:
      - file
  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