Skip to main content
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).

Start a build

Encode the body as JSON.
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

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: A refine changes only the steps the feedback concerns; every other step comes back exactly as it was sent.

Stream — GET /builds//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.
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.