> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Rebuild Image

> Rebuilds an image by replacing the whole build context with a new ZIP file.

The request is `multipart/form-data`. The rebuild keeps the same image ID and, when it succeeds, adds a new [version](https://docs.vertracloud.app/api-reference/endpoint/images/versions.md). **A rebuild never restarts applications**: each app moves to the new version on the next restart or deploy you ask for. A failed rebuild keeps the current version. Rebuilds do not count against the image limit. Plans without custom images cannot rebuild, but can still delete.

Needs the `images:write` scope when called with an API key.

**image\_id** `string` *required*

The image ID.

**workspace\_id** `string`

If the image belongs to a workspace, the workspace's ID. Required for workspace members acting on an image they don't own.

**file** `file` *required*

The new build context: a ZIP file, up to 100 MB, with a `Dockerfile` at its root.

### Response

**response** `object`

The image. The response is `202 Accepted` with `status: "building"`.

**Toggle object**

**id** `string`

The image ID.

**name** `string`

The image name.

**description** `string | null`

The image description (free text, up to 128 characters), or `null` when it has none.

**owner** `string`

`account` for your own images, `system` for images provided by the platform (these cannot be changed or deleted).

**status** `string`

State of the latest build: `building`, `success` or `failed`. A failed rebuild does not change the current version: apps keep running the last good one.

**error** `string | null`

Readable reason of the latest failed build, or `null`.

**digest** `string | null`

Digest (`sha256:...`) of the current version, or `null` while no build has succeeded.

**uncompressed\_bytes** `integer | null`

Size of the current version, uncompressed, in bytes.

**layer\_count** `integer | null`

Number of layers of the current version.

**apps** `object[]`

The applications created from this image. Each has `id`, `name`, `version_id` (the image version it runs, or `null`) and `outdated` (`true` when the image has a newer version; the app moves to it on the next restart or deploy you ask for).

**github** `object | null`

The linked GitHub repository and branch (`repository` as `owner/name`, `branch`), or `null` when the image is not linked.

**current\_version\_id** `string | null`

The current version of the image, or `null` while no build has succeeded.

**created\_at** `string`

When the image was created.

**updated\_at** `string`

When the image was last updated.

```json Response theme={null}
{
  "response": {
    "id": "img-abc123def456",
    "name": "my-api",
    "description": null,
    "owner": "account",
    "status": "building",
    "error": null,
    "digest": null,
    "uncompressed_bytes": null,
    "layer_count": null,
    "apps": [],
    "github": null,
    "current_version_id": null,
    "created_at": "2026-10-23T14:02:00Z",
    "updated_at": "2026-10-23T14:02:00Z"
  }
}
```

### Error Responses

**code** `string`

The error code indicating the reason for the failure. Possible values:

* `API_KEY_SCOPE_DENIED`: The API key does not have the required scope (`403`).
* `IMAGE_NOT_FOUND`: The image does not exist or you cannot access it (`404`).
* `PLAN_DOES_NOT_SUPPORT_CUSTOM_IMAGES`: The plan does not include custom Docker images (`403`).
* `IMAGE_BUILD_IN_PROGRESS`: The image already has a build running (`409`).
* `DOCKERFILE_NOT_FOUND`: There is no file named exactly `Dockerfile` at the root of the context (`400`).
* `DOCKERFILE_REFUSED`: The `Dockerfile` has a refused instruction; `details` lists the findings (`400`).
* `IMAGE_CONTEXT_TOO_LARGE`: The build context is over a limit: more than 100 MB compressed, more than 512 MB uncompressed, more than 50,000 entries, or a `Dockerfile` larger than 1 MB (`413`).
* `IMAGE_BUILDER_UNAVAILABLE`: No host can build images right now; try again later (`503`).
* `INTERNAL_SERVER_ERROR`: Unexpected failure (`500`).

```json Error Response theme={null}
{
  "code": "IMAGE_BUILD_IN_PROGRESS"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.