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 Workflow API
  version: v0
servers: .
tags:
- name: Workflow
paths:
  /v1/workflows/events:
    put:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowEventResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not Found
      tags:
      - Workflow
      summary: Send Workflow Event
      description: Trigger a new workflow or progress an existing one.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowEventRequestSchema'
      security:
      - ApiJwtAuth: &id001 []
      - ApiUserKeyAuth: *id001
  /v1/workflows/{workflow_id}:
    get:
      parameters:
      - in: path
        name: workflow_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowGetResponseSchema'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Workflow
      summary: Get Workflow Details
      description: Retrieve detailed information about a specific workflow including audit history, approvals, and approval configuration. Access is controlled by entity-based privileges (VIEW_OPPORTUNITY or VIEW_APPLICATION).
      security:
      - ApiJwtAuth: &id002 []
      - ApiUserKeyAuth: *id002
  /v1/workflows/events/{event_id}:
    get:
      parameters:
      - in: path
        name: event_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowGetResponseSchema'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Workflow
      summary: Get Workflow by Event ID
      description: Retrieve detailed information about a workflow associated with a specific event. Access is controlled by entity-based privileges (VIEW_OPPORTUNITY or VIEW_APPLICATION).
      security:
      - ApiJwtAuth: &id003 []
      - ApiUserKeyAuth: *id003
  /v1/workflows/{workflow_id}/audit:
    post:
      parameters:
      - in: path
        name: workflow_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowAuditResponseSchema'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - Workflow
      summary: Get Workflow Audit Events
      description: Retrieve a paginated list of audit events for a specific workflow. Access is controlled by entity-based privileges (VIEW_OPPORTUNITY or VIEW_APPLICATION).
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowAuditRequestSchema'
      security:
      - ApiJwtAuth: &id004 []
      - ApiUserKeyAuth: *id004
components:
  schemas:
    WorkflowEventResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type:
          - object
          $ref: '#/components/schemas/WorkflowEventResponseDataSchema'
        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
    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'
    WorkflowApprovalSchema:
      type: object
      properties:
        workflow_approval_id:
          type: string
          format: uuid
          description: The workflow approval's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        approving_user:
          description: The user who provided the approval
          type:
          - object
          $ref: '#/components/schemas/WorkflowUserSchema'
        event_id:
          type: string
          format: uuid
          description: The workflow event that created this approval
          example: 123e4567-e89b-12d3-a456-426614174000
        is_still_valid:
          type: boolean
          description: Whether this approval is still valid or has been invalidated
          example: true
        comment:
          type:
          - string
          - 'null'
          description: Optional comment from the approver
          example: Approved with conditions
        approval_type:
          description: The type of approval
          example:
          - program_officer_approval
          enum:
          - initial_prototype_approval
          - program_officer_approval
          - budget_officer_approval
          type:
          - string
        approval_response_type:
          description: The response type of the approval
          example:
          - approved
          enum:
          - approved
          - declined
          - requires_modification
          type:
          - string
        created_at:
          type: string
          format: date-time
          description: When the approval was created
    WorkflowUserSchema:
      type: object
      properties:
        user_id:
          type: string
          format: uuid
          description: The user's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        email:
          type:
          - string
          - 'null'
          description: The user's email address
          example: user@example.com
        first_name:
          type:
          - string
          - 'null'
          description: The user's first name
          example: John
        last_name:
          type:
          - string
          - 'null'
          description: The user's last name
          example: Smith
    ProcessWorkflowContextSchema:
      type: object
      properties:
        workflow_id:
          type: string
          format: uuid
          description: The ID of the existing workflow to progress
          example: 123e4567-e89b-12d3-a456-426614174000
        event_to_send:
          type: string
          minLength: 1
          description: The specific event/action to trigger in the state machine
          example: approve
      required:
      - event_to_send
      - workflow_id
    WorkflowEventResponseDataSchema:
      type: object
      properties:
        event_id:
          type: string
          format: uuid
          description: The tracking ID for the workflow event
          example: 123e4567-e89b-12d3-a456-426614174000
    StartWorkflowContextSchema:
      type: object
      properties:
        workflow_type:
          description: The type of workflow to initiate
          enum:
          - opportunity_publish
          - application_submission
          - initial_prototype
          - basic_test_workflow
          - no_concurrent_test_workflow
          - limited_approval_test_workflow
          type:
          - string
        entity_type:
          description: The type of entity to associate with the workflow - different workflows require different entities.
          enum:
          - opportunity
          - application
          - award_recommendation
          type:
          - string
        entity_id:
          type: string
          format: uuid
          description: The ID of the entity, for example an opportunity_id
          example: 123e4567-e89b-12d3-a456-426614174000
      required:
      - entity_id
      - entity_type
      - workflow_type
    WorkflowEventRequestSchema:
      type: object
      properties:
        event_type:
          description: 'The category of event: either starting a new workflow or processing an existing one'
          enum:
          - start_workflow
          - process_workflow
          type:
          - string
        start_workflow_context:
          description: Context and entities required to initialize a new workflow. Only allowed if event_type is 'start_workflow'.
          type:
          - object
          $ref: '#/components/schemas/StartWorkflowContextSchema'
        process_workflow_context:
          description: Information required to progress an existing workflow state. Only allowed if event_type is 'process_workflow'.
          type:
          - object
          $ref: '#/components/schemas/ProcessWorkflowContextSchema'
        metadata:
          type: object
          default: {}
          description: 'A freeform JSON object for the particular event, if needed[cite: 127].'
          example:
            source_system: grants_solutions
            priority: high
          additionalProperties: {}
      required:
      - event_type
    WorkflowGetResponseDataSchema:
      type: object
      properties:
        workflow_id:
          type: string
          format: uuid
          description: The workflow's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        workflow_type:
          description: The type of workflow
          example:
          - opportunity_publish
          enum:
          - opportunity_publish
          - application_submission
          - initial_prototype
          - basic_test_workflow
          - no_concurrent_test_workflow
          - limited_approval_test_workflow
          type:
          - string
        current_workflow_state:
          type: string
          description: The current state in the workflow
          example: draft
        is_active:
          type: boolean
          description: Whether the workflow is active (false when workflow reaches end state)
          example: true
        created_at:
          type: string
          format: date-time
          description: When the workflow was created
        updated_at:
          type: string
          format: date-time
          description: When the workflow was last updated
        workflow_audit_events:
          type: array
          description: Ordered list of audit events (sorted by created_at)
          items:
            type:
            - object
            $ref: '#/components/schemas/WorkflowAuditEventSchema'
        workflow_approvals:
          type: array
          description: Ordered list of approvals (sorted by created_at)
          items:
            type:
            - object
            $ref: '#/components/schemas/WorkflowApprovalSchema'
        workflow_approval_config:
          type: object
          description: Configuration mapping event names to approval requirements and possible users
          example:
            receive_program_officer_approval:
              approval_type: PROGRAM_OFFICER_APPROVAL
              required_privileges:
              - PROGRAM_OFFICER_APPROVAL
              possible_users: []
          additionalProperties:
            type:
            - object
            $ref: '#/components/schemas/WorkflowApprovalConfigItemSchema'
        valid_events:
          type: array
          description: List of events that can be sent for the current workflow state. Empty if the workflow is no longer active.
          example:
          - receive_program_officer_approval
          items:
            type: string
        opportunity_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The opportunity ID if this is an opportunity workflow
          example: 123e4567-e89b-12d3-a456-426614174000
        application_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The application ID if this is an application workflow
          example: 123e4567-e89b-12d3-a456-426614174000
        application_submission_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The application submission ID if this is a submission workflow
          example: 123e4567-e89b-12d3-a456-426614174000
    WorkflowEventHistorySchema:
      type: object
      properties:
        event_id:
          type: string
          format: uuid
          description: The tracking ID for the workflow event
          example: 123e4567-e89b-12d3-a456-426614174000
        sent_at:
          type: string
          format: date-time
          description: When the event was sent
    WorkflowAuditRequestSchema:
      type: object
      properties:
        pagination:
          description: Pagination parameters for the workflow audit events
          type:
          - object
          $ref: '#/components/schemas/WorkflowAuditPaginationSchema'
      required:
      - pagination
    WorkflowAuditPaginationSchema:
      type: object
      properties:
        sort_order:
          type: array
          default:
          - order_by: created_at
            sort_direction: descending
          minItems: 1
          maxItems: 5
          description: The list of sorting rules
          items:
            type:
            - object
            $ref: '#/components/schemas/SortOrderWorkflowAuditPaginationSchema'
        page_size:
          type: integer
          default: 25
          minimum: 1
          maximum: 5000
          description: The size of the page to fetch
          example: 25
        page_offset:
          type: integer
          default: 1
          minimum: 1
          description: The page number to fetch, starts counting from 1
          example: 1
    WorkflowApprovalConfigItemSchema:
      type: object
      properties:
        approval_type:
          description: The type of approval required
          example:
          - program_officer_approval
          enum:
          - initial_prototype_approval
          - program_officer_approval
          - budget_officer_approval
          type:
          - string
        required_privileges:
          type: array
          description: List of privileges required to provide this approval
          example:
          - - program_officer_approval
          items:
            enum:
            - manage_org_members
            - manage_org_admin_members
            - view_org_membership
            - start_application
            - list_application
            - view_application
            - modify_application
            - submit_application
            - update_form
            - manage_agency_members
            - get_submitted_applications
            - legacy_agency_viewer
            - legacy_agency_grant_retriever
            - legacy_agency_assigner
            - manage_internal_roles
            - manage_competition
            - read_test_user_token
            - view_opportunity
            - create_opportunity
            - update_opportunity
            - publish_opportunity
            - internal_workflow_access
            - view_org_saved_opportunities
            - modify_org_saved_opportunities
            - internal_workflow_event_send
            - view_award_recommendation
            - create_award_recommendation
            - update_award_recommendation
            - submit_award_recommendation
            - program_officer_approval
            - budget_officer_approval
            - internal_s3_scan
            type:
            - string
        allowed_approval_response_types:
          type: array
          description: List of approval response types allowed for this approval
          example:
          - - approved
          - - requires_modification
          items:
            enum:
            - approved
            - declined
            - requires_modification
            type:
            - string
        possible_users:
          type: array
          description: List of users in the workflow's agency who have the required privileges
          items:
            type:
            - object
            $ref: '#/components/schemas/WorkflowUserSchema'
    WorkflowGetResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: The message to return
          example: Success
        data:
          description: The workflow details with audit history and approval configuration
          type:
          - object
          $ref: '#/components/schemas/WorkflowGetResponseDataSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    SortOrderWorkflowAuditPaginationSchema:
      type: object
      properties:
        order_by:
          type: string
          enum:
          - created_at
          description: The field to sort the response by
        sort_direction:
          description: Whether to sort the response ascending or descending
          enum:
          - ascending
          - descending
          type:
          - string
      required:
      - order_by
      - sort_direction
    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
    WorkflowAuditResponseSchema:
      type: object
      properties:
        pagination_info:
          description: The pagination information for paginated endpoints
          type:
          - object
          $ref: '#/components/schemas/PaginationInfoSchema'
        message:
          type: string
          description: The message to return
          example: Success
        data:
          type: array
          description: Ordered list of audit events (sorted by created_at)
          items:
            type:
            - object
            $ref: '#/components/schemas/WorkflowAuditEventSchema'
        status_code:
          type: integer
          description: The HTTP status code
          example: 200
    WorkflowAuditEventSchema:
      type: object
      properties:
        workflow_audit_id:
          type: string
          format: uuid
          description: The audit event's unique identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        acting_user:
          description: The user who triggered the transition
          type:
          - object
          $ref: '#/components/schemas/WorkflowUserSchema'
        transition_event:
          type: string
          description: The event that triggered the state transition
          example: approve
        source_state:
          type: string
          description: The state before the transition
          example: pending_review
        target_state:
          type: string
          description: The state after the transition
          example: approved
        event:
          description: The workflow event that triggered this audit
          type:
          - object
          $ref: '#/components/schemas/WorkflowEventHistorySchema'
        audit_metadata:
          type:
          - object
          - 'null'
          description: Additional metadata about the audit event
          example:
            comment: Looks good
          additionalProperties: {}
        created_at:
          type: string
          format: date-time
          description: When the audit event was created
    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
  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