Reference

Workflow Endpoints


Workflow Execution

Execute Workflow

Start a new workflow execution.

1
POST /api/v1/workflows/execute
2
Authorization: Bearer <token>
3
Content-Type: application/json
4
5
{
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.99
13
},
14
"execution_timeout": 3600,
15
"retry_policy": {
16
"max_attempts": 3,
17
"initial_interval": 1,
18
"backoff_coefficient": 2.0,
19
"maximum_interval": 60
20
}
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

1
GET /api/v1/executions/:execution_id/status
2
Authorization: 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": 100
13
}
14
}

Status Values:

  • pending - Execution queued
  • running - Currently executing
  • completed - Finished successfully
  • failed - Execution failed
  • canceled - Canceled by user
  • timed_out - Exceeded timeout

Get Execution Result

1
GET /api/v1/executions/:execution_id/result
2
Authorization: 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

1
POST /api/v1/executions/:execution_id/cancel
2
Authorization: Bearer <token>
3
Content-Type: application/json
4
5
{
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.

1
POST /api/v1/executions/:execution_id/reset
2
Authorization: Bearer <token>
3
Content-Type: application/json
4
5
{
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

1
GET /api/v1/executions?workflow_type=order_processing&status=running&limit=50&offset=0
2
Authorization: Bearer <token>

Query Parameters:

  • workflow_type - Filter by workflow type
  • status - Filter by status
  • workflow_id - Filter by workflow ID
  • from - 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": true
15
}

Get Execution Logs

1
GET /api/v1/executions/:execution_id/logs?level=info&limit=100
2
Authorization: Bearer <token>

Query Parameters:

  • level - Filter by log level (debug, info, warn, error)
  • limit - Number of logs to return
  • from - Start timestamp
  • to - 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": 1500
19
}
20
}
21
],
22
"total": 45
23
}

Stream Execution Logs (SSE)

Stream real-time logs using Server-Sent Events.

1
GET /api/v1/executions/:execution_id/logs/stream
2
Authorization: Bearer <token>
3
Accept: text/event-stream

Response (SSE Stream):

1
event: log
2
data: {"timestamp":"2024-01-07T12:00:01Z","level":"info","message":"Workflow started"}
3
4
event: log
5
data: {"timestamp":"2024-01-07T12:00:05Z","level":"info","message":"Task completed"}
6
7
event: complete
8
data: {"execution_id":"exec_abc123","status":"completed"}

Next Steps