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 Get Himalaya Authorization with the project's ID. Check that saveDesign is true, and save the returned canonicalApp.

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

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