Sign in

Create checkpoint

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Saves the app's current state as a new checkpoint, so you can return to it later with Restore checkpoint.

A checkpoint records the app's committed code, its entity schemas and its backend functions. Nothing is saved when the app has not changed since its most recent checkpoint: you get a 200 with created set to false and reason set to no_changes, and the checkpoint you already have stands.

<Warning>That check is not a guarantee against duplicates. Two requests in flight at the same time can both find nothing changed and both save a checkpoint, so retrying before the first request has finished can leave you with two. Send one at a time, and read List checkpoints rather than retrying blind.</Warning>

Saving a checkpoint starts its preview build in the background. Poll List checkpoints and watch the new checkpoint's preview_status to see when the preview is ready.

<Note>This endpoint accepts a personal API key. Workspace API keys are not authorized for it and are rejected with a 403.</Note>

post/api/apps/{app_id}/app-checkpoints

Path parameters

app_idstring required

ID of the app.

ID of the app.

Request body

namestring

Name for the checkpoint, shown in the app's version history. Send a non-empty value: an empty string is not stored, and the checkpoint is named after the app's most recent chat message instead.

Example request

{
  "name": "Before pricing rework"
}

Response

Whether a checkpoint was saved, and its ID if one was.

createdboolean required

Whether a checkpoint was saved. false means the app has not changed since its most recent checkpoint, so there was nothing to save.

checkpoint_idstring nullable

ID of the checkpoint that was saved, or null when created is false. Pass it as checkpoint_id to Deploy an app to publish this version, or as checkpoint_id to Restore checkpoint to return to it.

reasonstring nullable

Why nothing was saved. no_changes is the only value, and it is null when created is true.

Example response

{
  "created": true,
  "checkpoint_id": "6886b8d390dc7e2f4a2c91b3",
  "reason": "no_changes"
}

Changes