Workflow Endpoints
Workflow Execution
Execute Workflow
Start a new workflow execution.
1POST /api/v1/workflows/execute2Authorization: Bearer <token>3Content-Type: application/json45{6 "workflow_type": "order_processing",7 "workflow_id": "order-12345",8 "task_queue": "orders",9 "input": {10 "order_id": "12345",11 "customer_id": "cust_789",12 "amount": 99.9913 },14 "execution_timeout": 3600,15 "retry_policy": {16 "max_attempts": 3,17 "initial_interval": 1,18 "backoff_coefficient": 2.0,19 "maximum_interval": 6020 }21}Response:
1{2 "execution_id": "exec_abc123",3 "workflow_id": "order-12345",4 "run_id": "run_xyz789",5 "status": "running",6 "created_at": "2024-01-07T12:00:00Z"7}Get Execution Status
1GET /api/v1/executions/:execution_id/status2Authorization: Bearer <token>Response:
1{2 "execution_id": "exec_abc123",3 "workflow_id": "order-12345",4 "run_id": "run_xyz789",5 "status": "completed",6 "started_at": "2024-01-07T12:00:00Z",7 "completed_at": "2024-01-07T12:05:30Z",8 "duration_ms": 330000,9 "progress": {10 "current_step": 5,11 "total_steps": 5,12 "percentage": 10013 }14}Status Values:
pending- Execution queuedrunning- Currently executingcompleted- Finished successfullyfailed- Execution failedcanceled- Canceled by usertimed_out- Exceeded timeout
Get Execution Result
1GET /api/v1/executions/:execution_id/result2Authorization: Bearer <token>Response:
1{2 "execution_id": "exec_abc123",3 "status": "completed",4 "result": {5 "order_id": "12345",6 "payment_status": "succeeded",7 "shipment_tracking": "TRK123456"8 },9 "completed_at": "2024-01-07T12:05:30Z"10}Cancel Execution
1POST /api/v1/executions/:execution_id/cancel2Authorization: Bearer <token>3Content-Type: application/json45{6 "reason": "Customer requested cancellation"7}Response:
1{2 "execution_id": "exec_abc123",3 "status": "canceled",4 "canceled_at": "2024-01-07T12:03:00Z"5}Reset Execution
Rewind a workflow to a specific journal point and re-execute from there. The original execution is marked as "reset" (terminal) and a new execution is created with the journal history preserved up to the target event.
This is useful for recovering from bad deployments, debugging production failures, or retrying from a known-good checkpoint without re-running from scratch.
1POST /api/v1/executions/:execution_id/reset2Authorization: Bearer <token>3Content-Type: application/json45{6 "target_event_id": 5,7 "reason": "Bad deployment caused task failures after step 5"8}Request Body:
target_event_id(required) - Journal event ID to reset to. All events up to and including this ID are preserved; events after it are discarded.reason(optional) - Human-readable reason recorded in the journal.
Response:
1{2 "new_execution_id": "exec_def789",3 "old_execution_id": "exec_abc123"4}The new execution replays the preserved journal (completed steps are skipped via cache), then continues executing from the reset point making fresh decisions.
List Executions
1GET /api/v1/executions?workflow_type=order_processing&status=running&limit=50&offset=02Authorization: Bearer <token>Query Parameters:
workflow_type- Filter by workflow typestatus- Filter by statusworkflow_id- Filter by workflow IDfrom- Start date (ISO 8601)to- End date (ISO 8601)limit- Results per page (default: 50, max: 100)offset- Pagination offset
Response:
1{2 "executions": [3 {4 "execution_id": "exec_abc123",5 "workflow_id": "order-12345",6 "workflow_type": "order_processing",7 "status": "running",8 "started_at": "2024-01-07T12:00:00Z"9 }10 ],11 "total": 150,12 "limit": 50,13 "offset": 0,14 "has_more": true15}Get Execution Logs
1GET /api/v1/executions/:execution_id/logs?level=info&limit=1002Authorization: Bearer <token>Query Parameters:
level- Filter by log level (debug, info, warn, error)limit- Number of logs to returnfrom- Start timestampto- End timestamp
Response:
1{2 "execution_id": "exec_abc123",3 "logs": [4 {5 "timestamp": "2024-01-07T12:00:01Z",6 "level": "info",7 "message": "Workflow started",8 "context": {9 "step": "initialization"10 }11 },12 {13 "timestamp": "2024-01-07T12:00:05Z",14 "level": "info",15 "message": "Task completed: charge_payment",16 "context": {17 "task_id": "task_123",18 "duration_ms": 150019 }20 }21 ],22 "total": 4523}Stream Execution Logs (SSE)
Stream real-time logs using Server-Sent Events.
1GET /api/v1/executions/:execution_id/logs/stream2Authorization: Bearer <token>3Accept: text/event-streamResponse (SSE Stream):
1event: log2data: {"timestamp":"2024-01-07T12:00:01Z","level":"info","message":"Workflow started"}34event: log5data: {"timestamp":"2024-01-07T12:00:05Z","level":"info","message":"Task completed"}67event: complete8data: {"execution_id":"exec_abc123","status":"completed"}Next Steps
- Task Endpoints -- Submit and track tasks
- Management Endpoints -- Users, organizations, and registry
- Errors & Limits -- Error handling and rate limiting
- Best Practices & Examples -- Usage patterns and code examples