Skip to main content
A workflow is a saved, ordered list of steps. Each step is a task description bound to one deployed agent. When you run a workflow, Nasiko runs the steps in order in the background, feeds what each step produced into the next, and synthesizes one final answer. Each run is an execution. These are the routes behind the Workflows and Executions screens under Orchestrator in the dashboard (Workflows dashboard) and behind nasiko maf (workflow CLI reference). For the concepts, see Workflows.

Authentication

Every route needs a signed-in user: send the session JWT from POST /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.
On Free and Individual, the write and run routes return 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 429 with the plain-text body rate limit exceeded, try again shortly and a Retry-After header 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, or 422. Run and Stop executions parse their own bodies and answer malformed JSON with an enveloped 400.

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 with 403 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

The response is a Workflow in the envelope, with 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.
  • steps replaces the whole step list. Steps are resolved to agents exactly as in Create a workflow, and every step gets a new step_id. The array order is the run order.
  • description: null clears the description. Leaving description out keeps it.
Executions that are already queued or running keep the definition they started with.

Path parameters

Request body

Example

The response is the updated Workflow, status 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

The response is the promoted Workflow with 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

  1. The execution starts as pending, then running when a worker claims it.
  2. 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: ….
  3. If a step needs a human, the run moves to awaiting_human and the request appears in hitl. Resolve it through the Approvals API and the run resumes from that step.
  4. On success, output holds the final answer.
  5. If an attempt fails, the run goes back to pending and is attempted again from the start, up to max_attempts (the server’s MAF_MAX_ATTEMPTS, default 3). 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

The 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: false hasn’t reported yet. Its zeros mean “not known yet”, not “free”. Don’t present a sum over unresolved steps as a total.
  • complete turns true when 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: false means this server isn’t collecting agent trace usage (no trace backend configured, such as TEMPO_URL unset). Agent figures will never arrive, and complete is true immediately.

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 pending run never starts.
  • A running run 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_human run’s open approval requests are canceled, so a late answer has nothing to resume.
Auth: session JWT or dashboard cookie. Only executions you started. No request body.

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 of execution_ids or workflow_id.

Example

The request is safe to repeat: a second call reports the same runs under already_finished.

Errors

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.