Skip to main content
POST
Create and start a flow execution

Authorizations

X-API-Key
string
header
required

API key authentication. Include your API key in the X-API-Key header as: X-API-Key YOUR_API_KEY

Example:

Authorization
string
header
required

JWT Bearer token authentication. Include your access token in the Authorization header as: Bearer YOUR_ACCESS_TOKEN

Example:

Body

application/json

Request payload for creating a new flow execution.

This model defines the required data to start a new flow execution. The input schema must match the flow definition's expected input structure.

flow_id
string<uuid>
required

UUID of the flow definition to execute. Must be a valid, active flow accessible to your organization. The flow defines the workflow structure and task sequence.

Example:

"550e8400-e29b-41d4-a716-446655440000"

input
Input · object
required

Input data for the flow execution. Schema is flow-specific. Common patterns: - Document processing: {'file_key': 'path/to/file.pdf'} - Data processing: {'document_url': 'gs://bucket/file.csv'} - Email processing: {'message_id': 'msg_123', 'attachments': []} Refer to flow definition for exact schema requirements.

Example:

Response

Flow execution created and started successfully

Response model for flow execution operations.

Represents a single flow execution instance with its current state and metadata. Flow executions are runtime instances of flow definitions that process input data through a series of tasks defined in the flow's workflow.

created_at
string<date-time>
required
flow_id
string<uuid>
required

UUID of the flow definition being executed. References the parent flow that defines the workflow structure.

Example:

"550e8400-e29b-41d4-a716-446655440000"

flow_version
integer
required

Version number of the flow definition used for this execution. Execution continues on the same version even if flow is updated. Ensures consistency throughout execution lifecycle.

Required range: x >= 1
Example:

3

id
string<uuid>
required
input
Input · object
required

Input data provided when execution was created. Schema is defined by the flow definition. Commonly includes: file_key, document_url, or custom parameters. Structure varies by flow type.

Example:
modified_by
string
required
organization_id
string<uuid>
required

UUID of the organization that owns this execution. Used for access control and data isolation. All executions are scoped to an organization.

Example:

"660e8400-e29b-41d4-a716-446655440001"

status
string
required

Current execution status. Possible values: 'queued', 'running', 'in_progress', 'completed', 'failed', 'deleted', 'stale'. Status transitions: queued → running → in_progress → completed/failed. Use 'completed' to indicate success, 'failed' for errors.

Example:

"running"

updated_at
string<date-time>
required