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.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 withinit (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.