API
Use this page to inspect the WebSocket methods, events, and errors exposed by the engine.
The engine is driven through one API. The afe command line and, later, the web UI are its
clients.
The protocol
The API is JSON-RPC 2.0 over a WebSocket at /rpc. The
handshake must carry Authorization: Bearer <token>, or a valid session cookie from the server's
own Origin.
| Method | Params | Result |
|---|---|---|
flow.list | — | flows with their input Schema, the workspace they need, their projects and the current revision |
flow.bpmn | flow, revision? | {xml}: the flow as BPMN 2.0 XML, with no layout |
ticket.start | flow, input, project?, revision?, traceparent? | {ticket_id} as soon as it is accepted |
ticket.rerun | ticket_id | {ticket_id} of a new ticket on the same flow, input, project and revision |
revision.get | revision_id | {id, manifests}: the frozen configuration |
ticket.resume | ticket_id, answer? (action, comment?) | {ticket_id} |
ticket.pause, ticket.cancel | ticket_id | null |
ticket.get | ticket_id | state, round, revision, artifacts, totals, pending question, last error |
ticket.list | state? | tickets with their totals, and the pending question of the waiting ones |
ticket.events | ticket_id | the ticket's events, in order |
events.subscribe | ticket_id? | {subscription}, then events.event notifications |
events.unsubscribe | subscription | true or false |
workers.status | — | queue metrics (waiting, claimed) and the live workers |
Tickets run in the background. Their progress arrives as events.event notifications on the same
connection. A late subscriber first gets the ticket's past events, then the live ones, with no
duplicates.
Event kinds
| Kind | Meaning |
|---|---|
ticket_started | The ticket was accepted and the engine started it. |
ticket_resumed | A person answered, or the ticket was restarted. |
ticket_recovered | A worker took over a ticket whose worker died. |
ticket_cancelled | The ticket was cancelled. |
ticket_done | The flow reached END. |
node_started | A node began an activation. |
node_finished | A node finished an activation. |
budget_alert | A budget crossed an alert fraction or a limit; waits for a person. |
loop_detected | The same tool call repeated; waits for a person. |
human_request | A human node asks a person. |
human_response | A person answered a human node. |
needs_human | A hand-over; the ticket stops for a person. |
error | The ticket failed; the payload carries state and error. |
Errors
| Error code | Meaning |
|---|---|
-32602 | Invalid params |
-32001 | Unknown flow or ticket |
-32002 | Invalid input; data.fields names the field that is wrong |
-32003 | Action not offered |
-32004 | The ticket is running, or closed |
-32005 | Unknown revision |
-32006 | The ticket has no revision (created before revisions existed) |
See also
- CLI for commands that call the API.
- Ticket states for ticket lifecycle values.
- Operations for health and metrics endpoints.