Skip to main content
A flow is the lifecycle of one user request: the message that starts it, every agent call it fans out into, and how it ends. A flow’s 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 from POST /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:
Handler errors return a plain-text body (or an empty body for 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

Returns 201 Created with the new flow:

Behavior

  • Not idempotent. A second call with the same flow_id returns 409.
  • You can’t claim another user’s request: a session_id that belongs to another user’s chat or flows, or a flow_id that already has another user’s usage or tool calls recorded, returns 403.

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

Returns 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.

Errors