Client App Builder
Apps built with Client App Builder: projects, builds, changes and code
List projects in the caller's location.
Lists the ClientPortal apps in the sub-account, most recently active first. A sub-account token sees every app by default; `view=mine` limits the list to apps the caller created.
Create a project.
Creates an app in the sub-account. Then start its first build with `POST .../agent-runs`; a sub-account token sends `externalAgent: true` because its own agent writes the code.
Get a project by id.
Returns one app: its status, publication state, preview and production URLs, and its latest run.
Rename an app, archive it, or pin it to the top of the app list.
Renames the app, archives it or brings it back, or pins it to the top of the app list. Send only the fields to change.
Submit a prompt; the agent runs in the background.
Returns `runId` at once; the run goes on in the background. An agent outside the builder (an
List an app's runs, newest first.
Returns the project's runs ordered newest-first by `createdAt`. The
Get the current state of a run (poll-friendly).
Strictly tenant- and project-scoped. A run that exists under a
Answer every question of one form in a single write.
Records up to 12 answers in one run write and resumes the run once,
JSON Schema and an example for each change kind.
Static per server release: what `change` must look like for each kind
Check a change of one kind and sign a plan for it, without writing anything.
The caller's AI writes a `change` of one `kind`; the server validates it
Apply a signed plan once.
Idempotent on `planId`: a second (or concurrent) apply of the same plan
Read an app's stack and open its sandbox for editing.
Returns the app's stack, which decides how its code is written, and its kernel bundle, and opens the app's sandbox: read and edit it once `sandbox.status` is `ready`. A `react_native_app_kernel_v1` app is a phone app: its screens are files under `apps/mobile/app-extensions/`, registered with `POST .../sandbox/extension-routes`. Every other stack is a web portal.
Write, patch or delete one file in the app's sandbox.
Writes, patches or deletes one file in the app's sandbox. A small change to a text file is a `patch`: exact replacements, without resending the file. After a set of edits, save them with `POST .../sandbox/checkpoint`, then start a run with `externalAgent: true` to check, build and deploy them. A React Native app (`react_native_app_kernel_v1`) writes only under `apps/mobile/app-extensions/` and `apps/mobile/application-assets/`; its `routes.ts` is generated, so register its screens with `POST .../sandbox/extension-routes` instead of writing that file.
Register, rename or remove a React Native app's screens.
Changes the screen list of a React Native app (`react_native_app_kernel_v1`) once its screen files are written with `POST .../sandbox/edit`: `app-extensions/routes.ts` is generated from these changes, never written as text. Send several changes as one `batch`: all of them apply or none does, and a resent batch that is already in effect changes nothing (a repeated single `add` is refused as `duplicate_id`). The run started next with `externalAgent: true` checks the screens, saves them as a mobile revision and deploys the preview.
Read a file in the app's sandbox, or list a folder.
Reads one file of the app's code, or lists a folder's files and subfolders, so an agent sees what is there before it edits. A folder path always lists. The kernel's own files are readable; the writable boundary applies only to `POST .../sandbox/edit`.
Search the app's code for literal text.
Finds where text appears in the app's source files (ts, tsx, js, jsx, vue, json, md, css), with dependencies and build output left out. The text is matched literally, not as a pattern. Read the files it finds with `POST .../sandbox/view`.
Save the app's sandbox files as the point it restarts from.
Saves the sandbox's files so a sandbox that restarts comes back with them. Call it after a set of `POST .../sandbox/edit` calls and before starting the run that builds them: a sandbox that restarts in between otherwise comes back with the files as they were at the last save.
List the custom domains attached to a project.
Lists the app's custom domains with their setup status and the DNS records to add. A domain is attached with `changes` kind `domain`; once it is `active` it serves the live site.
List the app templates a project can be created from.
The template catalog powers the template picker on the landing page:
Check whether an app can be published now, and which build would go live.
Computed by the same resolver as promote-to-production. Without
Publish an app to its live site.
Publishes the app to its live site: its managed address, and every custom domain attached to it (`changes` kind `domain`) once that domain is `active`. A domain that becomes active later joins the live site without another publish. Check `GET .../publishability` first and send the `sourceRunId` it returns, so the build the creator approved is the one that goes live. Returns a publish job: poll `GET .../infra/publish-jobs/{publishJobId}` until `status` is `succeeded` (`publishedUrl` is the live site) or `failed` (`error` says why). Send the same `idempotencyKey` to retry safely.
Read a publish job's progress.
Reports a publish job's progress. Poll it every few seconds until `status` is `succeeded`, when `publishedUrl` is the live site, or `failed`, when `error` says why.
Get which revision of an app is newest, applied and published.
A phone app saves a revision at the end of each run. Publish it with `POST .../app-config/publish` once `appliedRevision` equals `revision` and `status` is `ready`.
Create a preview link token for a phone app.
A short-lived token that makes the app's preview show this app. Open `sandbox.devUrl` from `GET .../cli/projects/{projectId}/context` with `#previewToken=<token>` appended; without it the preview shows the stock app.
Publish a saved revision of an app to its members.
For a phone app send `platform: mobile` and the `revision` from `GET .../app-config`: installed apps get it over the air. Screens your agent wrote reach members only in a new APK (`POST .../app-config/apk-builds`). `web`, the default, is for ClientPortal configuration apps; a coded web app publishes with `POST .../infra/promote-to-production`.
Build a signed Android APK of a published phone app revision.
Idempotent per Idempotency-Key. For a project whose current revision carries generated screens, the build is instead identified by the revision and the generated sources it carries (sha256(locationId:projectId:revision:sourcesSha)): repeating the request for the same revision and sources returns the same build whatever the key, and a failed one is queued again. Such a build is made from the React Native kernel commit the screens were generated against, and must be requested for the current revision. Generated screens reach members only through a new APK; they are never delivered over the air. At most one build may be active per project; sibling projects in the same location may build in parallel. Deleting a project while its build is still queued or building fails that build. A project compiles one signed APK for now: after a successful build the binary is final. A project without generated screens keeps reaching installed apps by publishing a revision; a project with generated screens cannot build another APK yet. Failed builds do not consume the allowance.
Get an APK build's status and download link.
Read it again until `status` is `finished`, when `artifactUrl` is a short-lived download link, or `failed`, when `error` says why.
List a phone app's saved revisions.
Up to 50, newest first, marking the current one and the one members get. Return to one with `POST .../app-config/revisions/{revision}/restore`.
Return a phone app to an earlier revision.
Saves a copy of the earlier revision, screens included, as the newest one. Members get it once you publish it with `POST .../app-config/publish`.