Create and start a flow execution
Create a new flow execution and start workflow processing.
This endpoint creates a flow execution record and immediately starts the associated workflow processing. The execution is created with status 'running' and will be processed asynchronously by the execution engine.
Context: - Flow executions represent runtime instances of flow definitions - Each execution is isolated and maintains its own state - Input data must conform to the flow's input schema - Executions are scoped to the user's organization - WebSocket notifications are sent on creation for real-time updates
Execution Flow: 1. Validates flow exists and user has access 2. Creates execution record in database 3. Starts workflow processing asynchronously 4. Sends WebSocket notification to connected clients 5. Returns immediately (does not wait for completion)
Performance Notes: - Response time: < 200ms (workflow starts asynchronously) - Does not block on workflow completion - WebSocket notifications sent in background task
Use Cases: - Trigger flow execution from UI dashboard - Automated flow execution via API integration - Batch processing of multiple documents - Event-driven workflow automation
Related Endpoints: - GET /flow-executions/{id} - Check execution status - GET /flow-executions - List all executions for a flow - POST /flow-executions/{id}/execute - Re-execute failed execution
Header Parameters
Body Parameters
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.
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.
Show child attributes
Response
Response Attributes
UUID of the flow definition being executed. References the parent flow that defines the workflow structure.
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.
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.
Show child attributes
UUID of the organization that owns this execution. Used for access control and data isolation. All executions are scoped to an organization.
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.
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.
Show child attributes
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.
Show child attributes
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.
Show child attributes
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.
Show child attributes
Response Attributes
Show child attributes
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.