openapi: 3.1.0
info:
title: SuperAI Flow Platform auth flow-executions 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: flow-executions
description: 'Flow execution operations for running and monitoring workflows.
Flow executions represent runtime instances of flows. When you execute a flow, a new flow execution is created with its own unique ID, status, and execution context. Each execution is independent and maintains its own state, input data, and results.
**Key concepts:**
- **Execution Status**: Tracks the lifecycle (running, completed, failed, cancelled)
- **Run Number**: Sequential identifier for executions of the same flow
- **Execution Context**: Contains input parameters, user information, and metadata
- **Task Results**: Stores outputs from each task within the execution
**Use these endpoints to:**
- Start new flow executions with custom input parameters
- Monitor execution progress and status in real-time
- Retrieve execution history and detailed results
- Filter and search executions by status, date, or flow
- Cancel running executions when needed
- Access task-level execution details and outputs
Flow executions transform flow definitions into actual work and deliverable results.'
x-displayName: Flow Executions
paths:
/api/flow-executions:
post:
tags:
- flow-executions
summary: Create and start a flow execution
description: "Create a new flow execution and start workflow processing.\n\nThis endpoint creates a flow execution record and attempts to start the associated\nworkflow processing. The execution is created with status 'queued' and atomically\npromoted to 'running' if the organization's concurrency limit allows.\n\nContext:\n - Flow executions represent runtime instances of flow definitions\n - Each execution is isolated and maintains its own state\n - Input data must conform to the flow's input schema\n - Executions are scoped to the user's organization\n - WebSocket notifications are sent on creation for real-time updates\n\nInput Validation:\n - Input data is validated against the flow's input task schema\n - Validation occurs before database record creation or workflow start\n - Invalid input returns 400 Bad Request with detailed error messages\n - Validation errors include field location, type, and specific issue\n - No flow execution record is created if validation fails\n\nExecution Flow:\n 1. Validates flow exists and user has access\n 2. Validates input data against flow's input schema\n 3. Creates execution record in database\n 4. Starts workflow processing asynchronously\n 5. Sends WebSocket notification to connected clients\n 6. Returns immediately (does not wait for completion)\n\nPerformance Notes:\n - Response time: < 200ms (workflow starts asynchronously)\n - Does not block on workflow completion\n - WebSocket notifications sent in background task\n\nUse Cases:\n - Trigger flow execution from UI dashboard\n - Automated flow execution via API integration\n - Batch processing of multiple documents\n - Event-driven workflow automation\n\nRelated Endpoints:\n - GET /flow-executions/{id} - Check execution status\n - GET /flow-executions - List all executions for a flow\n - POST /flow-executions/{id}/execute - Re-execute failed execution"
operationId: create_flow_execution_api_flow_executions_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FlowExecutionCreateRequest'
responses:
'201':
description: Flow execution created and started successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FlowExecutionResponse'
'400':
description: Bad Request - Invalid input data or missing required fields
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden - User lacks permission to execute this flow
content:
application/json:
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'
'402':
description: Payment Required - Organization has exhausted its credit allocation
content:
application/json:
examples:
credit_limit_exceeded:
summary: Credit limit exceeded
value:
error:
message: Your organization has exhausted its credit allocation.
code: insufficient_credits
details:
credits_used: 25000
allocation: 25000
credits_remaining: 0
request_id: 01K8KABR6S16YETA2SZPVBS9SP
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'
'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: []
get:
tags:
- flow-executions
summary: List flow executions with filtering and pagination
description: "List flow executions with filtering, sorting, and pagination.\n\nRetrieve a paginated list of flow executions for a specific flow with support\nfor filtering by status, tags, and date ranges. Results can be sorted by\ncreation or update time and include optional run number calculation.\n\nContext:\n - Returns executions for a single flow (specified by flow_id)\n - Excludes soft-deleted executions from results\n - Supports multiple filtering dimensions for flexible queries\n - Pagination uses offset-based approach (page/page_size)\n - Run numbers calculated on-demand (performance impact)\n\nFiltering Logic:\n - Status filter: Returns executions containing tasks with ANY of specified statuses\n - Tag filter: Returns executions containing tasks with ANY of specified tags\n - Date range: created_after/created_before bound created_at;\n updated_after/updated_before bound updated_at (all inclusive, ISO 8601)\n - Multiple filters combined with AND logic\n - Empty filters return all executions\n\nPagination:\n - Offset-based: page=1, page_size=10 returns first 10 results\n - Default: page=1, page_size=10\n - Maximum page_size: 1000 results\n - Maximum page: 10,000 (to prevent excessive database load)\n - Use start_from_execution_id for cursor-like pagination\n\nRun Numbers:\n - include_run_number=true: Calculates sequential number (1, 2, 3...)\n - Based on creation time for the flow\n - Includes deleted executions in count (may have gaps)\n - Performance impact: Additional database query per execution\n - Recommended: Use only when displaying in UI\n\nSorting:\n - sort_field: 'created_at' (when execution was created) or\n 'updated_at' (when execution was last modified)\n - sort_direction: 'asc' (oldest first) or 'desc' (newest first)\n - Default: sort by created_at desc (most recently created first)\n\nPerformance Considerations:\n - Without run_number: ~50ms for 100 results\n - With run_number: ~200ms for 100 results (N+1 query issue)\n - Consider caching for frequently accessed pages\n - Large page_size values increase response time linearly\n\nUse Cases:\n - Display execution history in UI dashboard\n - Monitor recent execution failures (filter by status='failed')\n - Find executions by business context (filter by tags)\n - Export execution audit trail\n - Identify oldest pending executions (sort by created_at asc)\n\nExample Queries:\n - Recent failures: ?flow_id=xxx&status=failed&sort_field=created_at&sort_direction=desc&page_size=20\n - Tagged executions: ?flow_id=xxx&tags=priority:high&tags=customer:acme\n - Paginated view: ?flow_id=xxx&page=2&page_size=50\n - With run numbers: ?flow_id=xxx&include_run_number=true\n - Completed in window: ?flow_id=xxx&status=completed&created_after=2026-06-18T08:00:00Z&created_before=2026-06-18T10:00:00Z\n\nRelated Endpoints:\n - GET /flow-executions/{id} - Get single execution details\n - POST /flow-executions - Create new execution\n - GET /flows/{id} - Get flow definition details"
operationId: list_flow_executions_api_flow_executions_get
parameters:
- name: flow_id
in: query
required: true
schema:
type: string
format: uuid
description: UUID of the flow to list executions for. Required parameter.
title: Flow Id
description: UUID of the flow to list executions for. Required parameter.
example: 550e8400-e29b-41d4-a716-446655440000
- name: sort_field
in: query
required: false
schema:
anyOf:
- type: string
pattern: ^(created_at|updated_at)$
- type: 'null'
description: 'Field to sort results by. Valid values: ''created_at'', ''updated_at''. Defaults to ''created_at'' for most recently modified first.'
title: Sort Field
description: 'Field to sort results by. Valid values: ''created_at'', ''updated_at''. Defaults to ''created_at'' for most recently modified first.'
example: created_at
- name: sort_direction
in: query
required: false
schema:
anyOf:
- type: string
pattern: ^(asc|desc)$
- type: 'null'
description: 'Sort order direction. Valid values: ''asc'' (ascending), ''desc'' (descending). Defaults to ''desc'' for newest first.'
title: Sort Direction
description: 'Sort order direction. Valid values: ''asc'' (ascending), ''desc'' (descending). Defaults to ''desc'' for newest first.'
example: desc
- name: status
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: 'Filter by flow execution status. Can specify multiple values. Valid values: ''queued'', ''running'', ''completed'', ''failed'', ''stale'', ''awaiting_input'', ''cancel_requested'', ''cancelled'', ''edited''. Returns executions whose overall status matches ANY of the specified values. Example: ?status=failed&status=running'
title: Status
description: 'Filter by flow execution status. Can specify multiple values. Valid values: ''queued'', ''running'', ''completed'', ''failed'', ''stale'', ''awaiting_input'', ''cancel_requested'', ''cancelled'', ''edited''. Returns executions whose overall status matches ANY of the specified values. Example: ?status=failed&status=running'
example:
- running
- completed
- name: status_exclude
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: 'Exclude flow executions whose status matches any of these values. Mirrors tags/tags_exclude. Combines with `status` using AND. Example: ?status_exclude=queued hides queued runs from the result and total count.'
title: Status Exclude
description: 'Exclude flow executions whose status matches any of these values. Mirrors tags/tags_exclude. Combines with `status` using AND. Example: ?status_exclude=queued hides queued runs from the result and total count.'
example:
- queued
- name: tags
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: 'Filter by task tags. Can specify multiple values. Returns executions containing tasks with ANY of the specified tags. Tags use key:value format. Example: ?tags=priority:high&tags=env:prod'
title: Tags
description: 'Filter by task tags. Can specify multiple values. Returns executions containing tasks with ANY of the specified tags. Tags use key:value format. Example: ?tags=priority:high&tags=env:prod'
example:
- priority:high
- department:finance
- name: include_run_number
in: query
required: false
schema:
type: boolean
description: 'Calculate sequential run number for each execution. Run numbers start at 1 and increment based on creation time. Warning: Adds performance overhead (~150ms per 100 executions). Recommended only for UI display purposes.'
default: false
title: Include Run Number
description: 'Calculate sequential run number for each execution. Run numbers start at 1 and increment based on creation time. Warning: Adds performance overhead (~150ms per 100 executions). Recommended only for UI display purposes.'
example: false
- name: page
in: query
required: false
schema:
type: integer
maximum: 10000
minimum: 1
description: 'Page number for pagination (1-indexed). Minimum: 1, Maximum: 10,000. Works with page_size to implement offset-based pagination.'
default: 1
title: Page
description: 'Page number for pagination (1-indexed). Minimum: 1, Maximum: 10,000. Works with page_size to implement offset-based pagination.'
example: 1
- name: page_size
in: query
required: false
schema:
type: integer
maximum: 1000
minimum: 1
description: 'Number of results to return per page. Minimum: 1, Maximum: 1000. Larger values increase response time. Recommended: 10-100.'
default: 10
title: Page Size
description: 'Number of results to return per page. Minimum: 1, Maximum: 1000. Larger values increase response time. Recommended: 10-100.'
example: 10
- name: start_from_execution_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
description: Start listing after this execution ID. Provides cursor-like pagination. When combined with sort parameters, returns results after the specified execution. Useful for infinite scroll or keyset pagination patterns.
title: Start From Execution Id
description: Start listing after this execution ID. Provides cursor-like pagination. When combined with sort parameters, returns results after the specified execution. Useful for infinite scroll or keyset pagination patterns.
example: 550e8400-e29b-41d4-a716-446655440000
- name: created_after
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Return executions created at or after this timestamp (inclusive). Accepts ISO 8601 (e.g. '2026-06-18T08:00:00Z'). Combined with other filters using AND.
title: Created After
description: Return executions created at or after this timestamp (inclusive). Accepts ISO 8601 (e.g. '2026-06-18T08:00:00Z'). Combined with other filters using AND.
example: '2026-06-18T08:00:00Z'
- name: created_before
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Return executions created at or before this timestamp (inclusive). Accepts ISO 8601 (e.g. '2026-06-18T10:00:00Z'). Combined with other filters using AND.
title: Created Before
description: Return executions created at or before this timestamp (inclusive). Accepts ISO 8601 (e.g. '2026-06-18T10:00:00Z'). Combined with other filters using AND.
example: '2026-06-18T10:00:00Z'
- name: updated_after
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Return executions last updated at or after this timestamp (inclusive). Accepts ISO 8601. Combined with other filters using AND.
title: Updated After
description: Return executions last updated at or after this timestamp (inclusive). Accepts ISO 8601. Combined with other filters using AND.
example: '2026-06-18T08:00:00Z'
- name: updated_before
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Return executions last updated at or before this timestamp (inclusive). Accepts ISO 8601. Combined with other filters using AND.
title: Updated Before
description: Return executions last updated at or before this timestamp (inclusive). Accepts ISO 8601. Combined with other filters using AND.
example: '2026-06-18T10:00:00Z'
- name: include_credits
in: query
required: false
schema:
type: boolean
description: Include total credits consumed by each execution in the response. When false (default), total_credits is null and the usage table is not queried. Adds a single bulk usage-table lookup for the page when enabled.
default: false
title: Include Credits
description: Include total credits consumed by each execution in the response. When false (default), total_credits is null and the usage table is not queried. Adds a single bulk usage-table lookup for the page when enabled.
example: false
responses:
'200':
description: List of flow executions successfully retrieved
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FlowExecutionResponseWithRunNumber'
title: Response List Flow Executions Api Flow Executions Get
'400':
description: Bad Request - Invalid query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden - User lacks permission to view this flow's executions
content:
application/json:
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: Unprocessable Entity - Request validation failed
content:
application/json:
examples:
validation_error:
summary: Validation error
value:
error:
message: Request validation failed
code: validation_error
details:
- type: missing
loc:
- body
- name
msg: Field required
request_id: 01K8KABR6S16YETA2SZPVBS9SP
type_error:
summary: Type validation error
value:
error:
message: Request validation failed
code: validation_error
details:
- type: uuid_parsing
loc:
- path
- flow_id
msg: Input should be a valid UUID
input: not-a-uuid
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'
security:
- BearerAuth: []
- APIKeyAuth: []
/api/flow-executions/{flow_execution_id}:
delete:
tags:
- flow-executions
summary: Soft delete a flow execution
description: "Soft delete a flow execution by marking it as deleted.\n\nThis endpoint performs a soft delete by setting the execution status to 'deleted'.\nThe execution record remains in the database but is excluded from list operations\nand cannot be retrieved through standard endpoints.\n\nContext:\n - Soft delete preserves audit trail and historical data\n - Does NOT stop running workflows (use cancel endpoint for that)\n - Deleted executions do not appear in GET /flow-executions list\n - Operation is idempotent - deleting already deleted execution succeeds\n - Deletion is permanent - no undelete functionality exists\n\nBehavior:\n - Updates execution status to 'deleted' in database\n - Maintains all execution data for audit purposes\n - Removes from user-facing list queries\n - Does not affect related task executions or outputs\n - Triggers WebSocket notification for status change\n\nUse Cases:\n - Remove test executions from production environment\n - Clean up failed executions no longer needed\n - Archive old executions while preserving data\n\nImportant Notes:\n - To stop a RUNNING workflow, use cancel endpoint (not yet implemented)\n - Soft delete does not free up workflow resources\n - Consider hard delete for GDPR compliance (requires database migration)\n\nRelated Endpoints:\n - GET /flow-executions - List excludes deleted executions\n - POST /flow-executions - Create new execution"
operationId: delete_flow_execution_api_flow_executions__flow_execution_id__delete
parameters:
- name: flow_execution_id
in: path
required: true
schema:
type: string
format: uuid
description: UUID of the flow execution to soft delete. Must be owned by your organization.
title: Flow Execution Id
description: UUID of the flow execution to soft delete. Must be owned by your organization.
example: 550e8400-e29b-41d4-a716-446655440000
responses:
'204':
description: Flow execution successfully soft deleted
'403':
description: Forbidden - User lacks permission to delete this execution
content:
application/json:
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'
'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: []
get:
tags:
- flow-executions
summary: Retrieve a specific flow execution
description: "Retrieve detailed information for a specific flow execution.\n\nFetch a single flow execution by its unique identifier. Returns execution\nmetadata including status, input data, timestamps, and optionally the\nsequential run number within its flow.\n\nContext:\n - Retrieves single execution regardless of status (except deleted)\n - Soft-deleted executions return 404 Not Found\n - Includes full input data as provided at creation\n - Run number calculated on-demand if requested\n - Useful for monitoring execution progress\n\nRun Number Calculation:\n - When include_run_number=true, calculates sequential position\n - Based on creation timestamp among all executions for this flow\n - Includes deleted executions (may have gaps in visible numbers)\n - Performance: Adds ~10-20ms per request\n - Useful for displaying \"Run #42\" in UI\n\nUse Cases:\n - Check status of long-running execution\n - Retrieve input data for debugging\n - Display execution details in UI\n - Audit execution history with run numbers\n - Poll for execution completion\n\nPerformance Notes:\n - Without run_number: ~10ms average response time\n - With run_number: ~25ms average response time\n - Highly cacheable (status changes infrequently)\n\nRelated Endpoints:\n - GET /flow-executions - List all executions for a flow\n - POST /flow-executions/{id}/execute - Re-execute this execution\n - GET /task-executions?flow_execution_id={id} - Get task details\n - DELETE /flow-executions/{id} - Delete this execution"
operationId: get_flow_execution_api_flow_executions__flow_execution_id__get
parameters:
- name: flow_execution_id
in: path
required: true
schema:
type: string
format: uuid
description: UUID of the flow execution to retrieve. Must exist and not be soft-deleted.
title: Flow Execution Id
description: UUID of the flow execution to retrieve. Must exist and not be soft-deleted.
example: 550e8400-e29b-41d4-a716-446655440000
- name: include_run_number
in: qu
# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/superai/refs/heads/main/openapi/superai-flow-executions-api-openapi.yml