API Reference

Base URL: https://api.whiterabbit.app
API version: v1

All request bodies are JSON. All responses are JSON. Dates are ISO 8601 strings.

---

Authentication headers

Header	Scope
X-Api-Key: ws_...	All SDK endpoints (component execution, workflow triggers, run inspection)
Authorization: Bearer <jwt>	Dashboard/UI authenticated endpoints

---

TypeScript SDK types

All types are exported from caller-sdk:

import type {
  // WorkspaceClient — component execution
  ClientOptions,
  ExecuteOptions,
  PromiseOptions,
  ExecuteComponentResponse,
  ExecutionStreamEvent,
  ExecutionStreamHandlers,
  ExecutionStreamSubscription,
  // WorkflowClient
  TriggerRunResponse,
  WorkflowRunDetail,
  WorkflowRunStatus,
  RunStage,
  StageStatus,
  RunStreamEvent,
  RunStreamHandlers,
  RunStreamSubscription,
  UpdateComponentRequest,
} from 'caller-sdk';

---

WorkspaceClient

ClientOptions

interface ClientOptions {
  /** Workspace API key (ws_...) */
  apiKey: string;
  /** Override API base URL. Defaults to https://api.whiterabbit.app */
  baseUrl?: string;
}

WorkflowClientOptions

Options for WorkflowClient constructor.

interface WorkflowClientOptions {
  /** Workspace API key (ws_...) */
  apiKey: string;
  /** UUID of the workflow to trigger. */
  workflowId: string;
  /** Override API base URL. Defaults to https://api.whiterabbit.app */
  baseUrl?: string;
}

ExecuteOptions

Options for .execute() — fire and return the execution record.

interface ExecuteOptions {
  /** Execution attempts on failure, 1–3. @default 1 */
  attempts?: number;
  /** Wait up to N ms for inline result. Max 15000. */
  waitForMs?: number;
  /** HTTPS URL to receive completion webhook. */
  callbackUrl?: string;
  /** HMAC-SHA256 key for webhook signature. */
  callbackSecret?: string;
  /** Custom HTTP headers added to the webhook request. */
  callbackHeaders?: Record<string, string>;
}

PromiseOptions

Options for .promise() — wait for result via SSE stream.

interface PromiseOptions {
  /** Execution attempts on failure, 1–3. @default 1 */
  attempts?: number;
  /**
   * Max wait time in ms. Rejects with CallerSDKError("Execution timed out")
   * if the execution doesn't complete in time.
   * @default 60_000
   */
  timeoutMs?: number;
}

ExecuteComponentResponse

Returned by .execute() and workspace.execution.get().

interface ExecuteComponentResponse {
  id: string;
  module: string;
  status: 'CREATED' | 'EXECUTING' | 'COMPLETED' | 'FAILED';
  completed: boolean;
  output: unknown | null;
  error: unknown | null;
  totalUsage: number;
  callback: {
    url: string | null;
    signed: boolean;
    signatureAlgorithm: 'hmac-sha256-v1' | null;
    headerNames: string[];
    lastAttemptAt: string | null;
    deliveredAt: string | null;
    attemptCount: number;
    lastError: unknown | null;
  };
  createdAt: string;
  updatedAt: string;
}

ExecutionStreamEvent

Events emitted by workspace.execution.stream().

interface ExecutionStreamEvent {
  id: string;
  status: 'CREATED' | 'EXECUTING' | 'COMPLETED' | 'FAILED';
  output: unknown | null;  // populated on COMPLETED
  error: unknown | null;   // populated on FAILED
  timestamp: string;
}

ExecutionStreamHandlers

interface ExecutionStreamHandlers {
  /** Called for every status event pushed by the stream. */
  onUpdate(event: ExecutionStreamEvent): void;
  /** Called when the stream closes due to a network error. */
  onError?(err: Error): void;
}

ExecutionStreamSubscription

interface ExecutionStreamSubscription {
  /** Unsubscribe and tear down the SSE connection. */
  close(): void;
}

workspace.execution namespace

interface ExecutionNamespace {
  /** Fetch current state of an execution by ID. */
  get(executionId: string): Promise<ExecuteComponentResponse>;

  /** Subscribe to live status events for an execution via SSE. */
  stream(
    executionId: string,
    handlers: ExecutionStreamHandlers,
  ): ExecutionStreamSubscription;
}

workspace.webhook namespace

interface WebhookNamespace {
  /** Re-deliver the completion webhook for an execution. Idempotent. */
  redeliver(executionId: string): Promise<void>;
}

---

WorkflowClient

TriggerRunResponse

Returned by workflow.trigger().

interface TriggerRunResponse {
  /** UUID identifying the new run. */
  runId: string;
  /** Underlying BullMQ job ID. */
  jobId: string;
}

WorkflowRunStatus

type WorkflowRunStatus =
  | 'CREATED'
  | 'EXECUTING'
  | 'COMPLETED'
  | 'FAILED'
  | 'CANCELED';

StageStatus

type StageStatus =
  | 'CREATED'
  | 'RUNNING'
  | 'COMPLETED'
  | 'FAILED'
  | 'CANCELED';

RunStage

A single component stage within a workflow run.

interface RunStage {
  id: string;
  module: string;
  status: StageStatus;
  output: unknown | null;
  error: unknown | null;
  creditUsage: number;
  executionEventId: string | null;
  executionDispatchedAt: string | null;
  /** 1-based retry counter. 1 = first attempt. */
  executionAttempt: number;
  updatedAt: string;
}

WorkflowRunDetail

Returned by workflow.execution.get() and workflow.waitForRun().

interface WorkflowRunDetail {
  id: string;
  status: WorkflowRunStatus;
  pendingStageCount: number;
  failedStageCount: number;
  cancelRequestedAt: string | null;
  cancelReason: string | null;
  totalUsage: number;
  createdAt: string;
  updatedAt: string;
  runStages: RunStage[];
}

RunStreamEvent

Events emitted by workflow.stream().

interface RunStreamEvent {
  id: string;
  status: WorkflowRunStatus;
  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;
}

RunStreamHandlers

interface RunStreamHandlers {
  /** Called for every status event emitted by the stream. */
  onUpdate(event: RunStreamEvent): void;
  /** Called when the stream closes due to a connection error. */
  onError?(err: Error): void;
}

RunStreamSubscription

interface RunStreamSubscription {
  /** Unsubscribe and release the SSE connection. */
  close(): void;
}

UpdateComponentRequest

Payload for workflow.component.update().

interface UpdateComponentRequest {
  /** New component config (merged with existing values on the server). */
  config?: Record<string, unknown>;
  /** New display name for the component on the canvas. */
  name?: string;
  /** Canvas position [x, y]. */
  position?: [number, number];
}

---

SDK — Components

Execute component

POST /v1/sdk/components

Auth: X-Api-Key · Rate: 2×

Execute any component standalone. Without waitForMs, returns immediately with status: "CREATED". Set waitForMs (max 15000 ms) for an inline result, or use callbackUrl for async webhook delivery.

Request

{
  "module": "RANDOM_UUID",
  "input": {},
  "config": {},
  "attempts": 1,
  "waitForMs": 5000,
  "callbackUrl": "https://your.app/webhook",
  "callbackSecret": "hmac-secret",
  "callbackHeaders": { "X-Source": "whiterabbit" }
}

Response 200 — default (no waitForMs): returns CREATED immediately

{
  "id": "3f7a1b2c-...",
  "module": "RANDOM_UUID",
  "status": "CREATED",
  "completed": false,
  "output": null,
  "totalUsage": 0,
  "callback": {
    "url": null, "signed": false, "signatureAlgorithm": null,
    "headerNames": [], "attemptCount": 0
  },
  "createdAt": "2026-04-20T10:00:00Z",
  "updatedAt": "2026-04-20T10:00:00Z"
}

Response 200 — with waitForMs: may return COMPLETED if the component finishes in time

{
  "id": "3f7a1b2c-...",
  "module": "RANDOM_UUID",
  "status": "COMPLETED",
  "completed": true,
  "output": { "uuid": "a4c2e8f1-..." },
  "totalUsage": 1,
  "callback": {
    "url": null, "signed": false, "signatureAlgorithm": null,
    "headerNames": [], "attemptCount": 0
  },
  "createdAt": "2026-04-20T10:00:00Z",
  "updatedAt": "2026-04-20T10:00:01Z"
}

---

Get execution status

GET /v1/sdk/components/executions/:executionId

Auth: X-Api-Key

Response 200 — same shape as Execute Component response above.

---

Stream execution status

SSE /v1/sdk/components/executions/:executionId/stream

Auth: X-Api-Key

Emits ExecutionStreamEvent objects until the execution reaches COMPLETED or FAILED, then closes.

interface ExecutionStreamEvent {
  id: string;
  status: 'CREATED' | 'EXECUTING' | 'COMPLETED' | 'FAILED';
  output?: unknown;
  error?: unknown;
  timestamp: string;
}

---

Replay callback

POST /v1/sdk/components/executions/:executionId/replay-callback

Auth: X-Api-Key

Re-delivers the completion webhook. Idempotent.

Response 200 — same as execution response.

---

SDK — Workflows

Trigger workflow run

POST /v1/sdk/workflows/:workflowId

Auth: X-Api-Key

Response 200

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

---

Get workflow run

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

Auth: X-Api-Key

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 run

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

Auth: X-Api-Key

Emits run status events including pendingStageCount and currently active stages. Closes on COMPLETED, FAILED, or CANCELED.

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

Auth: X-Api-Key

Request

{
  "config": { "url": "https://new-endpoint.com" },
  "name": "Updated Component",
  "position": [120, 340]
}

---

Error responses

All errors follow:

{
  "message": "Human-readable description",
  "statusCode": 400,
  "error": "Bad Request"
}

Status	Meaning
400	Validation error
401	Missing or invalid API key
402	Insufficient credits
403	Missing workspace permission
404	Resource not found
409	Conflict (e.g. duplicate name)
429	Rate limit exceeded
502	Upstream microservice unavailable