flow_id is the request’s W3C trace ID — the same ID in the traceparent header and in the session trace. It’s also the scope of the flow limits: call depth, fan-out, token budget, and wall-clock timeout all count against one flow_id.
Nasiko records a flow automatically when you chat with an agent, use the orchestrator, or run a workflow. The dashboard’s Flows screen (Flows) and the agent activity in Chat read these routes. The POST routes let an agent or integration record its own flow and steps.
Not in the generated OpenAPI spec.
Authentication
Every route takes the session JWT fromPOST /api/auth/login as Authorization: Bearer <token>, or the dashboard session cookie. Any authenticated user can call them; there is no role requirement and no rate limit.
A flow you can’t see returns
404, the same as one that doesn’t exist.
A missing or invalid credential returns 401 before the handler runs:
404).
The flow object
For token and cost reporting by agent, model, and team, use TokenOps.
The step object
A step is one agent call inside the flow.List flows
GET /api/flows
Returns your flows, newest first. Use it to build a flow list, or to find flows paused on a human with status=paused — the dashboard’s overview does exactly that.
Auth: session JWT or dashboard cookie. Returns only the caller’s flows.
Query parameters
Example
Pagination
total is the number of flows on this page, not the total across all pages. Page with limit and offset; a page with fewer than limit rows is the last one.
Errors
Record a flow
POST /api/flows
Creates a flow owned by you, in status running. Use it when your own agent or integration starts a request and you want it in the Flows screen. Chat, the orchestrator, and workflows record their flows for you — don’t call this for those.
Recording a flow doesn’t change the flow limits. They apply to every agent-to-agent call with that trace ID either way.
Auth: session JWT or dashboard cookie. Any authenticated user.
Request body
Example
201 Created with the new flow:
Behavior
- Not idempotent. A second call with the same
flow_idreturns409. - You can’t claim another user’s request: a
session_idthat belongs to another user’s chat or flows, or aflow_idthat already has another user’s usage or tool calls recorded, returns403.
Errors
Get a flow
GET /api/flows/{flow_id}
Returns one flow and all its steps in order. This backs the flow detail page and the “agents used” list under a routed reply in Chat. Use it after a request finishes to see which agents ran, in what order, and where it failed.
Auth: session JWT or dashboard cookie. Owner or superuser.
Path parameters
Example
Errors
List a flow’s steps
GET /api/flows/{flow_id}/steps
Returns just the steps of one flow, ordered by step_order, as a bare JSON array. Use it when you already have the flow and only need its timeline.
Auth: session JWT or dashboard cookie. Owner or superuser.
Path parameters
Example
Errors
Record a step
POST /api/flows/{flow_id}/steps
Appends a step to a flow you recorded, in status running. Nasiko assigns the next step_order. Use it from your own agent or integration each time it calls another agent, so the call shows on the flow’s timeline.
Auth: session JWT or dashboard cookie. Owner or superuser.
Path parameters
Request body
Example
201 Created with the new step:
Behavior
- Not idempotent. Each call appends a new step.
- A recorded step is for display. The flow guard counts depth and fan-out from the actual agent calls Nasiko makes, not from steps you record.