Client App BuilderVersion: v3

Get a project by id.

GET/ai-builder-api/projects/{projectId}

Returns one app: its status, publication state, preview and production URLs, and its latest run.

Authorizations

Authorizationstringheaderrequired

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

Scope:clientportal-ai.readonly

Auth methods:OAuthPrivate Integration

Token type:Sub-Account Token

Request

Headers

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

Response

application/json

Project.

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"