Usage

Driving a workflow

POST /workflow/start      begin an instance
GET  /workflow/status     where an instance has reached
POST /workflow/signal     deliver a signal — an approval, a decision
POST /workflow/event      deliver an external event
POST /workflow/resume     resume a suspended instance
POST /workflow/cancel     stop an instance
GET  /workflow/logs       execution history for an instance
GET  /workflow/config     the definitions loaded for this tenant
GET  /workflow/queue      queued work

Signals versus events

The distinction trips people up, and getting it wrong produces workflows that hang.

A signal is addressed to one instance. It usually carries a human decision — an approval, a rejection, a chosen option. You send it because you know which instance you are answering.

An event is broadcast. Instances waiting on that event wake up. You send it because something changed in the world and you do not know, or care, which instances are interested.

Reach for a signal when you have an instance id. Reach for an event when you have a fact.

Suspension

A workflow that reaches a wait step suspends. It holds no connection, consumes no worker, and survives restarts of every service involved. When the signal or event it is waiting for arrives, it resumes from that step with its accumulated state intact.

This is the property that makes approval processes tractable. A month-long expense approval is a suspended instance, not a process holding resources for a month.

Logs and status

GET /workflow/status    where an instance has reached
GET /workflow/logs      the full execution history

status answers “where is it”; logs answers “how did it get there”. Reach for logs when an instance took a branch you did not expect — the history records which conditions evaluated which way.

Admin surface

GET /admin/agents        connected workers
GET /admin/agents/:id    one worker
GET /admin/instances     running instances
GET /admin/queue         the work queue
GET /admin/queue/:id     one queued item

/admin/instances is the first place to look when a process appears stuck. An instance sitting in a wait state is usually correct — it is waiting for a signal nobody sent — and telling that apart from a genuinely wedged instance is exactly what the endpoint is for.

Operations — definitions, capacity and what to watch