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

Starts a new preview build for a checkpoint and returns without waiting for it to finish.

Use it when a checkpoint's preview_status in List checkpoints is failed. It works on a checkpoint in any state. When the checkpoint's commit already has a build, nothing is rebuilt and the checkpoint is marked ready straight away.

The build runs in the background. Poll List checkpoints and watch the checkpoint's preview_status until it's ready or failed. Build failures can include details in build_error.message.

Only one build of a commit runs at a time. Retrying while another build of the same commit is still running doesn't start a second one in parallel. The retry waits for that build and only builds again if it didn't succeed. If the wait expires without a completed build, the checkpoint stays building while it's within the build execution budget. Once more than 20 minutes have passed since the latest checkpoint update or build start, listing checkpoints checks for a completed build and marks the checkpoint ready or failed. If build availability can't be checked, its status stays unchanged. You can retry a failed checkpoint's build.

<Warning>A checkpoint whose git_commit_hash is null was saved before the app's code was kept in git. Retrying its build first saves that checkpoint's code to the app as a new commit, which changes the app's current code. On a branch, such a checkpoint can't be rebuilt and returns a 400.</Warning>

Set branch_id to rebuild one of a branch's checkpoints.

<Note>This endpoint accepts a personal API key. A read-only key is refused, and workspace API keys are not accepted.</Note>

{
  "status": "building",
  "git_commit_hash": "a1b2c3d4e5f67890abcdef1234567890abcdef12"
}