Strictly tenant- and project-scoped. A run that exists under a
different projectId (or under a different tenant entirely)
returns 404 not_found — never 403, never the run record.
This matches OWASP API1:2023 Broken Object Level Authorization
guidance: same shape for "doesn't exist" and "not yours".
Authorizations
Authorizationstringheaderrequired
Bearer authentication header of the form Bearer <token>, where <token> is your access token.
app when an app sent the prompt rather than a person: an MCP client (name is "Claude", "Cursor"…) or an integration.
Available optionsapp
Example:app
statusAgentRunStatusrequired
The run's status.
Available optionsqueuedrunningdeployingreadyfailedcancelledneeds_input
phasestring
Internal Spec Kit phase for the active builder run. Stream-v6 maps this to user-facing data-status.data.phase values such as planning, clarifying, coding, and building.
Available optionsinitconstitutionspecifyclarifyplantasksanalyzeimplementindexingbuilddeployready
Example:plan
phaseStatusstring
Phase-local status for the active Spec Kit phase.
Available optionsqueuedrunningawaiting_inputterminal
Example:running
awaitingQuestionobject
The question the run is paused on, while it waits for the creator.
awaitingQuestion.capIdstringrequired
The question's id: send it back as capId with the answer.
Example:cap_portal_modules
awaitingQuestion.questionstringrequired
The question to put to the creator.
Example:Which areas should your portal have?
awaitingQuestion.choicesstring[]
The answers to offer, when it is a choice.
Example:["Courses","Communities"]
awaitingQuestion.formobject
Set when the answer is a form (record fields or media) rather than a choice; its kind says which.
oneOf
RecordQuestionForm
MediaQuestionForm
The record-fields form on awaitingQuestion.form. The answer value
is JSON.stringify({ fields: [{ label, type, options? }], show: [label, …] })
(fields = the NEW fields, show = every field clients see); as the
editor (edit: true) it also carries edits and has show only when
what clients see changed.
Set when this is the editor for an existing record type.
Available optionstrue
Example:true
awaitingQuestion.form.typesobject[]required
The field types the dropdown offers (server-owned).
awaitingQuestion.form.types[].valuestringrequired
The type, as an answer sends it.
Example:TEXT
awaitingQuestion.form.types[].labelstringrequired
What the creator sees.
Example:Single line
awaitingQuestion.form.types[].withOptionsboolean
This type takes a list of choices.
Available optionstrue
Example:true
awaitingQuestion.form.types[].noConvertboolean
An existing field cannot be changed to this type.
Available optionstrue
Example:true
awaitingQuestion.detailsstring
What the creator is agreeing to, shown under the question.
Example:Your portal will use the Courses and Communities modules.
awaitingQuestion.previewobject
What the builder shows the creator beside this question. Display only: its shape follows the builder's screens and may change.
awaitingQuestion.preview.property name*any
What the builder shows the creator beside this question. Display only: its shape follows the builder's screens and may change.
awaitingQuestion.multiSelectboolean
Several choices may be picked.
Example:false
awaitingQuestion.allowOtherboolean
Adds a "Something else" choice that opens a box.
Example:true
awaitingQuestion.inputstring
With no choices, one line or a paragraph.
Available optionsshort_textlong_text
Example:short_text
awaitingQuestion.placeholderstring
Hint text for a typed answer.
Example:e.g. Weekly yoga classes
awaitingQuestion.askedAtstring<date-time>required
When the run asked.
Example:2026-10-15T09:32:00.000Z
pendingQuestionsobject[]
The questions a first build asks before it starts, while status is needs_input: answer them all with POST .../runs/{runId}/answers/batch, each by its capId.
pendingQuestions[].capIdstringrequired
The question's id: send it back as capId with its answer.
Example:clarify.cp.name
pendingQuestions[].displayNamestring
What kind of question it is.
Example:Planning question
pendingQuestions[].textstringrequired
The question.
Example:What should we call it?
pendingQuestions[].optionsobject[]required
The answers to pick from; empty when freeText asks for a typed answer.
pendingQuestions[].options[].valuestringrequired
What to send back when this option is picked.
Example:slate
pendingQuestions[].options[].labelstringrequired
The option as the creator reads it.
Example:Slate
pendingQuestions[].options[].hintstring
A second line under the label.
Example:Calm and neutral
pendingQuestions[].options[].selectedboolean
Picked unless the creator unpicks it.
Example:false
pendingQuestions[].options[].freeTextboolean
Picking it means typing the answer instead.
Example:false
pendingQuestions[].options[].swatchesstring[]
A palette's colours, lightest to darkest.
Example:["#364152","#697586"]
pendingQuestions[].options[].brandstring
The colour a palette leads with.
Example:#364152
pendingQuestions[].options[].platformsstring[]
The platforms the option exists on, when not all.
Example:["mobile"]
pendingQuestions[].options[].property name*any
pendingQuestions[].multiSelectboolean
Several options may be picked.
Example:false
pendingQuestions[].freeTextboolean
No options: the answer is typed.
Example:true
pendingQuestions[].placeholderstring
Hint text for a typed answer.
Example:e.g. Forge Fitness
pendingQuestions[].helperstring
A supporting line under the question.
Example:The name your customers see when they sign in.
pendingQuestions[].groupstring
The page of the intake form it belongs to.
Example:app
pendingQuestions[].controlstring
How the builder draws it: cards, swatches, fonts, text and so on.
Example:text
pendingQuestions[].platformsstring[]
The platforms the question exists on, when not all.
Example:["mobile"]
publicPhaseStateobject
Where the run is, in the words the builder shows the creator.
publicPhaseState.phasestringrequired
The step the run is on.
Example:clarifying
publicPhaseState.phaseStatusstringrequired
Where that step is.
Available optionsqueuedrunningawaiting_inputterminal
Example:awaiting_input
publicPhaseState.messagestring
The step in one sentence for the creator.
Example:Answer the planning question to continue.
publicPhaseState.phaseIndexinteger
The step's position, from 0.
Example:2
publicPhaseState.phaseTotalinteger
How many steps the run has.
Example:6
publicPhaseState.tsstring<date-time>
When the run reached this state.
Example:2026-10-23T12:57:27.435Z
createdAtstring<date-time>required
When the run was created.
Example:2026-10-15T09:30:00.000Z
updatedAtstring<date-time>required
When the run last changed.
Example:2026-10-15T09:41:12.000Z
checkProblemsstring[]
Problems the check found in a build written by an outside agent (externalAgent: true)
that still built and deployed. Fix them with another set of edits and run.
Example:["pages/learn.vue: 'courses' is possibly undefined"]
previewUrlstring<uri>
Convenience field equal to preview.primaryUrl. Kept for
single-service callers; multi-service callers should read
preview.services[] for per-service URLs. This is the
durable customer-facing preview URL produced after a
successful build/deploy, not the live sandbox edit URL.
Example:https://preview.example.com/my-portal
previewobject
Where to see what the run built.
preview.primaryUrlstring<uri>required
The URL the user opens — for multi-service web stacks, this is the primary (frontend) URL.
Deprecated 2026-05-17. Will be removed 2026-11-17.
Use sandboxUrl instead — same value, accurate name.
Misleadingly named: this is the SANDBOX URL (the agent's
HMR/edit workshop), not the customer-facing preview. The
customer preview lives at previewUrl. Co-populated with
sandboxUrl for the deprecation window; readers should
migrate to sandboxUrl.
Example:https://sbx-prj-5f0c2a3e.example.com
livePreviewStatusstringdeprecated
Deprecated 2026-05-17. Will be removed 2026-11-17.
Use sandboxStatus instead.
Available optionsstartingreadyfailedstopped
Example:ready
sandboxUrlstring<uri>
URL of the project sandbox runtime.
This is the agent's compile + HMR workshop — NOT the
customer-facing preview. The customer preview is at
previewUrl, which surfaces in the builder UI's right
pane after the deploy gate succeeds.
Example:https://sbx-prj-5f0c2a3e.example.com
sandboxStatusstring
Current state of the sandbox dev server.
Available optionsstartingreadyfailedstopped
Example:ready
publishedUrlstring<uri>
URL of the production ("Published") runtime service for this project.
Populated when the project has
been explicitly published at least once. Distinct from
previewUrl/preview.primaryUrl, which always point at the
durable customer preview service that auto-updates on every
successful agent run. Absent for projects that have never
been published — the FE renders "Not published" in that case.
Example:https://my-portal.example.com
publishedAtstring<date-time>
ISO-8601 timestamp of the most recent publish, snapshotted
onto the run at the moment it reached ready. Used by the
FE to render staleness like "Last published 5 hours ago".
Example:2026-10-14T18:02:00.000Z
runsSinceLastPublishinteger
Number of successful (status=ready) runs completed since
the project was last published. Reset to 0 by publish.
Snapshotted onto each ready run so the FE can render a
staleness indicator without an extra round-trip. Absent
for projects that have never been published.
Possible values:>= 0
Example:2
summarystring
AI-generated 1-line checkpoint description, snapshotted onto
the run record at setStatus("ready") time. Sourced from
the agent's completion narrator event when present,
otherwise falls back to a deterministic prompt-derived
stub. Read by Timeline + chat UI so users see "what
changed in this checkpoint" at a glance. Absent on
non-terminal or legacy runs.
Example:Added an events page
imageUristringdeprecated
Deprecated: no longer returned. It named the builder's own image registry.
Deprecated: no longer returned. It named the builder's own image.
Example:sha256:3b1f0c9e2d7a
failureMessagestring
Why the run failed, in one line.
Example:The build failed: pages/events.vue has a type error
failureobject
Structured failure taxonomy for a terminated run. Set in
tandem with failureMessage (which is the human-readable
derivation). Discriminated by category; consumers should
branch on category + code to render an actionable hint
instead of a generic "Internal error".
failure.categorystringrequired
What kind of failure it was.
Available optionsuser_inputconfigmodelbuildinfraspec_kittransportruntimeinternal
Example:build
failure.codestringrequired
Category-specific failure code. See the run-runtime
RunFailure discriminated union for the per-category
code enum.
Example:build_failed
failure.retryablebooleanrequired
Sending the same request again may succeed.
Example:false
failure.responsibleModulestringrequired
The part of the builder that failed.
Available optionsruntimedispatcherplannerclassifierspec_kitdesignerscaffolderbuilderverifierdeployerinframodel_provider
Example:runtime
failure.userMessagestring
For category=user_input — text safe to show the user verbatim.
Example:Describe the page you want in a sentence or two.
failure.detailsstring
For category=config / spec_kit — operator-facing detail.
Example:No stack manifest for this template
failure.providerstring
For category=model — provider identifier (e.g. anthropic, openai).
Example:anthropic
failure.attemptinteger
For category=model — retry attempt index that ultimately gave up.
Example:3
failure.failureHeadstring
For category=build — first chunk of compiler/test stderr.
Example:pages/events.vue(12,5): error TS2339
failure.failureTailstring
For category=build — last chunk of compiler/test stderr.
Example:Found 1 error.
failure.causestring
For category=infra — short cause description.
Example:The sandbox did not become ready in time
failure.phasestring
For category=spec_kit — phase id where the orchestrator halted.
Example:plan
failure.stackstring
For category=internal — first lines of the stack trace. Never sent to a sub-account token.
Example:TypeError: Cannot read properties of undefined
failure.messagestring
For category=runtime — text safe to show the user verbatim.
Example:The preview could not start.
metadataobjectdeprecated
Deprecated: no longer returned. It held the builder's own debugging state.
metadata.generationFailureobject
Why generating the app failed, when it did.
metadata.generationFailure.codestring
The failure code.
Available optionsprovider_transientdispatch_failedscaffold_failedinfra_failedagent_failedbuild_faileddeploy_failedrun_stalledpipeline_failed
Example:provider_transient
metadata.generationFailure.retryableboolean
Retrying may succeed.
Example:true
metadata.generationFailure.sourcestring
Where it failed.
Available optionsproviderdispatchplanningscaffoldinfraagentbuilddeploypipeline
Example:provider
metadata.generationFailure.detailstring
Detail for support.
Example:The model provider was overloaded
metadata.generationFailure.property name*any
Why generating the app failed, when it did.
metadata.failedWorkspaceobject
The workspace kept from a failed run, for diagnosis.