> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nasiko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows API

> Create, draft, run, monitor, and stop pre-defined multi-agent workflows.

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](https://docs.nasiko.com/dashboard/workflows.md)) and behind `nasiko maf` ([workflow CLI reference](https://docs.nasiko.com/reference/cli/workflows.md)). For the concepts, see [Workflows](https://docs.nasiko.com/build/workflows.md).

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

> [!NOTE]
>
> **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.

> [!NOTE]
>
> 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](https://docs.nasiko.com/governance/access-control/agent-access.md): 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:

```json theme={null}
{
  "data": { },
  "status_code": 200,
  "message": "Workflow retrieved successfully"
}
```

`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](#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.

| Tier | Limit | Routes |
| - | - | - |
| Expensive (model calls and runs) | 10 requests per minute | `POST /api/maf/generate`, `POST /api/maf/workflow/{id}/run` |
| Standard (reads, edits, stops) | 120 requests per minute | Every other route on this page |

The standard tier is loose enough for the dashboard to poll an execution and its usage every couple of seconds while it runs.

## Endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/api/maf/generate` | Draft a workflow plan from a plain-language description (nothing is saved) |
| `GET` | `/api/maf/workflows` | List active workflows you can run |
| `POST` | `/api/maf/workflows` | Create an active workflow from steps |
| `POST` | `/api/maf/workflow/draft` | Save or autosave a draft instruction |
| `GET` | `/api/maf/workflow/drafts` | List your drafts |
| `GET` | `/api/maf/workflow/{id}` | Get one workflow |
| `PUT` | `/api/maf/workflow/{id}` | Edit a workflow or draft |
| `DELETE` | `/api/maf/workflow/{id}` | Delete a workflow or discard a draft |
| `POST` | `/api/maf/workflow/{id}/promote` | Promote a draft to an active workflow |
| `POST` | `/api/maf/workflow/{id}/run` | Start an execution (`202`) |
| `GET` | `/api/maf/workflow/{id}/executions` | List your executions of one workflow |
| `GET` | `/api/maf/workflow/result/{exec_id}` | Poll an execution for status and output |
| `GET` | `/api/maf/executions` | List all your executions across workflows |
| `GET` | `/api/maf/execution/{id}` | Get one execution |
| `GET` | `/api/maf/execution/{id}/usage` | Per-step agent tokens and cost for an execution |
| `POST` | `/api/maf/execution/{id}/stop` | Stop one execution |
| `POST` | `/api/maf/executions/stop` | Stop several executions, or every unfinished run of a workflow |

## Objects

### Workflow

Returned by get, create, update, promote, and save draft.

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Workflow ID |
| `user_id` | UUID | Owner |
| `name` | string | Display name. If you don't give one, it's the first 60 characters of the first step's task (or of the draft instruction) |
| `description` | string \| null | Free-text description. For a draft, the instruction as typed |
| `maf_json` | object | The stored definition: `steps`, plus `description` and `output_generation` (both usually `null`; the planner produces them on each run) |
| `status` | string | `active` or `draft` |
| `created_at` | timestamp | ISO 8601 |
| `updated_at` | timestamp | ISO 8601 |
| `execution_count` | integer | How many times **you** have run it |
| `is_public` | boolean | Every user can run it; only the owner can change it |

Each entry in `maf_json.steps`:

| Field | Type | Description |
| - | - | - |
| `step_id` | UUID | Regenerated each time the step list is replaced |
| `step_index` | integer | Zero-based position. The order of the array is the order of the steps |
| `agent_id` | UUID | The agent that runs this step |
| `agent_name` | string | That agent's name |
| `agent_endpoint` | string | The agent's address at the time the step was saved |
| `task_description` | string | What the step asks the agent to do |

### Workflow list item

Returned by both list routes. Includes every [Workflow](#workflow) field, plus:

| Field | Type | Description |
| - | - | - |
| `success_rate` | number \| null | Percentage of your finished runs that succeeded, to one decimal. Stopped runs don't count. `null` if you've never run it |
| `health` | string | `healthy` (90% or more), `degraded` (50% to under 90%), `unhealthy` (under 50%), or `unknown` (never run) |
| `total_tokens` | integer | All-time workflow orchestration tokens across your runs |
| `last_run_at` | timestamp \| null | When your most recent run started |
| `last_run_status` | string \| null | That run's status |
| `step_count` | integer | Number of steps |
| `agent_names` | string\[] | Distinct agents the steps use, in first-use order |

### Execution

Returned by get execution, poll result, and both execution lists.

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Execution ID. Use this for every lookup |
| `execution_number` | integer | Human-friendly sequential number for display. Not a lookup key |
| `maf_id` | UUID \| null | The workflow this run belongs to |
| `user_id` | UUID | Who started it |
| `status` | string | See [Execution status](#execution-status) |
| `attempt_count` | integer | Attempts made so far |
| `max_attempts` | integer | Attempts allowed before the run is marked `failed` |
| `tokens_used` | integer | Tokens spent by the workflow's own planning, step preparation, and final synthesis. Agent tokens are reported by [the usage route](#get-execution-usage) |
| `started_at` | timestamp \| null | When the current attempt started |
| `completed_at` | timestamp \| null | When the run finished |
| `duration_ms` | integer \| null | Run duration |
| `output` | string \| null | The final synthesized answer |
| `step_results` | array \| null | Per-step progress (below) |
| `error` | string \| null | Why the run (or its last attempt) failed |
| `created_at` | timestamp | When the run was queued |
| `hitl` | array | Every [approval request](https://docs.nasiko.com/api-reference/approvals.md) raised during this run, oldest first, pending or resolved. Same shape as `GET /api/hitl/{id}`. At most one is `pending` at a time |

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`:

| Field | Type | Description |
| - | - | - |
| `step_id`, `step_index`, `agent_id`, `agent_name` | | Which step and agent |
| `status` | string | `pending`, `running`, `success`, or `failed` |
| `error` | string \| null | Why the step failed |
| `prompt_template` | string | The planned prompt, with placeholders for earlier steps' output |
| `to_extract` | string | What the workflow pulls out of the agent's reply for later steps |
| `prompt` | string | The prompt actually sent to the agent |
| `extracted_info` | string \| null | What was extracted from the reply |
| `tokens_used` | integer | Workflow orchestration tokens spent on this step |
| `trace_id` | string \| null | The trace this step's agent call ran under. Open it in [Sessions and traces](https://docs.nasiko.com/dashboard/sessions-and-traces.md) |
| `latency_ms` | integer | Step latency |
| `context` | string \| null | Context passed in from earlier steps |

### Execution status

| Status | Meaning |
| - | - |
| `pending` | Queued, waiting for a worker. Also the state between a failed attempt and its retry |
| `running` | A worker is running the steps |
| `awaiting_human` | A step is paused on an approval or input request. The pending request is in `hitl`; resolve it with the [Approvals API](https://docs.nasiko.com/api-reference/approvals.md) and the run resumes from that step |
| `success` | Finished. `output` holds the answer |
| `failed` | Finished with an error after its last attempt |
| `stopped` | You stopped it |

`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](#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](https://docs.nasiko.com/tokenops/dashboard.md).

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `description` | string | Yes | What the workflow should do. Must not be blank |

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/maf/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Research recent news on solid-state batteries, then summarize it in three bullets" }'
```

```json theme={null}
{
  "data": {
    "name": "Battery news brief",
    "description": "Researches recent solid-state battery news and condenses it into a short summary.",
    "output_generation": "Return three concise bullet points citing the key developments.",
    "steps": [
      {
        "agent_id": "7f0c2f9e-3a51-4d8e-9a2b-1c6f0e4d2b11",
        "agent_name": "research-agent",
        "task_description": "Find recent news on solid-state batteries"
      },
      {
        "agent_id": "c41a8d02-5be7-4f1e-8e33-9b0a7d6c5e20",
        "agent_name": "summarizer",
        "task_description": "Summarize the research into three bullet points"
      }
    ]
  },
  "status_code": 200,
  "message": "Workflow plan generated successfully"
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `400` | `description is required` | `description` is blank |
| `400` | `no agents registered — …` | You don't own any agents for the planner to choose from |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `422` | `planning failed: …` | The model couldn't produce a usable plan |
| `429` | plain text | More than 10 expensive requests in a minute |
| `502` | `code: "llm_key_rejected"`, `AI drafting failed: …` | No model key is available, or the provider refused the key. The message says whose key |
| `500` | message | Server error |

***

## List workflows

`GET /api/maf/workflows`

Lists active workflows you can run: your own plus public ones. Drafts aren't included; use [List drafts](#list-drafts). This backs the **Workflows** screen and `nasiko maf workflow list`.

**Auth:** session JWT or dashboard cookie. Any signed-in user.

### Query parameters

| Name | Type | Default | Description |
| - | - | - | - |
| `limit` | integer | `50` | Page size |
| `offset` | integer | `0` | Rows to skip |
| `search` | string | none | Case-insensitive substring match on name and description. Blank is ignored |
| `sort` | string | `recent` | `recent` (newest first), `success_rate` (highest first), `token_usage` (most first), `execution_count` (most first), or `health` (worst first). Workflows you've never run sort last for metric sorts |

`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

```bash theme={null}
curl "https://<your-host>/api/maf/workflows?sort=health&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": {
    "data": [
      {
        "id": "3b9d6c1e-8f2a-4e57-b0c4-2a7e91d5f803",
        "user_id": "0e4a7b2c-91d3-4f68-a5e0-6c2b8d1f9a47",
        "name": "research-and-summarize",
        "description": null,
        "maf_json": {
          "description": null,
          "output_generation": null,
          "steps": [
            {
              "step_id": "5a1e...",
              "step_index": 0,
              "agent_id": "7f0c2f9e-3a51-4d8e-9a2b-1c6f0e4d2b11",
              "agent_name": "research-agent",
              "agent_endpoint": "http://research-agent:8000",
              "task_description": "Research recent news on topic X"
            }
          ]
        },
        "status": "active",
        "created_at": "2026-11-10T09:12:44Z",
        "updated_at": "2026-11-10T09:12:44Z",
        "execution_count": 12,
        "success_rate": 83.3,
        "health": "degraded",
        "total_tokens": 48210,
        "last_run_at": "2026-11-13T16:02:10Z",
        "last_run_status": "failed",
        "step_count": 1,
        "agent_names": ["research-agent"],
        "is_public": false
      }
    ],
    "total": 1
  },
  "status_code": 200,
  "message": "Workflows retrieved successfully"
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `400` | plain text | `sort` isn't one of the allowed values, or `limit`/`offset` isn't an integer |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

***

## 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](#generate-a-workflow-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](https://docs.nasiko.com/build/routing-engine.md) 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

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | Display name. Defaults to the first 60 characters of the first step's task |
| `description` | string | No | Free-text description. Blank is stored as `null` |
| `steps` | array | Yes | At least one step, in run order |
| `steps[].task_description` | string | Yes | What the step should do. Must not be blank |
| `steps[].agent_id` | UUID | No | Agent to run the step. Omit to auto-assign |

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/maf/workflows \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research-and-summarize",
    "steps": [
      { "task_description": "Research recent news on topic X", "agent_id": "7f0c2f9e-3a51-4d8e-9a2b-1c6f0e4d2b11" },
      { "task_description": "Summarize the research into 3 bullet points" }
    ]
  }'
```

```json theme={null}
{
  "data": {
    "id": "3b9d6c1e-8f2a-4e57-b0c4-2a7e91d5f803",
    "user_id": "0e4a7b2c-91d3-4f68-a5e0-6c2b8d1f9a47",
    "name": "research-and-summarize",
    "description": null,
    "maf_json": {
      "description": null,
      "output_generation": null,
      "steps": [
        {
          "step_id": "5a1e7c3d-2b4f-4e8a-9c6d-0f1e2a3b4c5d",
          "step_index": 0,
          "agent_id": "7f0c2f9e-3a51-4d8e-9a2b-1c6f0e4d2b11",
          "agent_name": "research-agent",
          "agent_endpoint": "http://research-agent:8000",
          "task_description": "Research recent news on topic X"
        },
        {
          "step_id": "9d8c7b6a-5f4e-4d3c-8b2a-1e0f9d8c7b6a",
          "step_index": 1,
          "agent_id": "c41a8d02-5be7-4f1e-8e33-9b0a7d6c5e20",
          "agent_name": "summarizer",
          "agent_endpoint": "http://summarizer:8000",
          "task_description": "Summarize the research into 3 bullet points"
        }
      ]
    },
    "status": "active",
    "created_at": "2026-11-14T10:01:22Z",
    "updated_at": "2026-11-14T10:01:22Z",
    "execution_count": 0,
    "is_public": false
  },
  "status_code": 201,
  "message": "Workflow created successfully"
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `400` | `steps must not be empty` | `steps` is an empty array |
| `400` | `step <n>: task_description is required` | A step's task is blank |
| `400` | `step <n>: no deployed agent is available to run this step. …` | Auto-assign found no deployed agent |
| `400` | `step <n>: the routing policy refused every agent for this task. …` | Your operator's routing policy refused every candidate. Nasiko doesn't fall back in this case |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `403` | `agent <id> not found` | The named agent doesn't exist or you can't access it |
| `422` | plain text | Body is missing `steps` or a step is missing `task_description` |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

> [!NOTE]
>
> 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](#update-a-workflow). Drafts don't appear in [List workflows](#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

| Field | Type | Required | Description |
| - | - | - | - |
| `instruction` | string | Yes | The instruction as typed. Stored as the draft's `description`; the first 60 characters become its `name` |
| `draft_id` | UUID | No | The draft to overwrite. Omit on the first save |

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/maf/workflow/draft \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "translate hello to japanese then email it to jordan" }'
```

```json theme={null}
{
  "data": {
    "id": "e2c4a6b8-1d3f-4a5c-9e7b-0d2f4a6c8e1b",
    "user_id": "0e4a7b2c-91d3-4f68-a5e0-6c2b8d1f9a47",
    "name": "translate hello to japanese then email it to jordan",
    "description": "translate hello to japanese then email it to jordan",
    "maf_json": { "steps": [] },
    "status": "draft",
    "created_at": "2026-11-14T10:05:00Z",
    "updated_at": "2026-11-14T10:05:00Z",
    "execution_count": 0,
    "is_public": false
  },
  "status_code": 200,
  "message": "Draft saved"
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `400` | `instruction is required` | `instruction` is blank |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `404` | `draft not found` | `draft_id` isn't one of your drafts, or it was deleted or already promoted. Drop the ID and save again to start a new draft |
| `422` | plain text | Body is missing `instruction` |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

***

## 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

| Name | Type | Default | Description |
| - | - | - | - |
| `limit` | integer | `50` | Page size |
| `offset` | integer | `0` | Rows to skip |
| `search` | string | none | Case-insensitive substring match on name and description |
| `sort` | string | `all` | `all` (newest first), `last_updated` (most recently edited first), or `token_usage` (most first) |

The response has the same shape as [List workflows](#list-workflows), with `message: "Drafts retrieved successfully"`. `data.total` counts this page only.

### Example

```bash theme={null}
curl "https://<your-host>/api/maf/workflow/drafts?sort=last_updated" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": {
    "data": [
      {
        "id": "e2c4a6b8-1d3f-4a5c-9e7b-0d2f4a6c8e1b",
        "user_id": "0e4a7b2c-91d3-4f68-a5e0-6c2b8d1f9a47",
        "name": "translate hello to japanese then email it to jordan",
        "description": "translate hello to japanese then email it to jordan",
        "maf_json": { "steps": [] },
        "status": "draft",
        "created_at": "2026-11-14T10:05:00Z",
        "updated_at": "2026-11-14T10:05:41Z",
        "execution_count": 0,
        "success_rate": null,
        "health": "unknown",
        "total_tokens": 0,
        "last_run_at": null,
        "last_run_status": null,
        "step_count": 0,
        "agent_names": [],
        "is_public": false
      }
    ],
    "total": 1
  },
  "status_code": 200,
  "message": "Drafts retrieved successfully"
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `400` | plain text | Invalid `sort`, `limit`, or `offset` |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

***

## 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

| Name | Type | Description |
| - | - | - |
| `id` | UUID | Workflow ID |

### Example

```bash theme={null}
curl https://<your-host>/api/maf/workflow/3b9d6c1e-8f2a-4e57-b0c4-2a7e91d5f803 \
  -H "Authorization: Bearer $TOKEN"
```

The response is a [Workflow](#workflow) in the envelope, with `message: "Workflow retrieved successfully"` (same shape as the [create example](#create-a-workflow), status `200`).

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `403` | `not owned by caller` | The workflow is someone else's and isn't public |
| `404` | `workflow not found` | No such workflow, or it was deleted |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

***

## 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](#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

| Name | Type | Description |
| - | - | - |
| `id` | UUID | Workflow ID |

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | New name |
| `description` | string \| null | No | New description, or `null` to clear |
| `steps` | array | No | Replacement steps, at least one |
| `steps[].task_description` | string | Yes (per step) | What the step should do |
| `steps[].agent_id` | UUID | No | Agent to run the step. Omit to auto-assign |

### Example

```bash theme={null}
curl -X PUT https://<your-host>/api/maf/workflow/3b9d6c1e-8f2a-4e57-b0c4-2a7e91d5f803 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Weekly topic brief",
    "steps": [
      { "task_description": "Research recent news on topic X", "agent_id": "7f0c2f9e-3a51-4d8e-9a2b-1c6f0e4d2b11" },
      { "task_description": "Summarize the research into 5 bullet points" }
    ]
  }'
```

The response is the updated [Workflow](#workflow), status `200`, `message: "Workflow updated successfully"`.

### Errors

| Status | Body | When |
| - | - | - |
| `400` | `steps must not be empty` | `steps` is an empty array |
| `400` | `step <n>: task_description is required` | A step's task is blank |
| `400` | `step <n>: no agents available. …` | Auto-assign found no deployed agent |
| `400` | `step <n>: the routing policy refused every agent for this task. …` | Your operator's routing policy refused every candidate |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `403` | `not owned by caller` | You don't own the workflow (including public workflows you didn't create) |
| `403` | `agent <id> not found` | A named agent doesn't exist or you can't access it |
| `404` | `workflow not found` | No such workflow, or it was deleted |
| `422` | plain text | Body doesn't match the schema |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

***

## 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](#list-all-executions) with `workflow_status: "deleted"`. Runs already queued aren't stopped; use [Stop executions](#stop-executions) first if you need that. Matches `nasiko maf workflow delete`.

**Auth:** session JWT or dashboard cookie. Owner or superuser.

### Path parameters

| Name | Type | Description |
| - | - | - |
| `id` | UUID | Workflow ID |

### Example

```bash theme={null}
curl -X DELETE https://<your-host>/api/maf/workflow/3b9d6c1e-8f2a-4e57-b0c4-2a7e91d5f803 \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": null,
  "status_code": 200,
  "message": "Workflow deleted successfully"
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `403` | `not owned by caller` | You're neither the owner nor a superuser |
| `404` | `workflow not found` | No such workflow, or it was already deleted. Deleting twice returns `404` the second time |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

***

## 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](#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](#update-a-workflow).

Retrying a promotion that already succeeded returns `400` (the workflow is no longer a draft) and changes nothing.

### Path parameters

| Name | Type | Description |
| - | - | - |
| `id` | UUID | Draft ID |

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/maf/workflow/e2c4a6b8-1d3f-4a5c-9e7b-0d2f4a6c8e1b/promote \
  -H "Authorization: Bearer $TOKEN"
```

The response is the promoted [Workflow](#workflow) with `status: "active"`, status `200`, `message: "Draft promoted successfully"`.

### Errors

| Status | Body | When |
| - | - | - |
| `400` | `workflow is already '<status>' — only a draft can be promoted` | It isn't a draft |
| `400` | `this draft has no steps to run — …` | The draft has no steps yet |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `403` | `not owned by caller` | It isn't your draft |
| `404` | `draft not found` | No such draft, it was deleted, or it changed while you were promoting it |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

***

## 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](#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

| Name | Type | Description |
| - | - | - |
| `id` | UUID | Workflow ID |

### Request body

The body is optional. An empty body runs the workflow as saved.

| Field | Type | Required | Description |
| - | - | - | - |
| `content` | string | No | Input for this run only. It's appended, in quotes, to the first step's task, so you can rerun one workflow on different input. Later steps get their input from earlier steps |

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/maf/workflow/3b9d6c1e-8f2a-4e57-b0c4-2a7e91d5f803/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "content": "solid-state batteries" }'
```

```json theme={null}
{
  "data": {
    "execution_id": "a7b8c9d0-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
    "execution_number": 1042,
    "execution_count": 13
  },
  "status_code": 202,
  "message": "Execution started successfully"
}
```

`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](https://docs.nasiko.com/governance/flow-limits.md), 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](https://docs.nasiko.com/api-reference/approvals.md) 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

| Status | Body | When |
| - | - | - |
| `400` | `invalid request body: …` | The body isn't valid JSON |
| `400` | `this workflow has no steps to run — …` | The workflow (usually a saved draft) has no steps |
| `400` | `workflow definition is invalid: …` | The stored definition can't be read |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `403` | `not owned by caller` | Someone else's workflow that isn't public |
| `403` | `step <n>: agent '<name>' is no longer accessible to you` | You've lost access to an agent the workflow uses |
| `404` | `workflow not found` | No such workflow, or it was deleted |
| `429` | plain text | More than 10 expensive requests in a minute |
| `500` | message | The run couldn't be queued. Nothing was created |

> [!NOTE]
>
> 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

| Name | Type | Description |
| - | - | - |
| `id` | UUID | Workflow ID |

### Query parameters

| Name | Type | Default | Description |
| - | - | - | - |
| `limit` | integer | `50` | Page size. Values above `50` are capped at `50` |
| `offset` | integer | `0` | Rows to skip |

`data.total` counts this page only.

### Example

```bash theme={null}
curl "https://<your-host>/api/maf/workflow/3b9d6c1e-8f2a-4e57-b0c4-2a7e91d5f803/executions?limit=10" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": {
    "data": [
      {
        "id": "a7b8c9d0-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
        "execution_number": 1042,
        "maf_id": "3b9d6c1e-8f2a-4e57-b0c4-2a7e91d5f803",
        "user_id": "0e4a7b2c-91d3-4f68-a5e0-6c2b8d1f9a47",
        "status": "success",
        "attempt_count": 1,
        "max_attempts": 3,
        "tokens_used": 3120,
        "started_at": "2026-11-14T10:10:02Z",
        "completed_at": "2026-11-14T10:10:31Z",
        "duration_ms": 29012,
        "output": "- Toyota targets 2027 ...",
        "step_results": [ ],
        "error": null,
        "created_at": "2026-11-14T10:10:01Z",
        "hitl": []
      }
    ],
    "total": 1
  },
  "status_code": 200,
  "message": "Executions retrieved successfully"
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `403` | `not owned by caller` | Someone else's workflow that isn't public |
| `404` | `workflow not found` | No such workflow, or it was deleted. Use [List all executions](#list-all-executions) for a deleted workflow's runs |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

***

## 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](#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

| Name | Type | Description |
| - | - | - |
| `exec_id` | UUID | Execution ID from the run response |

### Example

```bash theme={null}
curl https://<your-host>/api/maf/workflow/result/a7b8c9d0-1e2f-4a3b-8c4d-5e6f7a8b9c0d \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": {
    "id": "a7b8c9d0-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
    "execution_number": 1042,
    "maf_id": "3b9d6c1e-8f2a-4e57-b0c4-2a7e91d5f803",
    "user_id": "0e4a7b2c-91d3-4f68-a5e0-6c2b8d1f9a47",
    "status": "awaiting_human",
    "attempt_count": 1,
    "max_attempts": 3,
    "tokens_used": 1480,
    "started_at": "2026-11-14T10:10:02Z",
    "completed_at": null,
    "duration_ms": null,
    "output": null,
    "step_results": [
      {
        "step_id": "5a1e7c3d-2b4f-4e8a-9c6d-0f1e2a3b4c5d",
        "step_index": 0,
        "agent_id": "7f0c2f9e-3a51-4d8e-9a2b-1c6f0e4d2b11",
        "agent_name": "research-agent",
        "status": "running",
        "error": null,
        "prompt_template": "Research recent news on {topic}",
        "to_extract": "The three most significant developments",
        "prompt": "Research recent news on \"solid-state batteries\"",
        "extracted_info": null,
        "tokens_used": 610,
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "latency_ms": 0,
        "context": null
      }
    ],
    "error": null,
    "created_at": "2026-11-14T10:10:01Z",
    "hitl": [
      {
        "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
        "kind": "tool_approval",
        "status": "pending",
        "question": { },
        "execution": {
          "origin": "maf",
          "maf_execution_id": "a7b8c9d0-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
          "maf_step_index": 0
        },
        "created_at": "2026-11-14T10:10:20Z"
      }
    ]
  },
  "status_code": 200,
  "message": "Execution result retrieved successfully"
}
```

The `hitl` entries above are abbreviated. See the [Approvals API](https://docs.nasiko.com/api-reference/approvals.md) 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](#get-execution-usage).

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `403` | `not owned by caller` | Someone else started this execution |
| `404` | `execution not found` | No such execution |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

***

## 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

| Name | Type | Default | Description |
| - | - | - | - |
| `limit` | integer | `50` | Page size. Values above `50` are capped at `50` |
| `offset` | integer | `0` | Rows to skip |

`data.total` counts this page only.

### Example

```bash theme={null}
curl "https://<your-host>/api/maf/executions?limit=50&offset=50" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": {
    "data": [
      {
        "id": "a7b8c9d0-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
        "execution_number": 1042,
        "maf_id": "3b9d6c1e-8f2a-4e57-b0c4-2a7e91d5f803",
        "user_id": "0e4a7b2c-91d3-4f68-a5e0-6c2b8d1f9a47",
        "status": "success",
        "attempt_count": 1,
        "max_attempts": 3,
        "tokens_used": 3120,
        "started_at": "2026-11-14T10:10:02Z",
        "completed_at": "2026-11-14T10:10:31Z",
        "duration_ms": 29012,
        "output": "- Toyota targets 2027 ...",
        "step_results": [ ],
        "error": null,
        "created_at": "2026-11-14T10:10:01Z",
        "workflow_name": "research-and-summarize",
        "workflow_status": "active",
        "hitl": []
      }
    ],
    "total": 1
  },
  "status_code": 200,
  "message": "Executions retrieved successfully"
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `400` | plain text | `limit` or `offset` isn't an integer |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

***

## Get an execution

`GET /api/maf/execution/{id}`

Returns one execution. The response is identical to [Poll an execution result](#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

| Name | Type | Description |
| - | - | - |
| `id` | UUID | Execution ID |

### Example

```bash theme={null}
curl https://<your-host>/api/maf/execution/a7b8c9d0-1e2f-4a3b-8c4d-5e6f7a8b9c0d \
  -H "Authorization: Bearer $TOKEN"
```

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `403` | `not owned by caller` | Someone else started this execution |
| `404` | `execution not found` | No such execution |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

***

## 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

| Name | Type | Description |
| - | - | - |
| `id` | UUID | Execution ID |

### Response fields

| Field | Type | Description |
| - | - | - |
| `execution_id` | UUID | The execution |
| `status` | string | The execution's [status](#execution-status), so you can poll this route alone |
| `complete` | boolean | Nothing further to wait for |
| `usage_available` | boolean | Whether this server collects agent usage at all |
| `unresolved_steps` | integer | Steps that called their agent but haven't reported usage yet |
| `steps[]` | array | One entry per step |
| `steps[].step_index`, `steps[].agent_name` | | Which step |
| `steps[].trace_id` | string \| null | The step's trace. `null` if the step never reached its agent |
| `steps[].resolved` | boolean | Whether this step's agent usage has arrived |
| `steps[].input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens` | integer | Agent tokens, summed over every agent on the step's trace (including sub-agents) |
| `steps[].model` | string \| null | The model, when every agent on the trace used the same one |
| `steps[].cost_usd` | number | Agent cost for the step |
| `steps[].maf_tokens` | integer | Workflow orchestration tokens for the step. Known as soon as the step finishes |
| `steps[].latency_ms` | integer | Step latency |
| `totals.input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens` | integer | Sums over resolved steps |
| `totals.agent_tokens` | integer | `input_tokens + output_tokens` over resolved steps |
| `totals.maf_tokens` | integer | All workflow orchestration tokens: steps, planning, and final synthesis |
| `totals.cost_usd` | number | Orchestration cost plus resolved agent cost |

### Example

```bash theme={null}
curl https://<your-host>/api/maf/execution/a7b8c9d0-1e2f-4a3b-8c4d-5e6f7a8b9c0d/usage \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": {
    "execution_id": "a7b8c9d0-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
    "status": "success",
    "complete": false,
    "usage_available": true,
    "unresolved_steps": 1,
    "steps": [
      {
        "step_index": 0,
        "agent_name": "research-agent",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "resolved": true,
        "input_tokens": 5120,
        "output_tokens": 830,
        "cache_read_tokens": 0,
        "cache_creation_tokens": 0,
        "model": "gpt-4o-mini",
        "cost_usd": 0.00127,
        "maf_tokens": 610,
        "latency_ms": 14210
      },
      {
        "step_index": 1,
        "agent_name": "summarizer",
        "trace_id": "9a3c1e7f20b84d65b1f0c4e2d8a6b3f1",
        "resolved": false,
        "input_tokens": 0,
        "output_tokens": 0,
        "cache_read_tokens": 0,
        "cache_creation_tokens": 0,
        "model": null,
        "cost_usd": 0.0,
        "maf_tokens": 540,
        "latency_ms": 6120
      }
    ],
    "totals": {
      "input_tokens": 5120,
      "output_tokens": 830,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "agent_tokens": 5950,
      "maf_tokens": 3120,
      "cost_usd": 0.00241
    }
  },
  "status_code": 200,
  "message": "Execution usage retrieved successfully"
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `403` | `not owned by caller` | Someone else started this execution |
| `404` | `execution not found` | No such execution |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

***

## 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

| Name | Type | Description |
| - | - | - |
| `id` | UUID | Execution ID |

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/maf/execution/a7b8c9d0-1e2f-4a3b-8c4d-5e6f7a8b9c0d/stop \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": {
    "id": "a7b8c9d0-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
    "previous_status": "running"
  },
  "status_code": 200,
  "message": "Execution stopped"
}
```

`previous_status` is what the run was doing when you stopped it.

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `404` | `execution not found` | No such execution, or it isn't yours |
| `409` | `execution already finished: <status>` | It's already `success`, `failed`, or `stopped`. Safe to treat as done |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

***

## 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](#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`.

| Field | Type | Required | Description |
| - | - | - | - |
| `execution_ids` | UUID\[] | One of the two | Up to 1,000 execution IDs. Duplicates are ignored |
| `workflow_id` | UUID | One of the two | Stop every unfinished run of this workflow you started |

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/maf/executions/stop \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "workflow_id": "3b9d6c1e-8f2a-4e57-b0c4-2a7e91d5f803" }'
```

```json theme={null}
{
  "data": {
    "stopped": [
      { "id": "a7b8c9d0-1e2f-4a3b-8c4d-5e6f7a8b9c0d", "previous_status": "running" },
      { "id": "b8c9d0e1-2f3a-4b4c-9d5e-6f7a8b9c0d1e", "previous_status": "pending" }
    ],
    "already_finished": [
      { "id": "c9d0e1f2-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "status": "success" }
    ],
    "not_found": []
  },
  "status_code": 200,
  "message": "2 execution(s) stopped"
}
```

| Field | Description |
| - | - |
| `stopped` | Runs that were in flight and are now `stopped`, with the status they had |
| `already_finished` | Runs you asked for that had already ended, with their final status |
| `not_found` | IDs that don't exist or aren't yours |

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

### Errors

| Status | Body | When |
| - | - | - |
| `400` | `invalid request body: …` | The body isn't valid JSON |
| `400` | `give either execution_ids or workflow_id, not both` | Both were sent |
| `400` | `execution_ids or workflow_id is required` | Neither was sent (or `execution_ids` is empty) |
| `400` | `at most 1000 execution_ids per request` | Too many IDs |
| `401` | `invalid or missing user identity` | Token missing or invalid |
| `403` | `not owned by caller` | `workflow_id` is someone else's and isn't public |
| `404` | `workflow not found` | `workflow_id` doesn't exist or was deleted |
| `429` | plain text | Standard-tier rate limit |
| `500` | message | Server error |

## Related

> [card] [Workflows](https://docs.nasiko.com/build/workflows.md)
>
> How workflows chain agents and where each step's output goes.

> [card] [Workflow commands](https://docs.nasiko.com/reference/cli/workflows.md)
>
> The same operations from `nasiko maf`.

> [card] [Approvals API](https://docs.nasiko.com/api-reference/approvals.md)
>
> Resolve a run that's `awaiting_human`.

> [card] [Flow limits](https://docs.nasiko.com/governance/flow-limits.md)
>
> Token, depth, and time limits applied to each step.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.