Skip to main content
Version: v3

Submit a prompt; the agent runs in the background.

POST 
/ai-builder-api/projects/:projectId/runs

Returns runId immediately. The agent executes asynchronously: attempt workspace restore from project's prior run → materialise scaffold (only if no prior workspace) → loop tool calls → preflight pnpm build → flush workspace to GCS → deploy via Cloud Build → managed runtime revision replace → mark ready with a preview URL.

Per-project runtime services receive a stable public app hostname so the iframe URL works without platform-session auth.

Idempotency: callers SHOULD send an Idempotency-Key header on every retry. The server stores (locationId, projectId, key) → runId for 24 h. Same key + same body → the original runId is replayed. Same key + different body → 409 idempotency_conflict. Modeled after standard idempotent POST contracts; safe for browser retries, network blips, and double-click submits.

Attachment scope: when attachmentIds are present, each id is verified against the caller's tenant + project. Cross-project or cross-tenant reuse is rejected with 403 attachment_not_owned.

Request​

Idempotency-Key string

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

X-Correlation-Id string

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

Version stringrequired

The API version.

Available optionsv3
projectId stringrequired

The project's id.

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

application/json

Bodyrequired

    promptstringrequired

    What to build or change.

    Possible values: non-empty and <= 20000 characters

    productTargetProductTarget

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

    Available optionsfull_stackmobilelanding_page
    customCodeboolean

    ClientPortal-only per-run switch. When false or omitted, the agent can inspect the project and apply SDUI configuration, but source-code, shell, dependency, and build tools are unavailable. When true, the existing full custom-code tool surface is enabled. This choice does not change sandbox provisioning or preview lifecycle behavior.

    Default value: 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
    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 value: false
    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
    mobilePipelineSpeedstring

    Deprecated compatibility field. Accepted for older mobile clients but no longer selects a distinct generation pipeline; production mobile codegen uses the single-loop Mastra path.

    Available optionsfastslow
    modelIdstring

    Model id from GET /api/v1/catalog/models. When provided, this single model is used for every phase of the agent (classify, plan, code). When omitted, the platform routes to its per-phase defaults (Haiku → Sonnet → Opus).

    Possible values: non-empty and <= 200 characters

    agentIdstring

    Optional id of a user-defined agent profile created via POST /api/v1/agents. The profile's systemInstructions and skills are appended to the platform's catalog for this run, and its defaultModelId is honoured when modelId is not set.

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

    modestring

    Run mode. The composer's 3-way segmented control surfaces:

    • auto (default) — agent honours the classifier's recommended_mode and decides whether to plan, ask, or build straight through.
    • plan — agent always proposes a plan first via propose_plan and pauses for approval. The plan is surfaced as a plan_approval_request narrator event; the user POSTs an approve/refine/reject verdict to /agent-runs/{runId}/plan-approval.
    • build — agent skips planning and goes straight to file_editor (only ask_user when the classifier flags a high-cost architectural unknown).
    • plan_first — back-compat alias for plan. v1 callers still emit it; the runtime treats it as plan.
    Available optionsautoplanbuildplan_first
    attachmentIdsstring[]

    Optional ids of attachments previously created via POST /api/v1/projects/{projectId}/attachments/upload-url. Surfaced to the agent as user-provided context so generated code can reference uploaded files (logos, PDFs, brand assets).

    Possible values: <= 10

    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

application/json

Accepted; agent is running.

    X-Correlation-Id

    Correlation id used for log + audit stitching.

Schema
    runIdstringrequired

    The run that started.

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

    stateobjectrequired

    The run as it starts.