Skip to main content
Version: 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.

Request​

Idempotency-Key string

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

Possible values: <= 200 characters

Version stringrequired

The API version.

Available optionsv3
application/json

Bodyrequired

    promptstringrequired

    What the app should do.

    Possible values: non-empty and <= 20000 characters

    namestring

    The app's name, shown to members.

    Possible values: non-empty and <= 120 characters

    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

    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.

    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.

application/json

Project created.

Schema
    idstringrequired

    The project's id.

    namestringrequired

    The app's name, shown to members.

    locationIdstringrequired

    The sub-account the project belongs to.

    companyIdstringrequired

    The agency the sub-account belongs to.

    ownerUserIdstringrequired

    The user who owns the project.

    createdByUserIdstringrequired

    The user who created the project.

    visibilityProjectVisibilityrequired

    Who in the sub-account can see the project.

    Available optionsprivateshared
    slugstring

    URL-safe form of the name.

    statusProjectStatusrequired

    Where the project is in its lifecycle.

    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.

    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
    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.

    latestRunIdstring

    The project's most recent run.

    latestDeploymentIdstring

    The project's most recent deployment.

    previewUrlstring<uri>

    Where to preview the latest build.

    productionUrlstring<uri>

    Where the published app is served.

    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.

    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
    createdAtstring<date-time>required

    When the project was created.

    updatedAtstring<date-time>required

    When the project last changed.

    archivedAtstring<date-time>

    When the project was archived, if it was.

    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.

    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.

    etagstringrequired

    The project's version tag, for conditional updates.