Workflow Executions API

Auth: X-Api-Key: ws_...

Trigger your workflow and stream live execution status. Use your Workspace API key — pass an empty allowedWorkflowIds array for unrestricted access, or specify workflow IDs to scope the key.

---

Trigger workflow execution

POST /v1/sdk/workflows/:workflowId

Trigger a new workflow execution.

Request signing required

All REST API calls require X-Sdk-Timestamp (Unix epoch in seconds) and X-Sdk-Signature (base64 Ed25519) headers in addition to the API key. See Authentication →. The TypeScript SDK handles this automatically.

curl -X POST https://api.whiterabbit.app/v1/sdk/workflows/<workflowId> \
  -H "X-Api-Key: ws_..." \
  -H "X-Sdk-Timestamp: <timestamp>" \
  -H "X-Sdk-Signature: <signature>"

Response 200

{
  "runId": "9e4c7b1a-...",
  "jobId": "bull-12345"
}

---

Get workflow execution

GET /v1/sdk/workflows/executions/:runId

Fetch the current state of a run including all stage results.

curl https://api.whiterabbit.app/v1/sdk/workflows/executions/9e4c7b1a-... \
  -H "X-Api-Key: ws_..." \
  -H "X-Sdk-Timestamp: <timestamp>" \
  -H "X-Sdk-Signature: <signature>"

Response 200

{
  "id": "9e4c7b1a-...",
  "status": "COMPLETED",
  "pendingStageCount": 0,
  "failedStageCount": 0,
  "totalUsage": 14,
  "createdAt": "2026-04-20T10:00:00Z",
  "updatedAt": "2026-04-20T10:00:08Z",
  "runStages": [
    {
      "id": "stage-uuid",
      "module": "GET_EVM_ACCOUNT_BALANCE",
      "status": "COMPLETED",
      "output": { "balance": "1000000" },
      "creditUsage": 3,
      "executionAttempt": 1,
      "updatedAt": "2026-04-20T10:00:05Z"
    }
  ]
}

---

Stream workflow execution

SSE /v1/sdk/workflows/executions/:runId/stream

Subscribe to live status updates. Emits events as stages complete. Closes on COMPLETED, FAILED, or CANCELED.

const source = new EventSource(
  `https://api.whiterabbit.app/v1/sdk/workflows/executions/${runId}/stream`,
);

source.onmessage = (event) => {
  if (!event.data || event.data === ':ping') return;
  const update = JSON.parse(event.data);

  switch (update.status) {
    case 'EXECUTING':
      console.log(`${update.output.pendingStageCount} stages pending`);
      break;
    case 'COMPLETED':
      console.log(`Done — ${update.output.totalUsage} credits used`);
      source.close();
      break;
    case 'FAILED':
      console.error(`Failed — ${update.output.failedStageCount} stage failures`);
      source.close();
      break;
  }
};

info

The native EventSource API doesn't support custom headers. For Node.js, use fetch with a ReadableStream reader and the X-Api-Key header. For browsers, proxy the stream through your backend.

Event shape

interface RunStreamEvent {
  id: string;
  status: 'CREATED' | 'EXECUTING' | 'COMPLETED' | 'FAILED' | 'CANCELED';
  output: {
    totalUsage?: number;
    pendingStageCount?: number;
    failedStageCount?: number;
    cancelRequestedAt?: string | null;
    cancelReason?: string | null;
    nonTerminalStages?: Array<{
      id: string;
      module: string;
      status: 'CREATED' | 'RUNNING';
      executionEventId: string | null;
      executionAttempt: number;
    }>;
  };
  timestamp: string;
}

---

Update workflow component

POST /v1/sdk/workflows/:workflowId/components/:componentId

Update a component's config, name, or canvas position programmatically.

curl -X POST \
  https://api.whiterabbit.app/v1/sdk/workflows/<workflowId>/components/comp-uuid \
  -H "X-Api-Key: ws_..." \
  -H "X-Sdk-Timestamp: <timestamp>" \
  -H "X-Sdk-Signature: <signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "config": { "url": "https://new-endpoint.com" },
    "name": "Updated API Call"
  }'

Request body

{
  config?: object;         // New component config
  name?: string;           // New display name
  position?: [number, number]; // Canvas position [x, y]
}

---

Connection behavior

Scenario	Behavior
Run already COMPLETED when you connect	First event emitted immediately, stream closes
Run already FAILED	First event emitted with error, stream closes
Idle proxy/load balancer timeout	:ping heartbeat every 15s prevents disconnects
Unexpected disconnect	Re-subscribing emits current state immediately