# Submit a prompt; the agent runs in the background. POST https://services.leadconnectorhq.com/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`. ## Authentication Send `Authorization: Bearer ` using: - **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `clientportal-ai.write` ## Parameters ### Header Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Idempotency-Key` | string | No | 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`. | | `X-Correlation-Id` | string | No | Optional caller-supplied trace id. When omitted, the API mints `cid_` and echoes it back via the response `X-Correlation-Id` header. Threaded through audit rows + logs. | | `Version` | string | Yes | The API version. | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `projectId` | string | Yes | The project's id. | ## OpenAPI Specification ```json { "openapi": "3.0.0", "info": { "title": "LeadConnector API", "version": "v3" }, "servers": [ { "url": "https://services.leadconnectorhq.com" } ], "paths": { "/ai-builder-api/projects/{projectId}/runs": { "post": { "summary": "Submit a prompt; the agent runs in the background.", "operationId": "submitAPromptTheAgentRunsInTheBackground", "description": "Returns `runId` at once; the run goes on in the background. An agent outside the builder (an\nMCP client) writes the app's code first: `POST .../sandbox/edit` for each file (and, for a\nReact Native app, `POST .../sandbox/extension-routes` for its screens), then\n`POST .../sandbox/checkpoint` to save them, then this call with `externalAgent: true`, which\nchecks, builds and deploys the preview. Without `externalAgent`, the builder's own agent\nwrites the code from `prompt`.\n\nPoll `GET .../runs/{runId}` until `status` is `ready` or `failed`. A first build may stop at\n`needs_input` with `pendingQuestions`: answer them with `POST .../runs/{runId}/answers/batch`.\nProblems a passing build still has are in `checkProblems`.\n\n**Idempotency**: send an `Idempotency-Key` header on every retry. The same key and body\nreplays the original `runId` for 24 hours; the same key with a different body answers\n`409 idempotency_conflict`.\n", "parameters": [ { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string", "pattern": "^prj_[A-Za-z0-9_-]+$" }, "description": "The project's id.", "example": "prj_5f0c2a3e" }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "maxLength": 255, "minLength": 1 }, "description": "Caller-generated key (UUID-v4 recommended) that makes this POST\nsafe to retry. Must match the prior request body byte-for-byte\non replay. Reused with a different body → `409`.\n", "example": "6d2f0a8e-1b3c-4d5e-8f9a-0b1c2d3e4f5a" }, { "in": "header", "name": "X-Correlation-Id", "required": false, "schema": { "type": "string", "maxLength": 64, "minLength": 1 }, "description": "Optional caller-supplied trace id. When omitted, the API mints\n`cid_` and echoes it back via the response\n`X-Correlation-Id` header. Threaded through audit rows + logs.\n", "example": "cid_7d9e2f1a" }, { "name": "Version", "in": "header", "required": true, "description": "The API version.", "schema": { "type": "string", "enum": [ "v3" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitAgentRunRequest" } } } }, "responses": { "202": { "description": "Accepted; agent is running.", "headers": { "X-Correlation-Id": { "description": "Correlation id used for log + audit stitching.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitAgentRunResponse" } } } }, "403": { "description": "One or more `attachmentIds` are not owned by this project (or\nbelong to a different tenant). Code: `attachment_not_owned`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "`Idempotency-Key` was reused with a different request body.\nCode: `idempotency_conflict`. Generate a fresh key for the\nnew payload.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "bearer": [ "clientportal-ai.write" ] } ] } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A sub-account access token: a Marketplace app's OAuth token or a Private Integration Token." } }, "schemas": { "SubmitAgentRunRequest": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "What to build or change.", "example": "Add a page listing upcoming events" }, "displayText": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^(?=.*\\S)[^\\p{Cc}]+$", "description": "What the creator's chat bubble shows for this run instead of\n`prompt`, when the client sends an instruction the creator did not\ntype (for example a suggestion chip, whose full text carries\nverifier output or a planner directive for the agent). One plain\nline. Omitted for typed messages, whose bubble is the prompt.\n", "example": "Fix these issues" }, "productTarget": { "description": "What the project builds; the project's own by default.", "type": "string", "enum": [ "full_stack", "mobile", "landing_page" ], "title": "ProductTarget" }, "customCode": { "type": "boolean", "default": false, "description": "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`.", "example": false }, "clientPortalSurface": { "type": "string", "enum": [ "web", "mobile" ], "description": "ClientPortal-only context captured from the selected builder surface.\nUnqualified follow-ups default to this lane; explicit web, mobile,\nor web-and-mobile wording in the prompt takes precedence.\n", "example": "web" }, "externalAgent": { "type": "boolean", "default": false, "description": "An agent outside the builder (an MCP client) writes this run's code in\nthe project's sandbox. The run skips the builder's agent: a first build\nasks the builder's intake questions (answered through the answers\nAPI), then every run checks, delivers, registers the sandbox with\nClientPortal, and seals a publishable release.\n", "example": true }, "summary": { "description": "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.", "type": "object", "required": [ "title", "outcomes" ], "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "One line naming the change.", "example": "Dark mode on every page" }, "outcomes": { "type": "array", "maxItems": 6, "items": { "type": "string", "minLength": 1, "maxLength": 300 }, "description": "What the creator gets, one change per item, in plain words.", "example": [ "A light/dark switch in the header of every page", "Dark values for the community rail and avatars" ] } }, "title": "RunChangeSummary" }, "mobilePipeline": { "type": "string", "enum": [ "v2-simple" ], "description": "Deprecated compatibility field for older mobile clients. New mobile\nruns use the standard builder flow with the React Native app kernel.\n", "example": "v2-simple" }, "mobilePipelineSpeed": { "type": "string", "enum": [ "fast", "slow" ], "default": "slow", "description": "Deprecated: accepted from older mobile clients and ignored.", "example": "fast" }, "modelId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "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`.", "example": "claude-sonnet-4-5" }, "agentId": { "type": "string", "pattern": "^agt_[A-Za-z0-9_-]+$", "description": "An agent profile the creator set up in the builder, for the builder's own agent. Not used with `externalAgent`.", "example": "agt_4c2d1e" }, "mode": { "type": "string", "enum": [ "auto", "plan", "build", "plan_first" ], "default": "auto", "description": "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`.", "example": "auto" }, "attachmentIds": { "type": "array", "maxItems": 10, "items": { "type": "string" }, "description": "Files the creator uploaded in the builder, given to the builder's own agent as context. Not used with `externalAgent`.", "example": [ "att_1a2b3c" ] }, "selectedElements": { "type": "array", "maxItems": 20, "description": "Visual edits (vibe apps): the elements the creator selected in the\nlive preview before sending. The agent receives them as a\n`` block after the prompt, so \"this\" means the\nelement on screen. Context only: file and line are hints the agent\nchecks against the workspace.\n", "items": { "type": "object", "additionalProperties": false, "required": [ "elementType" ], "example": { "elementType": "h1", "filePath": "app/design-system/atoms/Heading.vue", "lineNumber": 20, "ownerFilePath": "app/pages/courses.vue", "ownerLineNumber": 16, "textContent": "Courses", "className": "font-heading text-4xl", "attrs": { "id": "page-title" } }, "properties": { "elementType": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,39}$", "description": "Lower-case tag name of the element, e.g. `h1`.", "example": "h1" }, "filePath": { "type": "string", "maxLength": 300, "pattern": "^(?!.*(?:^|/)\\.\\.(?:/|$))[A-Za-z0-9_@.()\\[\\]+~$ -][A-Za-z0-9_@.()\\[\\]+~$ /-]*$", "description": "Where the element is written, relative to the app root (no `..` segment, not absolute; Nuxt route characters such as `[id]` and `(group)` allowed).", "example": "pages/index.vue" }, "lineNumber": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "The element's line in `filePath`.", "example": 12 }, "ownerFilePath": { "type": "string", "maxLength": 300, "pattern": "^(?!.*(?:^|/)\\.\\.(?:/|$))[A-Za-z0-9_@.()\\[\\]+~$ -][A-Za-z0-9_@.()\\[\\]+~$ /-]*$", "description": "The page that renders the design-system component this element is the root of. Same rule as `filePath`.", "example": "pages/index.vue" }, "ownerLineNumber": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "The line in `ownerFilePath`.", "example": 8 }, "textContent": { "type": "string", "maxLength": 500, "description": "The element's visible text, with emails and phone numbers redacted by the preview.", "example": "Welcome back" }, "className": { "type": "string", "maxLength": 2000, "description": "The element's CSS classes.", "example": "text-3xl font-bold" }, "attrs": { "type": "object", "maxProperties": 30, "description": "A small set of the element's HTML attributes (id, role, type, name, links without their query, aria-*…).", "propertyNames": { "pattern": "^[A-Za-z][A-Za-z0-9:_-]{0,63}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "example": { "id": "hero-title" } } }, "title": "AgentRunSelectedElement" }, "example": [ { "elementType": "h1", "filePath": "pages/index.vue", "lineNumber": 12 } ] } }, "title": "SubmitAgentRunRequest" }, "SubmitAgentRunResponse": { "type": "object", "required": [ "runId", "state" ], "properties": { "runId": { "type": "string", "pattern": "^run_[A-Za-z0-9_-]+$", "description": "The run that started.", "example": "run_8f3c2a91" }, "state": { "description": "The run as it starts.", "type": "object", "required": [ "runId", "projectId", "prompt", "status", "createdAt", "updatedAt" ], "properties": { "runId": { "type": "string", "description": "The run.", "example": "run_8f3c2a91" }, "projectId": { "type": "string", "description": "The project the run belongs to.", "example": "prj_5f0c2a3e" }, "prompt": { "type": "string", "description": "What the run was asked to build or change.", "example": "Add a page listing upcoming events" }, "displayText": { "type": "string", "description": "The creator-facing text of this run's user bubble when it differs from `prompt` (see SubmitAgentRunRequest.displayText).", "example": "Fix these issues" }, "promptAuthor": { "description": "Who sent the prompt.", "type": "object", "required": [ "id", "name" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Authenticated user id captured when the prompt was submitted.", "example": "usr_9a8b7c" }, "name": { "type": "string", "description": "Display-name snapshot captured when the prompt was submitted.", "example": "Jane Doe" }, "avatarUrl": { "type": "string", "format": "uri", "description": "Profile-image snapshot captured when the prompt was submitted.", "example": "https://images.example.com/avatars/jane.png" }, "kind": { "type": "string", "enum": [ "app" ], "description": "`app` when an app sent the prompt rather than a person: an MCP client (`name` is \"Claude\", \"Cursor\"…) or an integration.", "example": "app" } }, "title": "PromptAuthor" }, "status": { "description": "The run's status.", "type": "string", "enum": [ "queued", "running", "deploying", "ready", "failed", "cancelled", "needs_input" ], "title": "AgentRunStatus" }, "phase": { "type": "string", "description": "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`.", "enum": [ "init", "constitution", "specify", "clarify", "plan", "tasks", "analyze", "implement", "indexing", "build", "deploy", "ready", "failed" ], "example": "plan" }, "phaseStatus": { "type": "string", "description": "Phase-local status for the active Spec Kit phase.", "enum": [ "queued", "running", "awaiting_input", "terminal" ], "example": "running" }, "awaitingQuestion": { "description": "The question the run is paused on, while it waits for the creator.", "type": "object", "required": [ "capId", "question", "askedAt" ], "properties": { "capId": { "type": "string", "description": "The question's id: send it back as `capId` with the answer.", "example": "cap_portal_modules" }, "question": { "type": "string", "description": "The question to put to the creator.", "example": "Which areas should your portal have?" }, "choices": { "type": "array", "items": { "type": "string" }, "description": "The answers to offer, when it is a choice.", "example": [ "Courses", "Communities" ] }, "form": { "oneOf": [ { "type": "object", "description": "The record-fields form on `awaitingQuestion.form`. The answer `value`\nis `JSON.stringify({ fields: [{ label, type, options? }], show: [label, …] })`\n(`fields` = the NEW fields, `show` = every field clients see); as the\neditor (`edit: true`) it also carries `edits` and has `show` only when\nwhat clients see changed.\n", "required": [ "kind", "fields", "types" ], "properties": { "kind": { "type": "string", "enum": [ "record_fields" ], "description": "Always `record_fields`.", "example": "record_fields" }, "recordType": { "type": "object", "required": [ "label", "exists" ], "properties": { "label": { "type": "string", "maxLength": 60, "description": "Its name.", "example": "Policy" }, "exists": { "type": "boolean", "description": "True when the record type already exists.", "example": false } }, "description": "The record type the fields belong to." }, "existingFields": { "type": "array", "maxItems": 60, "items": { "type": "object", "required": [ "label", "type" ], "properties": { "label": { "type": "string", "description": "The field's name.", "example": "Policy number" }, "type": { "type": "string", "description": "The field's type.", "example": "TEXT" }, "options": { "type": "array", "items": { "type": "string" }, "description": "The choices, for a choice field.", "example": [ "Active", "Lapsed" ] }, "shown": { "type": "boolean", "description": "Clients see this field.", "example": true }, "namesRecords": { "type": "boolean", "description": "This field names each record.", "example": true } } }, "description": "The record type's fields today.", "example": [ { "label": "Policy number", "type": "TEXT", "shown": true } ] }, "fields": { "type": "array", "maxItems": 30, "items": { "type": "object", "required": [ "label", "type" ], "properties": { "label": { "type": "string", "maxLength": 60, "description": "The field's name.", "example": "Renewal date" }, "type": { "type": "string", "description": "The field's type.", "example": "DATE" }, "options": { "type": "array", "maxItems": 50, "items": { "type": "string" }, "description": "The choices, for a choice field.", "example": [ "Monthly", "Yearly" ] } } }, "description": "The new fields proposed.", "example": [ { "label": "Renewal date", "type": "DATE" } ] }, "edit": { "type": "boolean", "enum": [ true ], "description": "Set when this is the editor for an existing record type.", "example": true }, "types": { "type": "array", "description": "The field types the dropdown offers (server-owned).", "items": { "type": "object", "required": [ "value", "label" ], "properties": { "value": { "type": "string", "description": "The type, as an answer sends it.", "example": "TEXT" }, "label": { "type": "string", "description": "What the creator sees.", "example": "Single line" }, "withOptions": { "type": "boolean", "enum": [ true ], "description": "This type takes a list of choices.", "example": true }, "noConvert": { "type": "boolean", "enum": [ true ], "description": "An existing field cannot be changed to this type.", "example": true } } }, "example": [ { "value": "TEXT", "label": "Single line" } ] } }, "title": "RecordQuestionForm" }, { "type": "object", "description": "The media a request needs, on `awaitingQuestion.form`: one slot each,\npicked from the creator's GHL Media Library, pasted as a link, or\n(images only) generated. The answer `value` is\n`JSON.stringify({ \"\": [{ url, name, source }] | \"generate\" | [] })`\n(`source` is `library` or `link`; `[]` = skipped).\n", "required": [ "kind", "slots" ], "properties": { "kind": { "type": "string", "enum": [ "media" ], "description": "Always `media`.", "example": "media" }, "slots": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "required": [ "key", "label", "max", "accepts" ], "properties": { "key": { "type": "string", "description": "The slot's key in the answer.", "example": "hero" }, "label": { "type": "string", "description": "What to ask for.", "example": "Hero image" }, "purpose": { "type": "string", "description": "Where it will be used.", "example": "Top of the home page" }, "max": { "type": "integer", "minimum": 1, "maximum": 10, "description": "How many files the slot takes.", "example": 1 }, "accepts": { "type": "string", "enum": [ "image", "video", "file" ], "description": "The kind of media.", "example": "image" } } }, "description": "The media to collect, one slot each.", "example": [ { "key": "hero", "label": "Hero image", "max": 1, "accepts": "image" } ] } }, "title": "MediaQuestionForm" } ], "description": "Set when the answer is a form (record fields or media) rather than a choice; its `kind` says which." }, "details": { "type": "string", "description": "What the creator is agreeing to, shown under the question.", "example": "Your portal will use the Courses and Communities modules." }, "preview": { "type": "object", "additionalProperties": true, "description": "What the builder shows the creator beside this question. Display only: its shape follows the builder's screens and may change.", "example": {} }, "multiSelect": { "type": "boolean", "description": "Several choices may be picked.", "example": false }, "allowOther": { "type": "boolean", "description": "Adds a \"Something else\" choice that opens a box.", "example": true }, "input": { "type": "string", "enum": [ "short_text", "long_text" ], "description": "With no choices, one line or a paragraph.", "example": "short_text" }, "placeholder": { "type": "string", "description": "Hint text for a typed answer.", "example": "e.g. Weekly yoga classes" }, "askedAt": { "type": "string", "format": "date-time", "description": "When the run asked.", "example": "2026-10-15T09:32:00.000Z" } }, "title": "AgentRunAwaitingQuestion" }, "pendingQuestions": { "type": "array", "description": "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`.", "example": [ { "capId": "clarify.cp.name", "displayName": "Planning question", "text": "What should we call it?", "options": [], "freeText": true, "group": "app", "control": "text" } ], "items": { "type": "object", "required": [ "capId", "text", "options" ], "properties": { "capId": { "type": "string", "description": "The question's id: send it back as `capId` with its answer.", "example": "clarify.cp.name" }, "displayName": { "type": "string", "description": "What kind of question it is.", "example": "Planning question" }, "text": { "type": "string", "description": "The question.", "example": "What should we call it?" }, "options": { "type": "array", "description": "The answers to pick from; empty when `freeText` asks for a typed answer.", "example": [ { "value": "slate", "label": "Slate" } ], "items": { "type": "object", "required": [ "value", "label" ], "additionalProperties": true, "properties": { "value": { "type": "string", "description": "What to send back when this option is picked.", "example": "slate" }, "label": { "type": "string", "description": "The option as the creator reads it.", "example": "Slate" }, "hint": { "type": "string", "description": "A second line under the label.", "example": "Calm and neutral" }, "selected": { "type": "boolean", "description": "Picked unless the creator unpicks it.", "example": false }, "freeText": { "type": "boolean", "description": "Picking it means typing the answer instead.", "example": false }, "swatches": { "type": "array", "items": { "type": "string" }, "description": "A palette's colours, lightest to darkest.", "example": [ "#364152", "#697586" ] }, "brand": { "type": "string", "description": "The colour a palette leads with.", "example": "#364152" }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "The platforms the option exists on, when not all.", "example": [ "mobile" ] } } } }, "multiSelect": { "type": "boolean", "description": "Several options may be picked.", "example": false }, "freeText": { "type": "boolean", "description": "No options: the answer is typed.", "example": true }, "placeholder": { "type": "string", "description": "Hint text for a typed answer.", "example": "e.g. Forge Fitness" }, "helper": { "type": "string", "description": "A supporting line under the question.", "example": "The name your customers see when they sign in." }, "group": { "type": "string", "description": "The page of the intake form it belongs to.", "example": "app" }, "control": { "type": "string", "description": "How the builder draws it: cards, swatches, fonts, text and so on.", "example": "text" }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "The platforms the question exists on, when not all.", "example": [ "mobile" ] } }, "title": "AgentRunPendingQuestion" } }, "publicPhaseState": { "description": "Where the run is, in the words the builder shows the creator.", "type": "object", "required": [ "phase", "phaseStatus" ], "properties": { "phase": { "type": "string", "description": "The step the run is on.", "example": "clarifying" }, "phaseStatus": { "type": "string", "enum": [ "queued", "running", "awaiting_input", "terminal" ], "description": "Where that step is.", "example": "awaiting_input" }, "message": { "type": "string", "description": "The step in one sentence for the creator.", "example": "Answer the planning question to continue." }, "phaseIndex": { "type": "integer", "description": "The step's position, from 0.", "example": 2 }, "phaseTotal": { "type": "integer", "description": "How many steps the run has.", "example": 6 }, "ts": { "type": "string", "format": "date-time", "description": "When the run reached this state.", "example": "2026-10-23T12:57:27.435Z" } }, "title": "AgentRunPhaseState" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the run was created.", "example": "2026-10-15T09:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the run last changed.", "example": "2026-10-15T09:41:12.000Z" }, "checkProblems": { "type": "array", "items": { "type": "string" }, "description": "Problems the check found in a build written by an outside agent (`externalAgent: true`)\nthat still built and deployed. Fix them with another set of edits and run.\n", "example": [ "pages/learn.vue: 'courses' is possibly undefined" ] }, "previewUrl": { "type": "string", "format": "uri", "description": "Convenience field equal to `preview.primaryUrl`. Kept for\nsingle-service callers; multi-service callers should read\n`preview.services[]` for per-service URLs. This is the\ndurable customer-facing preview URL produced after a\nsuccessful build/deploy, not the live sandbox edit URL.\n", "example": "https://preview.example.com/my-portal" }, "preview": { "description": "Where to see what the run built.", "type": "object", "required": [ "primaryUrl", "services" ], "properties": { "primaryUrl": { "type": "string", "format": "uri", "description": "The URL the user opens — for multi-service web stacks, this is the primary (frontend) URL.", "example": "https://preview.example.com/my-portal" }, "services": { "type": "array", "items": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": "string", "description": "Service name as declared in the stack manifest.", "example": "web" }, "url": { "type": "string", "format": "uri", "description": "Where the service is served.", "example": "https://preview.example.com/my-portal" }, "imageUri": { "type": "string", "description": "The service's image.", "example": "registry.example.com/apps/web:run_8f3c2a91" }, "digest": { "type": "string", "description": "The image's digest.", "example": "sha256:3b1f0c9e2d7a" } }, "title": "ProvisionedService" }, "description": "Each service of the app and where it is served.", "example": [ { "name": "web", "url": "https://preview.example.com/my-portal" } ] } }, "title": "RunPreview" }, "livePreviewUrl": { "type": "string", "format": "uri", "deprecated": true, "description": "**Deprecated 2026-05-17. Will be removed 2026-11-17.**\nUse `sandboxUrl` instead — same value, accurate name.\n\nMisleadingly named: this is the SANDBOX URL (the agent's\nHMR/edit workshop), not the customer-facing preview. The\ncustomer preview lives at `previewUrl`. Co-populated with\n`sandboxUrl` for the deprecation window; readers should\nmigrate to `sandboxUrl`.\n", "example": "https://sbx-prj-5f0c2a3e.example.com" }, "livePreviewStatus": { "type": "string", "enum": [ "starting", "ready", "failed", "stopped" ], "deprecated": true, "description": "**Deprecated 2026-05-17. Will be removed 2026-11-17.**\nUse `sandboxStatus` instead.\n", "example": "ready" }, "sandboxUrl": { "type": "string", "format": "uri", "description": "URL of the project sandbox runtime.\nThis is the agent's compile + HMR workshop — NOT the\ncustomer-facing preview. The customer preview is at\n`previewUrl`, which surfaces in the builder UI's right\npane after the deploy gate succeeds.\n", "example": "https://sbx-prj-5f0c2a3e.example.com" }, "sandboxStatus": { "type": "string", "enum": [ "starting", "ready", "failed", "stopped" ], "description": "Current state of the sandbox dev server.", "example": "ready" }, "publishedUrl": { "type": "string", "format": "uri", "description": "URL of the production (\"Published\") runtime service for this project.\nPopulated when the project has\nbeen explicitly published at least once. Distinct from\n`previewUrl`/`preview.primaryUrl`, which always point at the\ndurable customer preview service that auto-updates on every\nsuccessful agent run. Absent for projects that have never\nbeen published — the FE renders \"Not published\" in that case.\n", "example": "https://my-portal.example.com" }, "publishedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the most recent publish, snapshotted\nonto the run at the moment it reached `ready`. Used by the\nFE to render staleness like \"Last published 5 hours ago\".\n", "example": "2026-10-14T18:02:00.000Z" }, "runsSinceLastPublish": { "type": "integer", "minimum": 0, "description": "Number of successful (status=ready) runs completed since\nthe project was last published. Reset to 0 by `publish`.\nSnapshotted onto each ready run so the FE can render a\nstaleness indicator without an extra round-trip. Absent\nfor projects that have never been published.\n", "example": 2 }, "summary": { "type": "string", "description": "AI-generated 1-line checkpoint description, snapshotted onto\nthe run record at `setStatus(\"ready\")` time. Sourced from\nthe agent's `completion` narrator event when present,\notherwise falls back to a deterministic prompt-derived\nstub. Read by Timeline + chat UI so users see \"what\nchanged in this checkpoint\" at a glance. Absent on\nnon-terminal or legacy runs.\n", "example": "Added an events page" }, "imageUri": { "type": "string", "description": "Deprecated: no longer returned. It named the builder's own image registry.", "example": "registry.example.com/apps/web:run_8f3c2a91", "deprecated": true }, "imageDigest": { "type": "string", "description": "Deprecated: no longer returned. It named the builder's own image.", "example": "sha256:3b1f0c9e2d7a", "deprecated": true }, "failureMessage": { "type": "string", "description": "Why the run failed, in one line.", "example": "The build failed: pages/events.vue has a type error" }, "failure": { "type": "object", "description": "Structured failure taxonomy for a terminated run. Set in\ntandem with `failureMessage` (which is the human-readable\nderivation). Discriminated by `category`; consumers should\nbranch on `category` + `code` to render an actionable hint\ninstead of a generic \"Internal error\".\n", "required": [ "category", "code", "retryable", "responsibleModule" ], "properties": { "category": { "type": "string", "enum": [ "user_input", "config", "model", "build", "infra", "spec_kit", "transport", "runtime", "internal" ], "description": "What kind of failure it was.", "example": "build" }, "code": { "type": "string", "description": "Category-specific failure code. See the run-runtime\n`RunFailure` discriminated union for the per-category\ncode enum.\n", "example": "build_failed" }, "retryable": { "type": "boolean", "description": "Sending the same request again may succeed.", "example": false }, "responsibleModule": { "type": "string", "enum": [ "runtime", "dispatcher", "planner", "classifier", "spec_kit", "designer", "scaffolder", "builder", "verifier", "deployer", "infra", "model_provider", "transport", "unknown" ], "description": "The part of the builder that failed.", "example": "runtime" }, "userMessage": { "type": "string", "description": "For `category=user_input` — text safe to show the user verbatim.", "example": "Describe the page you want in a sentence or two." }, "details": { "type": "string", "description": "For `category=config` / `spec_kit` — operator-facing detail.", "example": "No stack manifest for this template" }, "provider": { "type": "string", "description": "For `category=model` — provider identifier (e.g. anthropic, openai).", "example": "anthropic" }, "attempt": { "type": "integer", "description": "For `category=model` — retry attempt index that ultimately gave up.", "example": 3 }, "failureHead": { "type": "string", "description": "For `category=build` — first chunk of compiler/test stderr.", "example": "pages/events.vue(12,5): error TS2339" }, "failureTail": { "type": "string", "description": "For `category=build` — last chunk of compiler/test stderr.", "example": "Found 1 error." }, "cause": { "type": "string", "description": "For `category=infra` — short cause description.", "example": "The sandbox did not become ready in time" }, "phase": { "type": "string", "description": "For `category=spec_kit` — phase id where the orchestrator halted.", "example": "plan" }, "stack": { "type": "string", "description": "For `category=internal` — first lines of the stack trace. Never sent to a sub-account token.", "example": "TypeError: Cannot read properties of undefined" }, "message": { "type": "string", "description": "For `category=runtime` — text safe to show the user verbatim.", "example": "The preview could not start." } } }, "metadata": { "type": "object", "additionalProperties": true, "description": "Deprecated: no longer returned. It held the builder's own debugging state.", "properties": { "generationFailure": { "type": "object", "additionalProperties": true, "properties": { "code": { "type": "string", "enum": [ "provider_transient", "dispatch_failed", "scaffold_failed", "infra_failed", "agent_failed", "build_failed", "deploy_failed", "run_stalled", "pipeline_failed" ], "description": "The failure code.", "example": "provider_transient" }, "retryable": { "type": "boolean", "description": "Retrying may succeed.", "example": true }, "source": { "type": "string", "enum": [ "provider", "dispatch", "planning", "scaffold", "infra", "agent", "build", "deploy", "pipeline" ], "description": "Where it failed.", "example": "provider" }, "detail": { "type": "string", "description": "Detail for support.", "example": "The model provider was overloaded" } }, "description": "Why generating the app failed, when it did." }, "failedWorkspace": { "type": "object", "additionalProperties": true, "properties": { "preservedAt": { "type": "string", "format": "date-time", "description": "When it was kept.", "example": "2026-10-15T09:45:00.000Z" }, "uploadedFiles": { "type": "integer", "description": "How many files were kept.", "example": 128 }, "durationMs": { "type": "integer", "description": "How long keeping it took, in milliseconds.", "example": 2140 } }, "description": "The workspace kept from a failed run, for diagnosis." } }, "deprecated": true } }, "title": "RunRecord" } }, "title": "SubmitAgentRunResponse" }, "ApiError": { "type": "object", "required": [ "type", "title", "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri", "example": "about:blank", "description": "A URI identifying the kind of error." }, "title": { "type": "string", "example": "Request validation failed", "description": "Short summary of the kind of error." }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "example": 422, "description": "The HTTP status code." }, "detail": { "type": "string", "example": "One or more fields are invalid.", "description": "What went wrong with this request." }, "instance": { "type": "string", "example": "/api/v1/runs", "description": "The request path that failed." }, "code": { "type": "string", "example": "validation_error", "description": "Stable, machine-readable error code." }, "requestId": { "type": "string", "example": "req_01HXQ8Z6J9K2", "description": "The request's id, for support." }, "fieldErrors": { "type": "array", "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string", "example": "prompt", "description": "The invalid field, as a dotted path." }, "code": { "type": "string", "example": "required", "description": "Machine-readable reason." }, "message": { "type": "string", "example": "Prompt is required.", "description": "Human-readable reason." } }, "title": "FieldError" }, "description": "One entry per invalid field, when the request body was invalid.", "example": [ { "field": "name", "code": "too_long", "message": "name must be at most 120 characters" } ] } }, "title": "ApiError" } } } } ``` ## Code Examples **cURL** ```bash curl -L -X POST 'https://services.leadconnectorhq.com/ai-builder-api/projects//runs' \ -H 'Authorization: Bearer ' \ -H 'Version: v3' \ -H 'Content-Type: application/json' \ --data-raw '{ "prompt": "Add a page listing upcoming events", "displayText": "Fix these issues", "customCode": false, "clientPortalSurface": "web", "externalAgent": true, "summary": { "title": "Dark mode on every page", "outcomes": [ "A light/dark switch in the header of every page", "Dark values for the community rail and avatars" ] }, "mobilePipeline": "v2-simple", "mobilePipelineSpeed": "fast", "modelId": "claude-sonnet-4-5", "agentId": "agt_4c2d1e", "mode": "auto", "attachmentIds": [ "att_1a2b3c" ], "selectedElements": [ { "elementType": "h1", "filePath": "pages/index.vue", "lineNumber": 12 } ] }' ``` **Node.js** ```javascript const options = { method: 'POST', headers: { Authorization: 'Bearer ', Version: 'v3', 'Content-Type': 'application/json' }, body: JSON.stringify({ "prompt": "Add a page listing upcoming events", "displayText": "Fix these issues", "customCode": false, "clientPortalSurface": "web", "externalAgent": true, "summary": { "title": "Dark mode on every page", "outcomes": [ "A light/dark switch in the header of every page", "Dark values for the community rail and avatars" ] }, "mobilePipeline": "v2-simple", "mobilePipelineSpeed": "fast", "modelId": "claude-sonnet-4-5", "agentId": "agt_4c2d1e", "mode": "auto", "attachmentIds": [ "att_1a2b3c" ], "selectedElements": [ { "elementType": "h1", "filePath": "pages/index.vue", "lineNumber": 12 } ] }) }; try { const response = await fetch('https://services.leadconnectorhq.com/ai-builder-api/projects//runs', options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **Python** ```python import requests url = "https://services.leadconnectorhq.com/ai-builder-api/projects/{projectId}/runs" headers = { "Authorization": "Bearer ", "Version": "v3" } payload = { "prompt": "Add a page listing upcoming events", "displayText": "Fix these issues", "customCode": false, "clientPortalSurface": "web", "externalAgent": true, "summary": { "title": "Dark mode on every page", "outcomes": [ "A light/dark switch in the header of every page", "Dark values for the community rail and avatars" ] }, "mobilePipeline": "v2-simple", "mobilePipelineSpeed": "fast", "modelId": "claude-sonnet-4-5", "agentId": "agt_4c2d1e", "mode": "auto", "attachmentIds": [ "att_1a2b3c" ], "selectedElements": [ { "elementType": "h1", "filePath": "pages/index.vue", "lineNumber": 12 } ] } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` **PHP** ```php 'https://services.leadconnectorhq.com/ai-builder-api/projects//runs', CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ', 'Version: v3', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => '{ "prompt": "Add a page listing upcoming events", "displayText": "Fix these issues", "customCode": false, "clientPortalSurface": "web", "externalAgent": true, "summary": { "title": "Dark mode on every page", "outcomes": [ "A light/dark switch in the header of every page", "Dark values for the community rail and avatars" ] }, "mobilePipeline": "v2-simple", "mobilePipelineSpeed": "fast", "modelId": "claude-sonnet-4-5", "agentId": "agt_4c2d1e", "mode": "auto", "attachmentIds": [ "att_1a2b3c" ], "selectedElements": [ { "elementType": "h1", "filePath": "pages/index.vue", "lineNumber": 12 } ] }', ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` **Java** ```java HttpResponse response = Unirest .post("https://services.leadconnectorhq.com/ai-builder-api/projects//runs") .header("Authorization", "Bearer ") .header("Version", "v3") .header("Content-Type", "application/json") .body("{\"prompt\":\"Add a page listing upcoming events\",\"displayText\":\"Fix these issues\",\"customCode\":false,\"clientPortalSurface\":\"web\",\"externalAgent\":true,\"summary\":{\"title\":\"Dark mode on every page\",\"outcomes\":[\"A light/dark switch in the header of every page\",\"Dark values for the community rail and avatars\"]},\"mobilePipeline\":\"v2-simple\",\"mobilePipelineSpeed\":\"fast\",\"modelId\":\"claude-sonnet-4-5\",\"agentId\":\"agt_4c2d1e\",\"mode\":\"auto\",\"attachmentIds\":[\"att_1a2b3c\"],\"selectedElements\":[{\"elementType\":\"h1\",\"filePath\":\"pages/index.vue\",\"lineNumber\":12}]}") .asString(); ``` **Go** ```go package main import ( "fmt" "net/http" "io" "strings" ) func main() { url := "https://services.leadconnectorhq.com/ai-builder-api/projects//runs" payload := strings.NewReader(`{ "prompt": "Add a page listing upcoming events", "displayText": "Fix these issues", "customCode": false, "clientPortalSurface": "web", "externalAgent": true, "summary": { "title": "Dark mode on every page", "outcomes": [ "A light/dark switch in the header of every page", "Dark values for the community rail and avatars" ] }, "mobilePipeline": "v2-simple", "mobilePipelineSpeed": "fast", "modelId": "claude-sonnet-4-5", "agentId": "agt_4c2d1e", "mode": "auto", "attachmentIds": [ "att_1a2b3c" ], "selectedElements": [ { "elementType": "h1", "filePath": "pages/index.vue", "lineNumber": 12 } ] }`) req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Version", "v3") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(string(body)) } ``` **Ruby** ```ruby require 'uri' require 'net/http' url = URI("https://services.leadconnectorhq.com/ai-builder-api/projects//runs") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = "Bearer " request["Version"] = "v3" request["Content-Type"] = "application/json" request.body = '{ "prompt": "Add a page listing upcoming events", "displayText": "Fix these issues", "customCode": false, "clientPortalSurface": "web", "externalAgent": true, "summary": { "title": "Dark mode on every page", "outcomes": [ "A light/dark switch in the header of every page", "Dark values for the community rail and avatars" ] }, "mobilePipeline": "v2-simple", "mobilePipelineSpeed": "fast", "modelId": "claude-sonnet-4-5", "agentId": "agt_4c2d1e", "mode": "auto", "attachmentIds": [ "att_1a2b3c" ], "selectedElements": [ { "elementType": "h1", "filePath": "pages/index.vue", "lineNumber": 12 } ] }' response = http.request(request) puts response.read_body ``` **PowerShell** ```powershell $headers = @{ "Authorization" = "Bearer " "Version" = "v3" } $body = '{ "prompt": "Add a page listing upcoming events", "displayText": "Fix these issues", "customCode": false, "clientPortalSurface": "web", "externalAgent": true, "summary": { "title": "Dark mode on every page", "outcomes": [ "A light/dark switch in the header of every page", "Dark values for the community rail and avatars" ] }, "mobilePipeline": "v2-simple", "mobilePipelineSpeed": "fast", "modelId": "claude-sonnet-4-5", "agentId": "agt_4c2d1e", "mode": "auto", "attachmentIds": [ "att_1a2b3c" ], "selectedElements": [ { "elementType": "h1", "filePath": "pages/index.vue", "lineNumber": 12 } ] }' $response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/ai-builder-api/projects//runs' -Method 'POST' -Headers $headers -Body $body -ContentType 'application/json' $response | ConvertTo-Json ```