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

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 these projects, 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 also includes the canonical slug of the project's app 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 for these projects.

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

## Before you begin

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

- The methods described in this API reference are in Beta.
- 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) requires 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)

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

@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 [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`, and save the returned `canonicalApp`.

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 that you saved 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).

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

Frontend Modules

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

Start Mobile Build