Client App BuilderVersion: v3

Create a project.

POST/ai-builder-api/projects

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.

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

Makes the request safe to retry: a repeat with the same key returns the first result.

Possible values: <= 200 characters

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

Versionstringrequired

The API version.

Available optionsv3

Example:v3

Body

application/json

promptstringrequired

What the app should do.

Possible values: non-empty and <= 20000 characters

Example:Build a mobile and web booking app for a med spa.

namestring

The app's name, shown to members.

Possible values: non-empty and <= 120 characters

Example:Groundbreak

targetModesTargetMode[]deprecated

Legacy hint retained for compatibility. Use productTarget from the landing composer instead: full_stack, landing_page, or mobile.

Available optionswebmobile

Possible values: >= 1

Example:["web"]

stackTemplateStackTemplate

The kernel to build on; leave it out to let the service choose.

Available optionsreact_native_app_kernel_v1nuxt_clientportal_app_v1nuxt_clientportal_vibe_v1auto

templateIdstring

Starter-template id (e.g. events-v1) to instantiate the project from. When set, the first build run scaffolds the kernel and byte-copies the finished starter overlay (instantiate mode — no plan/design/codegen). Omit to build from the bare prompt.

Example:events-v1

mobileCreationobject

For a mobile app: start from scratch or from the CP Base App.

appModeAppMode

App branding mode. cp_branded builds a Client Portal branded app wired to the location's courses/communities/purchases/affiliates. Defaults to standard.

Available optionsstandardcp_branded

productTargetProductTarget

Creator-selected landing composer category. full_stack means responsive web app plus backend/database; mobile means native Expo/React Native app.

Available optionsfull_stackmobilelanding_page

hostingModeHostingMode

Where to host the app; managed by default.

Available optionsmanagedbyo_vercel

clientRefIdstring<uuid>

Your own reference for this create.

Example:3f6c1d2e-8b4a-4f7e-9c1d-2a3b4c5d6e7f

Response

application/json

Project created.

idstringrequired

The project's id.

Example:prj_01HXQ8Z6J9K2

namestringrequired

The app's name, shown to members.

Example:Client Booking Portal

locationIdstringrequired

The sub-account the project belongs to.

Example:loc_01HXQ8Z6J9K2

companyIdstringrequired

The agency the sub-account belongs to.

Example:cmp_01HXQ8Z6J9K2

ownerUserIdstringrequired

The user who owns the project.

Example:usr_01HXQ8Z6J9K2

createdByUserIdstringrequired

The user who created the project.

Example:usr_01HXQ8Z6J9K2

visibilityProjectVisibilityrequired

Who in the sub-account can see the project.

Available optionsprivateshared

slugstring

URL-safe form of the name.

Example:client-booking-portal

statusProjectStatusrequired

Where the project is in its lifecycle: draft (in use), archived or deleted. A build's progress is its run's (latestRunId, then GET .../runs/{runId}), and whether the app is live is publicationStatus. The other values are no longer reported.

Available optionsdraftqueuedplanningbuildingpreviewingdeployingdeployedblockedarchiveddeleted

publicationStatusProjectPublicationStatus

Stable publication state, independent from the mutable run/build status. published means a successful publish activated at least the managed platform hostname; later draft edits do not change it. Legacy records without this field are interpreted as draft unless productionUrl is present.

Available optionsdraftpublished

stackTemplateStackTemplaterequired

The kernel the project is built on.

Available optionsreact_native_app_kernel_v1nuxt_clientportal_app_v1nuxt_clientportal_vibe_v1auto

templateIdstring

Starter-template id (e.g. events-v1) the project was instantiated from. Drives the scaffold overlay byte-copy and, on the first build run, the instantiate workflow mode (scaffold + finished overlay, no codegen). Absent for projects built from a bare prompt. Project-scoped — set at creation, never accepted on the run submit body.

Example:events-v1

mobileCreationobject

How a mobile project started: from scratch or from the CP Base App.

appModeAppMode

App branding mode persisted at project creation. cp_branded connects the app to the location's Client Portal modules.

Available optionsstandardcp_branded

productTargetProductTargetrequired

What the project builds.

Available optionsfull_stackmobilelanding_page

targetModesTargetMode[]required

Immutable surfaces owned by the project. New projects contain exactly one value derived by the server from productTarget: full-stack and landing-page projects resolve to web; native Expo/React Native projects resolve to mobile. Existing combined Client Portal projects may contain both values.

Available optionswebmobile

Example:["web"]

dataPlaneModeDataPlaneModerequired

Where the app's data lives.

Available optionsmanaged_mongo

hostingModeHostingModerequired

Where the app is hosted.

Available optionsmanagedbyo_vercel

apiContractVersionstring

The API contract version the project was created under.

Example:2026-04-27

latestRunIdstring

The project's most recent run.

Example:run_01HXQ9ABCD12

latestDeploymentIdstring

The project's most recent deployment.

Example:dep_01HXQ8Z6J9K2

previewUrlstring<uri>

Where to preview the latest build.

Example:https://preview.example.com/my-portal

productionUrlstring<uri>

Where the published app is served.

Example:https://my-portal.example.com

thumbnailUrlstring<uri>

Screenshot of the app's home page, taken after its latest successful build. Absent until a build has produced one; clients show their own placeholder then.

Example:

https://storage.googleapis.com/ai-builder-public-experiences-staging/project-thumbnails/5f0c2a3e-8d41-4c4b-9a35-0d1e6b7f2c91.jpg

preferredModestring

The user's last-selected run mode for this project. The composer's 3-way segmented control rehydrates from this value when the project is opened so the user's preference survives reloads. Updated server-side every time a new run is submitted with an explicit mode value (or via PATCH /projects/{projectId}).

Available optionsautoplanbuild

Example:auto

createdAtstring<date-time>required

When the project was created.

Example:2026-10-01T08:00:00.000Z

updatedAtstring<date-time>required

When the project last changed.

Example:2026-10-15T09:41:12.000Z

archivedAtstring<date-time>

When the project was archived, if it was.

Example:2026-10-20T12:00:00.000Z

starredboolean

Pinned by its owner so it sorts to the top of their project list. Absent means not starred; there is no per-viewer state — a project is starred for the location, like its name.

Example:true

hasMobileSourcesboolean

True when this project's current mobile revision carries generated source (documents.clientportal.mobile.sources on its app configuration), so its phone preview must be framed from the project's own sandbox rather than the shared stock host. Read from the authenticated location's revision only. Returned by GET /api/v1/projects/{projectId}; list, create and update responses omit it, and an absent value means false.

Example:false

etagstringrequired

The project's version tag, for conditional updates.

Example:W/"project-12"