# About the Containers Projects API

The Containers Projects API lets you work with the projects of the Wix AI coding agent. A project is a mobile app that a user builds by chatting with the coding agent. Use this API to retrieve projects, resume work on them, save design changes, and restore earlier versions.

With the Containers Projects API, you can:

- Retrieve a project and its current status.
- Resume work on a project, so the coding agent can continue to build it.
- Save design changes as a new draft release, and preview them.
- Restore an earlier version of a project.
- Build installable app files and retrieve the latest builds for each platform.

To chat with the coding agent about a project, use the [Containers Chat API](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-chat/introduction).

## The project lifecycle

A project's `status` changes in one direction only:

1. `PLANNING`: The user and the coding agent plan the app. New projects start with this status.
1. `PLAN_READY`: The plan is finalized, and the first build of the app is about to start.
1. `BUILDING`: The coding agent builds the app. The project stays in this status, and the user can continue to request changes.

You can resume a project only when its status is `BUILDING`.

## Releases and versions

Each design save and each edit by the coding agent creates a new draft release of the project's app. The project's `headReleaseId` is the release that the project is currently on. Your app previews this release, and the next design save or edit branches from it.

- [Save Project Design](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/save-project-design) creates a draft release from the release that the user is viewing, and sets `headReleaseId` to the new release.
- [Restore Release](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/restore-release) sets `headReleaseId` to an earlier release.

Neither method changes the project's live app.

When you specify a `conversationId`, both methods add a `CHECKPOINT` message to that conversation, so the user sees the saved or restored version in the chat.

## Platforms

Most new projects have `platform` set to `HIMALAYA_MOBILE`. For a new project, call [Claim Himalaya App](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/claim-himalaya-app) to associate it with its app. Then call [Get Himalaya Authorization](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/get-himalaya-authorization) to check that the current user can work on the project. The response includes the app's canonical slug in `canonicalApp`, which [Save Project Design](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/save-project-design) requires.

Older projects have `platform` set to `IOS` or `ANDROID`.

## App claims and mobile builds

Any authorized site collaborator can claim the app for a new project. Calling [Claim Himalaya App](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/claim-himalaya-app) again for the same project returns the same `canonicalApp`.

Call [Start Mobile Build](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/start-mobile-build) to build installable files for iOS, Android, or both. Builds run in the background. The response reports each accepted build and any platform whose build couldn't start. Poll [Get Latest Mobile Builds](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/get-latest-mobile-builds) for the last attempt and last successful build on each platform. Specify `himalayaControlToken` to refresh builds that are still in progress before each response.

When a build succeeds, its download links are valid for about 7 days, until `downloadExpiresDate`. To get new links after they expire, start a new build.

## Before you begin

It's important to note the following points before starting to code:

- Projects belong to the Wix site they're created on.
- [Save Project Design](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/save-project-design) and [Start Mobile Build](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/start-mobile-build) require a short-lived control credential for the project's app releases, in `himalayaControlToken`.
- Only a project's owner can restore a release.
- [Resume Project](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/resume-project) starts the project's remote development environment in the background. The API doesn't report when the environment is ready.

## Use cases

- [Save a design change and preview it](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/sample-flows#save-a-design-change-and-preview-it)
- [Restore an earlier version of a project](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/sample-flows#restore-an-earlier-version-of-a-project)
- [Resume work on a project](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/sample-flows#resume-work-on-a-project)
- [Build and download a project's app files](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/sample-flows#build-and-download-a-projects-app-files)

## Terminology

- **Project**: An app that a user builds with the Wix AI coding agent.
- **Release**: A saved version of a project's app. Design saves and edits by the coding agent create draft releases.
- **Head release**: The release that a project is currently on, in `headReleaseId`.
- **Design-token document**: A JSON document that holds the design values of a project's app, such as its colors and fonts.
- **Remote development environment**: The environment in which the coding agent builds the project's app.
- **Checkpoint**: A message in a conversation that marks a saved or restored version of the project.
- **Mobile build**: A build of a project's installable app file for 1 platform, such as an `.ipa` file for iOS or an `.apk` file for Android.

@sdk_package_setup

# Containers Projects API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

## Save a design change and preview it

When a user changes the design of their app, such as its colors or fonts, your app saves the change as a new draft release and shows the user a preview. The project's live app doesn't change. This flow is for projects whose `platform` is `HIMALAYA_MOBILE`.

To save a design change and preview it:

1. Call [Get Project](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/get-project) with the project's ID. Save the returned `project.headReleaseId`. This is the release that your app shows to the user.

1. Call [Claim Himalaya App](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/claim-himalaya-app) with the project's ID. Save the returned `canonicalApp`. If the app was already claimed, the method returns the same value.

1. Call [Get Himalaya Authorization](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/get-himalaya-authorization) with the project's ID. Check that `saveDesign` is `true`.

1. Call [Save Project Design](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/save-project-design) with these values:

    - `projectId`: The project's ID.
    - `baseReleaseId`: The release ID that you saved in step 1.
    - `tokensJson`: The complete design-token document, including the user's change.
    - `himalayaControlToken`: A short-lived control credential for the project's app releases.
    - `canonicalApp`: The value returned by Claim Himalaya App in step 2.
    - `conversationId`: The ID of the conversation that the user is viewing, to add a checkpoint for the saved version.

1. Use the returned `previewToken` to show the user a preview of the saved release. The token expires at `previewTokenExpiresAt`. Save the returned `himalayaReleaseId`, so the user can go back to this version later.

## Restore an earlier version of a project

When a user wants to go back to a version of their app that they saved earlier, your app restores that release. The restored release becomes the base for the next design save or edit, and the live app doesn't change.

To restore an earlier version of a project:

1. Each time you call [Save Project Design](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/save-project-design), store the returned `himalayaReleaseId`, so you can show the user a list of saved versions.

1. When the user selects a version, call [Restore Release](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/restore-release) with the project's ID and the selected release ID in `releaseId`. Specify `himalayaControlToken` to confirm that the release belongs to the project, and `conversationId` to add a checkpoint for the restored version.

1. Show the user the restored release. The returned `project.headReleaseId` is now the restored release ID. Use it as `baseReleaseId` the next time you call [Save Project Design](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/save-project-design).

## Resume work on a project

When a user returns to a project that the coding agent has already built, your app resumes the project so the coding agent can continue to work on it. This flow is for projects whose `platform` is `HIMALAYA_MOBILE`.

To resume work on a project:

1. Call [Get Project](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/get-project) with the project's ID. Check that `project.status` is `BUILDING`.

1. Call [Get Himalaya Authorization](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/get-himalaya-authorization) with the project's ID. Check that `workerLaunch` is `true`.

1. Call [Resume Project](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/resume-project) with the project's ID. The project's remote development environment starts in the background.

1. Call [Send Message](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-chat/send-message) in the Containers Chat API with the user's request. The coding agent picks up the request when the environment is ready. To track the response, poll [Query Messages](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-chat/query-messages).

## Build and download a project's app files

When a user wants to install or distribute their project, your app can start an iOS or Android build and show the resulting file. This flow is for a new project whose `platform` is `HIMALAYA_MOBILE`.

To build and download the app files:

1. Call [Claim Himalaya App](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/claim-himalaya-app) with the project's ID. Save the returned `canonicalApp`. A retry returns the same app.

1. Call [Start Mobile Build](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/start-mobile-build) with the project's ID, the `platforms` to build, a short-lived `himalayaControlToken`, and the `canonicalApp` from step 1. Don't specify `androidFormat`, so Android builds an installable `.apk` file. Check `failedPlatforms` for any platform whose build couldn't start.

1. Poll [Get Latest Mobile Builds](fallback::https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-projects/project-v1/get-latest-mobile-builds) with the project's ID and `himalayaControlToken` until each accepted build's `lastAttempt.status` is `SUCCEEDED`, `FAILED`, or `CANCELED`. Supplying the token refreshes builds that are still in progress.

1. When a build succeeds, check that `downloadExpired` is `false` and the link you need isn't empty. For iOS, use `installPageUrl` to let the user install the app on an iPhone. For Android, use `downloadUrl` to offer the installable `.apk` file. If the link is missing or expired, start a new build.

Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

List Projects