nasiko maf (workflow CLI reference). For the concepts, see Workflows.
Authentication
Every route needs a signed-in user: send the session JWT fromPOST /api/auth/login as Authorization: Bearer <token>, or call from the dashboard with its session cookie. Cookie-authenticated writes from another origin are refused with 403.
Workflows are scoped to people, not roles:
- You can read, edit, promote, run, and delete the workflows you created.
- Public workflows (
is_public: true, such as the sample workflows a server ships with) can be read and run by every user. Only their owner can edit or delete them. - A superuser can delete any workflow.
- Executions belong to the user who started them. You only ever see and stop your own runs, including your runs of a public workflow.
Plans: Pro and Enterprise. Self-hosted: Included in the open-source server.
402 with code plan_feature_not_included, in an { "error", "code", ... } body rather than the envelope below. Running one of the sample workflows the server ships with is allowed on every plan. Reads and stopping executions stay open.
Role tiers don’t gate these routes. Any signed-in user can create and run workflows. What a workflow can reach is limited by agent access: every agent a step names must be one you can access, checked when you save the workflow and again on every run.
Response envelope
Every response from these routes, success or error, uses the same envelope:status_code mirrors the HTTP status. On errors, data is null and message explains what went wrong. One error also carries a machine-readable code (see Generate a workflow plan).
Two kinds of error don’t use the envelope:
- Rate limits return
429with the plain-text bodyrate limit exceeded, try again shortlyand aRetry-Afterheader in seconds. - Malformed JSON sent to a route that takes a JSON body (create, update, save draft, generate) is rejected before it reaches the handler, with a plain-text
400,415, or422. Run and Stop executions parse their own bodies and answer malformed JSON with an enveloped400.
Rate limits
Limits are per user, over a 60-second window.
The standard tier is loose enough for the dashboard to poll an execution and its usage every couple of seconds while it runs.
Endpoints
Objects
Workflow
Returned by get, create, update, promote, and save draft.
Each entry in
maf_json.steps:
Workflow list item
Returned by both list routes. Includes every Workflow field, plus:Execution
Returned by get execution, poll result, and both execution lists.
The cross-workflow list (
GET /api/maf/executions) adds workflow_name and workflow_status (active, draft, deleted, or null if the workflow no longer exists), so runs of deleted workflows still show up there.
Each entry in step_results:
Execution status
success, failed, and stopped are terminal.
Generate a workflow plan
POST /api/maf/generate
Turns a plain-language description into a proposed workflow: a name, a description, guidance for the final answer, and steps with agents assigned. Nothing is saved. Review the plan, then send its steps to Create a workflow. The dashboard’s Generate a draft and nasiko maf trace use this route.
Auth: session JWT or dashboard cookie. Any signed-in user. Rate limit: 10 per minute.
The planner only chooses among agents you own. It uses the model API key saved in your settings if you have one, otherwise the server’s configured model. The planning call’s tokens show up in TokenOps.
Request body
Example
Errors
List workflows
GET /api/maf/workflows
Lists active workflows you can run: your own plus public ones. Drafts aren’t included; use List drafts. This backs the Workflows screen and nasiko maf workflow list.
Auth: session JWT or dashboard cookie. Any signed-in user.
Query parameters
data.total is the number of items in this page, not the total across pages. To page through, raise offset by limit until a page comes back shorter than limit.
Example
Errors
Create a workflow
POST /api/maf/workflows
Creates an active workflow from steps you supply. Use it when you already know the steps, for example after reviewing a generated plan. Matches nasiko maf workflow create.
Auth: session JWT or dashboard cookie. Any signed-in user.
Each step either names an agent or leaves it to Nasiko:
- With
agent_id: you must be able to access that agent, or the request is refused with403 agent <id> not found. The same response is used whether the agent doesn’t exist or you can’t access it. - Without
agent_id: the routing engine picks a running agent you can access. If it can’t decide, Nasiko falls back to the deployed agent you own whose name and description best match the task. Agents are resolved once, when you save; they aren’t re-picked on each run.
Request body
Example
Errors
On Nasiko Cloud and on a self-hosted Enterprise server, a workflow policy applies on save and on run. A refusal returns
400 with the policy’s reason. If the policy can’t be checked, the response is 503 with the workflow couldn't be checked right now; try again.Save a draft
POST /api/maf/workflow/draft
Saves an instruction you’re still writing as a draft — for example, on every pause while typing. It makes no model call and assigns no agents, so it’s cheap to call often. The draft has no steps until you add them with Update a workflow. Drafts don’t appear in List workflows.
Auth: session JWT or dashboard cookie. Any signed-in user. You can only overwrite your own drafts.
Send draft_id on every save after the first so you keep updating the same draft instead of creating a new one each time.
Request body
Example
Errors
List drafts
GET /api/maf/workflow/drafts
Lists your drafts. A draft you’ve promoted stays in this list with status: "active", so you can follow it from idea to runs and spend. Discarded drafts are excluded. Only your own drafts are listed. Matches nasiko maf workflow drafts.
Auth: session JWT or dashboard cookie. Any signed-in user.
Query parameters
The response has the same shape as List workflows, with
message: "Drafts retrieved successfully". data.total counts this page only.
Example
Errors
Get a workflow
GET /api/maf/workflow/{id}
Returns one workflow or draft. Use it to load a workflow’s steps before editing or running it. Matches nasiko maf workflow get.
Auth: session JWT or dashboard cookie. You must own the workflow, or it must be public.
Path parameters
Example
message: "Workflow retrieved successfully" (same shape as the create example, status 200).
Errors
Update a workflow
PUT /api/maf/workflow/{id}
Edits a workflow’s name, description, or steps. Works on drafts too — this is how you give a saved draft its steps before promoting it. Matches nasiko maf workflow update.
Auth: session JWT or dashboard cookie. Owner only.
Every field is optional; send only what you’re changing.
stepsreplaces the whole step list. Steps are resolved to agents exactly as in Create a workflow, and every step gets a newstep_id. The array order is the run order.description: nullclears the description. Leavingdescriptionout keeps it.
Path parameters
Request body
Example
200, message: "Workflow updated successfully".
Errors
Delete a workflow
DELETE /api/maf/workflow/{id}
Deletes a workflow, or discards a draft. The workflow disappears from lists and returns 404 from then on. Its past executions stay visible in List all executions with workflow_status: "deleted". Runs already queued aren’t stopped; use Stop executions first if you need that. Matches nasiko maf workflow delete.
Auth: session JWT or dashboard cookie. Owner or superuser.
Path parameters
Example
Errors
Promote a draft
POST /api/maf/workflow/{id}/promote
Marks a draft as ready: its status changes from draft to active and it moves into List workflows. Nothing else changes — the steps and agents you reviewed are exactly what runs, and the ID stays the same. Matches nasiko maf workflow promote.
Auth: session JWT or dashboard cookie. Owner only. No request body.
A draft must have steps before you can promote it. Add them with Update a workflow.
Retrying a promotion that already succeeded returns 400 (the workflow is no longer a draft) and changes nothing.
Path parameters
Example
status: "active", status 200, message: "Draft promoted successfully".
Errors
Run a workflow
POST /api/maf/workflow/{id}/run
Queues an execution and returns 202 Accepted immediately. A background worker runs the steps; poll Poll an execution result for progress. Matches nasiko maf workflow run (add --wait to poll from the CLI).
Auth: session JWT or dashboard cookie. You must own the workflow, or it must be public. A run of a public workflow is yours: you see it, you’re billed for it, and access is checked against your agent access. Rate limit: 10 per minute.
Before queuing, Nasiko re-checks that you can still access every agent the workflow uses. Revoked access fails here with 403, not later in the background. Drafts with steps can be run without promoting them first.
Each call creates a new execution; runs aren’t deduplicated.
Path parameters
Request body
The body is optional. An empty body runs the workflow as saved.Example
execution_count is your updated run count for this workflow.
How a run proceeds
- The execution starts as
pending, thenrunningwhen a worker claims it. - Steps run strictly in order. Each step’s agent call runs as its own flow, so flow token limits, depth, fan-out, and timeout limits apply per step. A step blocked by a limit fails with
step <n> (agent '<name>') blocked by flow limits: …. - If a step needs a human, the run moves to
awaiting_humanand the request appears inhitl. Resolve it through the Approvals API and the run resumes from that step. - On success,
outputholds the final answer. - If an attempt fails, the run goes back to
pendingand is attempted again from the start, up tomax_attempts(the server’sMAF_MAX_ATTEMPTS, default3). A run that timed out, or that failed after resuming from a human answer, isn’t retried.
Errors
On Nasiko Cloud and on a self-hosted Enterprise server, a workflow policy can refuse a run (
400 with its reason, or 503 if it can’t be checked).List executions of a workflow
GET /api/maf/workflow/{id}/executions
Lists your runs of one workflow, newest first. On a public workflow you only see your own runs. Matches nasiko maf workflow executions.
Auth: session JWT or dashboard cookie. You must own the workflow, or it must be public.
Path parameters
Query parameters
data.total counts this page only.
Example
Errors
Poll an execution result
GET /api/maf/workflow/result/{exec_id}
Returns an execution’s current status, step progress, approval requests, and — once it finishes — its output. This is the route to poll after Run a workflow. The CLI’s --wait polls it every 2 seconds until the status is terminal. Matches nasiko maf execution result.
Auth: session JWT or dashboard cookie. You must have started the execution.
Path parameters
Example
hitl entries above are abbreviated. See the Approvals API for the full shape and how to resolve one.
Stop polling when status is success, failed, or stopped. Agent token and cost figures arrive separately; see Get execution usage.
Errors
List all executions
GET /api/maf/executions
Lists every execution you’ve started, across all workflows, newest first. Runs of deleted workflows are included, with workflow_status: "deleted". This backs the Executions screen and nasiko maf execution list.
Auth: session JWT or dashboard cookie. Any signed-in user; returns only your runs.
Query parameters
data.total counts this page only.
Example
Errors
Get an execution
GET /api/maf/execution/{id}
Returns one execution. The response is identical to Poll an execution result except for message: "Execution retrieved successfully"; the dashboard polls this route while a run is open. Matches nasiko maf execution get.
Auth: session JWT or dashboard cookie. You must have started the execution.
Path parameters
Example
Errors
Get execution usage
GET /api/maf/execution/{id}/usage
Returns per-step agent token counts and cost for one execution, alongside the workflow’s own orchestration tokens. The dashboard and nasiko maf trace call it to fill in cost.
Auth: session JWT or dashboard cookie. You must have started the execution.
Agent usage is collected from traces after each step runs, so it arrives after the execution itself, usually within a few seconds. Poll this route until complete is true:
- A step with
resolved: falsehasn’t reported yet. Its zeros mean “not known yet”, not “free”. Don’t present a sum over unresolved steps as a total. completeturnstruewhen every step that called its agent has reported, or once the run has been finished long enough that anything still missing won’t arrive (for example, an agent that made no model calls).usage_available: falsemeans this server isn’t collecting agent trace usage (no trace backend configured, such asTEMPO_URLunset). Agent figures will never arrive, andcompleteistrueimmediately.
Path parameters
Response fields
Example
Errors
Stop an execution
POST /api/maf/execution/{id}/stop
Stops one of your executions that’s still pending, running, or awaiting_human. It becomes stopped immediately:
- A
pendingrun never starts. - A
runningrun is cut short now, or at the latest when its current step finishes. Steps already completed aren’t undone, and tokens already spent are still recorded. - An
awaiting_humanrun’s open approval requests are canceled, so a late answer has nothing to resume.
Path parameters
Example
previous_status is what the run was doing when you stopped it.
Errors
Stop executions
POST /api/maf/executions/stop
Stops several executions at once, or every unfinished run of one workflow. Each run is stopped as described in Stop an execution. The response reports what happened to each ID instead of failing the whole request. Matches nasiko maf execution stop.
Auth: session JWT or dashboard cookie. Only executions you started. Stopping by workflow_id on a public workflow stops only your runs of it.
Request body
Send exactly one ofexecution_ids or workflow_id.
Example
The request is safe to repeat: a second call reports the same runs under
already_finished.
Errors
Related
Workflows
How workflows chain agents and where each step’s output goes.
Workflow commands
The same operations from
nasiko maf.Approvals API
Resolve a run that’s
awaiting_human.Flow limits
Token, depth, and time limits applied to each step.