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 with the project's ID. Save the returned project.headReleaseId. This is the release that your app shows to the user.

  2. Call Claim Himalaya App with the project's ID. Save the returned canonicalApp. If the app was already claimed, the method returns the same value.

  3. Call Get Himalaya Authorization with the project's ID. Check that saveDesign is true.

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

  5. 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, store the returned himalayaReleaseId, so you can show the user a list of saved versions.

  2. When the user selects a version, call 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.

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

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 with the project's ID. Check that project.status is BUILDING.

  2. Call Get Himalaya Authorization with the project's ID. Check that workerLaunch is true.

  3. Call Resume Project with the project's ID. The project's remote development environment starts in the background.

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

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 with the project's ID. Save the returned canonicalApp. A retry returns the same app.

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

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

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

Last updated: 3 November 2026

Did this help?