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

# Building workflows and agents

> How POST /builds turns a brief into a workflow or an agent in the background, and how to follow the build and read its result.

A workflow or an agent is built from a plain-language brief, or changed from feedback, by a **build**: a background job like a run. `POST /builds` answers at once with the build's id; follow it as a stream, or read it until it has ended. A build needs the **Agents** permission. It is visible to the person who started it (a key acts for the person who created it) and to the Admins of its organization; anyone else is told it does not exist (`404`).

| Route | Does |
| - | - |
| `POST /builds` | Start a build. `202 {"id", "status": "queued"}` |
| `GET /builds/{build_id}` | The build: its status, stages, plan and steps, and the result once it succeeded |
| `GET /builds/{build_id}/stream` | Server-Sent Events of the build, from a snapshot to `done` |
| `GET /builds?kind=workflow&mode=build&active=true&unsaved=true&limit=20` | The caller's own builds, newest first, without their results. `mode` keeps the first builds (`build`) or the refines (`refine`). `active=true` keeps the queued and running ones, `unsaved=true` those not marked saved, `target_id=<id>` the refines of that saved workflow or agent; `limit` is 1 to 50 |
| `POST /builds/{build_id}/cancel` | Stop the build. A build that has ended is answered as it is |
| `POST /builds/{build_id}/saved` | Mark the build's result saved as a workflow or an agent. Only the person who started it may (`403` for anyone else who may read it), and only once the build succeeded (`409` while it is queued or running, or after it failed or was cancelled); marking it again keeps the first time |

## Start a build

Encode the body as JSON.

| Field | Used for | Description |
| - | - | - |
| `kind` | always | `workflow` or `agent` |
| `mode` | always | `build` (default) or `refine` |
| `description` | build | The brief, at least 10 characters |
| `sample_files` | build | Optional `[{"filename", "snippet"}]`: what people will upload; each snippet is read up to 1,200 characters |
| `blueprint` | workflow refine | The workflow as it stands |
| `spec` | agent refine | The agent as it stands |
| `feedback` | refine | What to change |
| `design_history` | refine | Optional `[{"role": "user" \| "ai", "content"}]`: the conversation so far, oldest first |
| `brief` | agent refine | Optional: the brief the agent was first built from; without it, the first thing the person wrote in `design_history` is the brief, and the build shows it as such. A workflow keeps its brief in the blueprint's `metadata.brief` |
| `target_id` | refine | Optional: the id of the saved workflow or agent the refine changes, returned with the build |

```bash theme={null}
curl -X POST https://api.neuralfactory.ai/builds \
  -H "Authorization: Bearer $NF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind": "workflow", "description": "Read the uploaded supplier list, search each supplier for adverse news and write a risk report"}'
```

A body that does not fit its kind and mode answers `422` with a sentence saying why. Builds count against a per-person limit per minute (`429` with `Retry-After`), and a suspended organization cannot build (`403`).

## The build

```json theme={null}
{
  "id": "bld_9c2...",
  "kind": "workflow",
  "mode": "build",
  "status": "running",
  "model": "gpt-6-astra",
  "title": "Supplier Risk Check",
  "request": {"description": "Read the uploaded supplier list, ...", "feedback": null, "brief": null},
  "target_id": null,
  "stages": [
    {"key": "plan", "title": "Plan the steps", "status": "done", "detail": "", "started_at": "2026-11-14T10:00:01+00:00", "finished_at": "2026-11-14T10:00:42+00:00", "seconds": 41.2},
    {"key": "write", "title": "Write the steps", "status": "running", "detail": "", "started_at": "2026-11-14T10:00:42+00:00", "finished_at": null, "seconds": null}
  ],
  "plan": {"steps": [{"id": "read_file", "name": "Read the supplier file", "type": "tool_action", "wave": 1, "parent": null, "added_because": null}]},
  "steps": {"read_file": {"status": "done", "errors": [], "seconds": 8.4}},
  "result": null,
  "error": null,
  "cost": null,
  "created_at": "2026-11-14T10:00:00+00:00",
  "updated_at": "2026-11-14T10:01:12+00:00",
  "finished_at": null,
  "saved_at": null
}
```

`request` is what the build was asked: the brief of a build, the feedback of a refine and the brief of what a refine changes; never the blueprint, spec or conversation it was sent. A list leaves it out. `status` is `queued`, `running`, `succeeded`, `failed` or `cancelled`. A workflow build shows the stages `plan`, `write`, `assemble`, `check` and `review`; a workflow refine the same keys, starting with "Plan the change". Each step of the plan is `waiting`, `writing`, `done`, `fixing` or `failed`. A failed build has `error`, such as `"Plan the steps failed: ..."`; a build that ended has `cost`.

The `result` of a workflow build or refine:

| Field | Description |
| - | - |
| `blueprint` | The workflow. Nothing is saved: create it with `POST /workflows/create` or save it on an existing workflow |
| `validation_errors` | Problems the checks still find, as warnings |
| `compiled_with_model` | The model that built it |
| `cost` | What the build cost |
| `report` | How it was built: which steps answer each step of the brief, the steps added and why, the review's findings, the steps that failed their checks, the calls and their timings. A refine's report also has `change`: its summary and the steps rewritten, added and removed |

A refine changes only the steps the feedback concerns; every other step comes back exactly as it was sent.

## Stream — GET /builds/{build_id}/stream

Every connection opens with `init` (the build without its result), then sends what changes, then `done`; reconnect at any time. Read `GET /builds/{build_id}` once after `done` for the result.

```
event: init          data: {"id": "bld_9c2...", "status": "queued", "stages": [...], ...}
event: status        data: {"status": "running"}
event: stage         data: {"key": "plan", "title": "Plan the steps", "status": "done", "detail": "", "started_at": "...", "finished_at": "...", "seconds": 41.2}
event: plan          data: {"steps": [...]}
event: step          data: {"id": "read_file", "status": "done", "errors": [], "seconds": 8.4}
event: done          data: {"status": "succeeded", "error": null}
```

`status` is sent when a build still under way changes status (from `queued` to `running`); its end is `done`. A cancelled build is charged by its worker a moment after `done`: read it again a few seconds later for its `cost`. `stream_error` (`{"message"}`) means the stream stopped; reconnect or read the build.

***


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