---
title: "Retry checkpoint build"
method: POST
path: "/api/apps/{app_id}/app-checkpoints/{checkpoint_id}/retry-build"
---

# Retry checkpoint build

`POST /api/apps/{app_id}/app-checkpoints/{checkpoint_id}/retry-build`

## Request

- Base URL: `https://app.base44.com`
- URL: `https://app.base44.com/api/apps/{app_id}/app-checkpoints/{checkpoint_id}/retry-build`
- Auth: HTTP bearer

<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](/developers/references/app-management/get-started/concepts#checkpoints) and returns without waiting for it to finish.

Use it when a checkpoint's `preview_status` in [List checkpoints](/api-reference/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](/api-reference/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](/developers/references/app-management/get-started/concepts#branches)'s checkpoints.

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

## Path parameters

- `checkpoint_id` string, required: ID of the checkpoint, as returned in `id` by [List checkpoints](/api-reference/list-checkpoints).
- `app_id` string, required: ID of the app.

## Query parameters

- `branch_id` string: ID of the branch to work on, as returned by [List branches](/api-reference/list-branches). Omit it to work on the app's main branch.

## Response `200`

Where the build stands, and the commit being built.

- RetryCheckpointBuildResponse: Where a checkpoint's preview build stands when the call returns.
  - `status` 'building' | 'ready' | 'skipped', required: Where the build stands when the call returns. Either `building` (the build started in the background), `ready` (the checkpoint's commit was already built, so nothing was rebuilt), or `skipped` (the app was imported from an external repository, and those apps have no preview build).
  - `git_commit_hash` string, required: Git commit hash of the code being built, the same as the checkpoint's `git_commit_hash`.

## Other responses

- `400`: The checkpoint has no commit to build. On an app imported from GitHub, a `branch_id` whose branch is the repository's default branch also answers 400 with `extra_data.reason` `invalid_branch_name`.
- `401`: Missing or invalid credentials.
- `403`: You don't have access to this app, or you used a read-only key or a workspace API key. These endpoints take a full-access personal API key.
- `404`: App not found, the app has no checkpoint with this ID on main or on the branch in `branch_id`, or no branch you can see has this `branch_id`.
- `409`: The app's main line is protected, so its state can't be changed directly. With `branch_id`, the branch was merged (`branch_scope_read_only`) or is being updated from main (`branch_sync_in_progress`), as `extra_data.reason` says.

## Changes

- **2026-10-21** `c23775445de2`: 1 info
  - added the new optional `query` request parameter `branch_id`
- **2026-10-11** `80287813ab84`: 1 info
  - the endpoint scheme security `PersonalAccessTokenAuth` was added to the API
- **2026-09-28** `53bda28df692`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/idealspot/apis/base44-app-management-api/changes/api/apps/:app_id/app-checkpoints/:checkpoint_id/retry-build/post.md)

---

[API](https://skmtc.dev/idealspot/apis/base44-app-management-api.md) - [All operations](https://skmtc.dev/idealspot/apis/base44-app-management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/idealspot/apis/base44-app-management-api/revisions/b5b4ebd82a1e?raw)