Runs and webhooks

Synchronous runs

POST /api/runs loads a root-relative flow and holds the connection until success, failure, or suspension. This endpoint is useful for development and bounded work. The response is the core workflow result rather than a durable run record.

Asynchronous runs

POST /api/runs/async accepts the same workflowId and input, plus optional debug and callbackUrl. It returns 202, a Location header, and a run ID. Poll GET /api/runs/:id: active states return 202; terminal states return 200.

Async statuses are queued, running, paused, suspended, cancelled, success, and failure. Debug runs execute one node at a time and pause for POST /api/runs/:id/continue. Cancel with POST /api/runs/:id/cancel.

See Debug runs for request examples and pause/resume behavior.

Manifest webhooks

GET /api/webhooks lists discovered workflows that declare a webhook. Each gets /api/webhooks/<id> and, when enabled, /api/webhooks/<id>/async. JSON requests reserve debug and callbackUrl as execution controls. Single-file and mixed multipart requests validate configured field, count, byte, total-size, and MIME rules, then pass base64 file data to the workflow. Mixed multipart requests may combine typed text fields with repeated file fields.

Both synchronous and asynchronous webhook execution calls require an application API key:

Authorization: Bearer <application-api-key>

Set this bearer token through APPLICATION_API_KEY in the server environment.

Manifest response mappings turn configuration, dependency, workflow, and fallback failures into stable public HTTP status/code/message triples. Preserve x-request-id when reporting a failure.

Completion callbacks

Callbacks must be HTTPS, match ASYNC_CALLBACK_ALLOWED_HOSTS, and resolve to public addresses. Terminal bodies are HMAC-SHA256 signed in X-Faimulus-Signature using ASYNC_CALLBACK_SECRET. Delivery retries five times; polling responses expose delivery state and the last error.

Queued work survives restarts and interrupted running work is requeued. Design workflow side effects for at-least-once execution.