Skip to main content
Client App BuilderVersion: v3

Submit a prompt; the agent runs in the background.

POST/ai-builder-api/projects/{projectId}/runs

Returns runId at once; the run goes on in the background. An agent outside the builder (an MCP client) writes the app's code first: POST .../sandbox/edit for each file (and, for a React Native app, POST .../sandbox/extension-routes for its screens), then POST .../sandbox/checkpoint to save them, then this call with externalAgent: true, which checks, builds and deploys the preview. Without externalAgent, the builder's own agent writes the code from prompt.

Poll GET .../runs/{runId} until status is ready or failed. A first build may stop at needs_input with pendingQuestions: answer them with POST .../runs/{runId}/answers/batch. Problems a passing build still has are in checkProblems.

Idempotency: send an Idempotency-Key header on every retry. The same key and body replays the original runId for 24 hours; the same key with a different body answers 409 idempotency_conflict.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:clientportal-ai.write
Auth methods:OAuthPrivate Integration
Token type:Sub-Account Token

Request​

Headers

Idempotency-Keystring

Caller-generated key (UUID-v4 recommended) that makes this POST safe to retry. Must match the prior request body byte-for-byte on replay. Reused with a different body → 409.

Possible values: non-empty and <= 255 characters

Example:6d2f0a8e-1b3c-4d5e-8f9a-0b1c2d3e4f5a
X-Correlation-Idstring

Optional caller-supplied trace id. When omitted, the API mints cid_<uuid> and echoes it back via the response X-Correlation-Id header. Threaded through audit rows + logs.

Possible values: non-empty and <= 64 characters

Example:cid_7d9e2f1a
Versionstringrequired

The API version.

Available optionsv3
Example:v3

Path Parameters

projectIdstringrequired

The project's id.

Possible values: Value must match regular expression ^prj_[A-Za-z0-9_-]+$

Example:prj_5f0c2a3e

Body

application/json
promptstringrequired

What to build or change.

Possible values: non-empty and <= 20000 characters

Example:Add a page listing upcoming events
displayTextstring

What the creator's chat bubble shows for this run instead of prompt, when the client sends an instruction the creator did not type (for example a suggestion chip, whose full text carries verifier output or a planner directive for the agent). One plain line. Omitted for typed messages, whose bubble is the prompt.

Possible values: non-empty and <= 200 characters, Value must match regular expression ^(?=.*\S)[^\p{Cc}]+$

Example:Fix these issues
productTargetProductTarget

What the project builds; the project's own by default.

Available optionsfull_stackmobilelanding_page
customCodeboolean

For the builder's own agent on a ClientPortal app: true lets it change the app's code, false limits it to the app's settings. Not used with externalAgent.

Default:false
Example:false
clientPortalSurfacestring

ClientPortal-only context captured from the selected builder surface. Unqualified follow-ups default to this lane; explicit web, mobile, or web-and-mobile wording in the prompt takes precedence.

Available optionswebmobile
Example:web
externalAgentboolean

An agent outside the builder (an MCP client) writes this run's code in the project's sandbox. The run skips the builder's agent: a first build asks the builder's intake questions (answered through the answers API), then every run checks, delivers, registers the sandbox with ClientPortal, and seals a publishable release.

Default:false
Example:true
summaryobject

With externalAgent only: what the agent changed, in the words its creator would use. The builder's chat shows it as the run's summary, beside the files the agent changed in the sandbox. Without it, the chat lists those files.

mobilePipelinestring

Deprecated compatibility field for older mobile clients. New mobile runs use the standard builder flow with the React Native app kernel.

Available optionsv2-simple
Example:v2-simple
mobilePipelineSpeedstring

Deprecated: accepted from older mobile clients and ignored.

Available optionsfastslow
Example:fast
modelIdstring

The model the builder's own agent uses for every step of this run; omitted, the platform picks one per step. Not used with externalAgent.

Possible values: non-empty and <= 200 characters

Example:claude-sonnet-4-5
agentIdstring

An agent profile the creator set up in the builder, for the builder's own agent. Not used with externalAgent.

Possible values: Value must match regular expression ^agt_[A-Za-z0-9_-]+$

Example:agt_4c2d1e
modestring

How the builder's own agent works: auto (it decides), plan (it proposes a plan and waits for the creator's approval in the builder) or build (straight to code); plan_first is plan. Not used with externalAgent.

Available optionsautoplanbuildplan_first
Example:auto
attachmentIdsstring[]

Files the creator uploaded in the builder, given to the builder's own agent as context. Not used with externalAgent.

Possible values: <= 10

Example:["att_1a2b3c"]
selectedElementsobject[]

Visual edits (vibe apps): the elements the creator selected in the live preview before sending. The agent receives them as a <selected-elements> block after the prompt, so "this" means the element on screen. Context only: file and line are hints the agent checks against the workspace.

Possible values: <= 20

Response

application/json

Accepted; agent is running.

    X-Correlation-Id

    Correlation id used for log + audit stitching.

runIdstringrequired

The run that started.

Possible values: Value must match regular expression ^run_[A-Za-z0-9_-]+$

Example:run_8f3c2a91
stateobjectrequired

The run as it starts.