Super.ai flows API

openapi: 3.1.0
info:
  title: SuperAI Flow Platform auth flows API
  description: "SuperAI Flows is a workflow orchestration platform that enables you to design, deploy, and monitor automated workflows at scale.\n\nBuild complex workflows using our declarative YAML DSL, execute them reliably, and integrate seamlessly with AI models, cloud storage, and enterprise systems.\n\n**Key Capabilities:**\n- **Workflow Management**: Define workflows as code with version control and automated execution\n- **Task Orchestration**: Chain together API calls, data processing, and AI operations\n- **Real-time Monitoring**: Track execution progress with WebSocket notifications and comprehensive logging\n- **Multi-tenant Architecture**: Organization-scoped resources with role-based access control\n\n**API Versioning and Breaking Changes:**\n\nWe follow a strict compatibility policy to ensure your integrations remain stable:\n\n- **Non-breaking changes** (safe, no action required):\n  - Adding new API endpoints\n  - Adding new optional query parameters to existing endpoints\n  - Adding new fields to API responses\n  - Adding new values to existing enums\n\n- **Breaking changes** (requires client updates):\n  - Removing or renaming API endpoints\n  - Removing query parameters or request fields\n  - Removing response fields\n  - Changing field types or validation rules\n  - Removing values from existing enums\n\n**Client Implementation Requirements:**\n\nYour API clients MUST be designed to gracefully handle additional fields in responses. We may add new fields to any response object without considering this a breaking change. Ensure your JSON parsers ignore unknown fields rather than raising errors.\n\n**Backward Compatibility Guarantee:**\n\nWe commit to maintaining backward compatibility for all non-breaking changes. Breaking changes will be:\n- Announced at least 15 days in advance\n- Documented in our changelog with migration guide\n\nFor the latest API updates and migration guides, see our changelog."
  version: 0.1.0
tags:
- name: flows
  description: 'Flow management operations for defining and organizing workflows.


    Flows represent workflow definitions with tasks, dependencies, and execution logic. They serve as reusable templates that can be executed multiple times with different inputs.


    **What is a flow?**

    A flow consists of:

    - **Tasks**: Individual units of work that perform specific actions

    - **Dependencies**: Relationships between tasks that define execution order

    - **Configuration**: Settings and parameters that control flow behavior


    **Use these endpoints to:**

    - Create new flow definitions from scratch or import from YAML

    - List and search existing flows in your organization

    - Retrieve detailed flow information including task definitions

    - Update flow configurations and task parameters

    - Delete flows that are no longer needed


    Flows are the foundation of your workflow automation—once defined, they can be executed via the flow-executions endpoints.'
  x-displayName: Flows
paths:
  /api/flows:
    get:
      tags:
      - flows
      summary: List all flows
      description: 'List all flows accessible to the authenticated user.


        Returns flows within the user''s organization with pagination, sorting, and search support.

        Each flow includes its latest version by default.


        ## Pagination

        Results are paginated with a default page size of 20. Use `page` and `page_size` parameters

        to navigate through results.


        ## Sorting

        Sort by `created_at` or `updated_at` in `asc` or `desc` direction.

        Default: `created_at` descending (newest first).


        ## Search

        Use `search` parameter for case-insensitive search on flow display names.


        ## Expansion Parameters

        Use query parameters to include additional computed fields. See FlowResponse model

        documentation for details on available expansion parameters and their performance impact.'
      operationId: list_flows_api_flows_get
      parameters:
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search flows by display name (case-insensitive)
          title: Search
        description: Search flows by display name (case-insensitive)
      - name: sort_field
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(created_at|updated_at|display_name)$
          - type: 'null'
          description: Field to sort by
          title: Sort Field
        description: Field to sort by
      - name: sort_direction
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(asc|desc)$
          - type: 'null'
          description: Sort direction
          title: Sort Direction
        description: Sort direction
      - name: page
        in: query
        required: false
        schema:
          type: integer
          maximum: 10000
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Number of items per page
          default: 20
          title: Page Size
        description: Number of items per page
      - name: tag_filters
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: JSON-encoded list of tag filter groups. Each group has 'mode' and 'values'.
          title: Tag Filters
        description: JSON-encoded list of tag filter groups. Each group has 'mode' and 'values'.
      - name: is_cleanable
        in: query
        required: false
        schema:
          type: boolean
          description: When true, returns only flows eligible for cleanup (0 tasks, older than 30 days)
          default: false
          title: Is Cleanable
        description: When true, returns only flows eligible for cleanup (0 tasks, older than 30 days)
      - name: created_by_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter flows by creator user ID.
          title: Created By Id
        description: Filter flows by creator user ID.
      - name: organization_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Restrict results to a single organization (backoffice cross-org views).
          title: Organization Id
        description: Restrict results to a single organization (backoffice cross-org views).
      - name: include_latest_version_executions_count
        in: query
        required: false
        schema:
          type: boolean
          description: When true, each flow includes latest_version_executions_count — runs on the most recent version that has any runs (the dataset calibration samples). Off by default to keep the default list query cheap.
          default: false
          title: Include Latest Version Executions Count
        description: When true, each flow includes latest_version_executions_count — runs on the most recent version that has any runs (the dataset calibration samples). Off by default to keep the default list query cheap.
      - name: include_ordered_task_names
        in: query
        required: false
        schema:
          type: boolean
          description: Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.
          default: false
          title: Include Ordered Task Names
        description: Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.
      - name: include_validation_errors
        in: query
        required: false
        schema:
          type: boolean
          description: Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.
          default: false
          title: Include Validation Errors
        description: Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.
      - name: include_dynamic_data
        in: query
        required: false
        schema:
          type: boolean
          description: Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.
          default: false
          title: Include Dynamic Data
        description: Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.
      - name: include_output_schemas
        in: query
        required: false
        schema:
          type: boolean
          description: 'Include JSON Schema definitions for each task''s output structure. Required for building dynamic UIs or validating task connections. '
          default: false
          title: Include Output Schemas
        description: 'Include JSON Schema definitions for each task''s output structure. Required for building dynamic UIs or validating task connections. '
      - name: include_input_schema
        in: query
        required: false
        schema:
          type: boolean
          description: 'Include JSON Schema definitions for input task executors'' input structure. Calls get_input_model() to generate dynamic input schemas for form building. '
          default: false
          title: Include Input Schema
        description: 'Include JSON Schema definitions for input task executors'' input structure. Calls get_input_model() to generate dynamic input schemas for form building. '
      - name: include_default_reference_modes
        in: query
        required: false
        schema:
          type: boolean
          description: Include each task's default reference modes (single/collection) as the task-level 'default_reference_modes' property. Lets the UI show the resolved default instead of an ambiguous 'Default' option. Cheap to compute.
          default: false
          title: Include Default Reference Modes
        description: Include each task's default reference modes (single/collection) as the task-level 'default_reference_modes' property. Lets the UI show the resolved default instead of an ambiguous 'Default' option. Cheap to compute.
      responses:
        '200':
          description: List of flows successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedFlowResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
    post:
      tags:
      - flows
      summary: Create a new flow
      description: 'Create a new flow in draft status.


        Creates a flow definition that can be executed via the flow executions API.

        New flows are assigned version 1 and status ''draft'', allowing iterative development

        before marking as ''published'' for production use.


        ## Flow Lifecycle

        1. **Draft**: Newly created flows start here. Editable and testable.

        2. **Published**: Ready for production. Can be executed by end users.


        ## DSL Validation

        The flow definition is validated against the DSL schema during creation.

        If validation fails, a 400 error is returned with detailed error messages

        in the `details` array.


        ## Common Validation Errors

        - Missing required fields (tasks, edges)

        - Invalid task executor names

        - Circular dependencies in task graph

        - Invalid parameter types for task executors'
      operationId: create_flow_api_flows_post
      parameters:
      - name: include_ordered_task_names
        in: query
        required: false
        schema:
          type: boolean
          description: Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.
          default: false
          title: Include Ordered Task Names
        description: Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.
      - name: include_validation_errors
        in: query
        required: false
        schema:
          type: boolean
          description: Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.
          default: false
          title: Include Validation Errors
        description: Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.
      - name: include_dynamic_data
        in: query
        required: false
        schema:
          type: boolean
          description: Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.
          default: false
          title: Include Dynamic Data
        description: Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.
      - name: include_output_schemas
        in: query
        required: false
        schema:
          type: boolean
          description: 'Include JSON Schema definitions for each task''s output structure. Required for building dynamic UIs or validating task connections. '
          default: false
          title: Include Output Schemas
        description: 'Include JSON Schema definitions for each task''s output structure. Required for building dynamic UIs or validating task connections. '
      - name: include_input_schema
        in: query
        required: false
        schema:
          type: boolean
          description: 'Include JSON Schema definitions for input task executors'' input structure. Calls get_input_model() to generate dynamic input schemas for form building. '
          default: false
          title: Include Input Schema
        description: 'Include JSON Schema definitions for input task executors'' input structure. Calls get_input_model() to generate dynamic input schemas for form building. '
      - name: include_default_reference_modes
        in: query
        required: false
        schema:
          type: boolean
          description: Include each task's default reference modes (single/collection) as the task-level 'default_reference_modes' property. Lets the UI show the resolved default instead of an ambiguous 'Default' option. Cheap to compute.
          default: false
          title: Include Default Reference Modes
        description: Include each task's default reference modes (single/collection) as the task-level 'default_reference_modes' property. Lets the UI show the resolved default instead of an ambiguous 'Default' option. Cheap to compute.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlowCreateRequest'
      responses:
        '201':
          description: Flow created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowResponse'
        '400':
          description: Bad Request - Invalid flow definition or validation errors
          content:
            application/json:
              examples:
                invalid_dsl:
                  summary: Invalid DSL input
                  value:
                    error:
                      message: Invalid DSL input
                      code: invalid_dsl_input
                      details:
                      - 'tasks.1.task_executor_name: Invalid task executor ''invalid_executor'''
                      - 'edges.0.target: Target task ''unknown_task'' does not exist'
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                missing_org:
                  summary: Missing organization ID
                  value:
                    error:
                      message: Organization ID is required
                      code: bad_request
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - The resource already exists or conflicts with existing state
          content:
            application/json:
              examples:
                duplicate_resource:
                  summary: Resource already exists
                  value:
                    error:
                      message: A resource with this identifier already exists
                      code: conflict
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                duplicate_name:
                  summary: Name already in use
                  value:
                    error:
                      message: A flow with this name already exists
                      code: conflict
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
  /api/flows/available-tags:
    get:
      tags:
      - flows
      summary: Get available flow tags for autocomplete
      operationId: get_flow_available_tags_api_flows_available_tags_get
      parameters:
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter tags by substring (case-insensitive)
          title: Search
        description: Filter tags by substring (case-insensitive)
      responses:
        '200':
          description: List of distinct tags successfully retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                title: Response Get Flow Available Tags Api Flows Available Tags Get
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
  /api/flows/{flow_id}:
    get:
      tags:
      - flows
      summary: Retrieve a flow by ID
      description: "Retrieve a specific flow by ID.\n\nReturns the latest version of a flow with its complete definition, metadata, and\noptional computed fields. This endpoint is typically used when displaying flow\ndetails or preparing to execute a flow.\n\n## Behavior\n- Always returns the latest version unless a specific version is requested via\n  `/flows/{flow_id}/versions/{version}`\n- Use expansion parameters to include computed fields (see FlowResponse model docs)\n\n## Use Cases\n- Display flow details in your application UI\n- Retrieve flow definition before execution\n- Check flow validation status and errors"
      operationId: get_flow_api_flows__flow_id__get
      parameters:
      - name: flow_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Flow Id
      - name: include_ordered_task_names
        in: query
        required: false
        schema:
          type: boolean
          description: Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.
          default: false
          title: Include Ordered Task Names
        description: Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.
      - name: include_validation_errors
        in: query
        required: false
        schema:
          type: boolean
          description: Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.
          default: false
          title: Include Validation Errors
        description: Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.
      - name: include_dynamic_data
        in: query
        required: false
        schema:
          type: boolean
          description: Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.
          default: false
          title: Include Dynamic Data
        description: Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.
      - name: include_output_schemas
        in: query
        required: false
        schema:
          type: boolean
          description: 'Include JSON Schema definitions for each task''s output structure. Required for building dynamic UIs or validating task connections. '
          default: false
          title: Include Output Schemas
        description: 'Include JSON Schema definitions for each task''s output structure. Required for building dynamic UIs or validating task connections. '
      - name: include_input_schema
        in: query
        required: false
        schema:
          type: boolean
          description: 'Include JSON Schema definitions for input task executors'' input structure. Calls get_input_model() to generate dynamic input schemas for form building. '
          default: false
          title: Include Input Schema
        description: 'Include JSON Schema definitions for input task executors'' input structure. Calls get_input_model() to generate dynamic input schemas for form building. '
      - name: include_default_reference_modes
        in: query
        required: false
        schema:
          type: boolean
          description: Include each task's default reference modes (single/collection) as the task-level 'default_reference_modes' property. Lets the UI show the resolved default instead of an ambiguous 'Default' option. Cheap to compute.
          default: false
          title: Include Default Reference Modes
        description: Include each task's default reference modes (single/collection) as the task-level 'default_reference_modes' property. Lets the UI show the resolved default instead of an ambiguous 'Default' option. Cheap to compute.
      responses:
        '200':
          description: Flow successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowResponse'
        '403':
          description: Forbidden - User doesn't have access to this flow (wrong organization)
          content:
            application/json:
              example:
                error:
                  message: User doesn't have access to this flow
                  code: forbidden
                request_id: 01K8KABR6S16YETA2SZPVBS9SP
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - The requested resource does not exist
          content:
            application/json:
              examples:
                resource_not_found:
                  summary: Resource not found
                  value:
                    error:
                      message: Resource not found
                      code: not_found
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                flow_not_found:
                  summary: Flow not found
                  value:
                    error:
                      message: Flow not found
                      code: not_found
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
    delete:
      tags:
      - flows
      summary: Delete a flow
      description: 'Soft delete a flow.


        Marks a flow as deleted without permanently removing it from the database.

        Deleted flows are hidden from listings but can be recovered if needed.


        ## Behavior

        - Flow is marked with `deleted=true` flag

        - Flow no longer appears in list/get operations

        - All versions of the flow are marked as deleted

        - Can be recovered by support team if needed


        ## Important Notes

        - This is a soft delete, not a permanent deletion

        - Associated executions and files are NOT deleted

        - Deleted flows cannot be undeleted via API (contact support)'
      operationId: delete_flow_api_flows__flow_id__delete
      parameters:
      - name: flow_id
        in: path
        required: true
        schema:
          type: string
          for

# --- truncated at 32 KB (173 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/superai/refs/heads/main/openapi/superai-flows-api-openapi.yml