Rebuild Image from Current Source

POST

images

{image_id}

rebuild

curl --request POST \
  --url https://api.vertracloud.app/v1/images/{image_id}/rebuild \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vertracloud.app/v1/images/{image_id}/rebuild', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vertracloud.app/v1/images/{image_id}/rebuild"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "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"
  }
}

There is no request body. The source depends on the image: an image linked to GitHub is built from the current tip of its linked branch; any other image is built from the build context of its latest build, including a build that failed. Use it to retry a failed build without sending the files again. The rebuild keeps the same image ID and, when it succeeds, adds a new version. It counts toward the hourly deploy limit like any other build, and a failed rebuild keeps the current version. Applications are only restarted if the image has auto_update_apps turned on; otherwise each app moves to the new version on the next restart or deploy you ask for. To build from different files, use Rebuild Image. Needs the images:write scope when called with an API key.

string

required

The image 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.

Response

object

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

Show Toggle object

string

The image ID.

string

The image name.

string | null

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

string

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

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.

string | null

Readable reason of the latest failed build, or null.

string | null

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

integer | null

Size of the current version, uncompressed, in bytes.

integer | null

Number of layers of the current version.

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

object | null

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

string | null

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

string

When the image was created.

string

When the image was last updated.

{
  "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

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 (404).
ACCESS_DENIED: The image belongs to another account or is provided by the platform, or you are a workspace member without the right to rebuild it (403).
IMAGE_TEMPLATE_ONLY: The image came from a template and cannot be rebuilt (409).
PLAN_REQUIRED: The image owner has no active plan (403).
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).
OPERATION_IN_PROGRESS: The image is being deleted (409).
IMAGE_NOT_READY: The image has no stored build context to build from (409).
DEPLOY_RATE_LIMITED: The hourly deploy limit of the image owner was reached; details has limit, window_seconds and retry_after (429).
INSTALLATION_NOT_FOUND: The linked repository is no longer in a GitHub App installation of the image owner (404).
FETCH_ZIP_ERROR: GitHub did not return the repository archive, for example because the linked branch no longer exists (404), or GitHub is unavailable (502).
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).
INVALID_ZIP: The stored build context or the repository archive is not a readable ZIP file (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). Also returned when the build could not be started (409).
INTERNAL_SERVER_ERROR: Unexpected failure (500).

{
  "code": "IMAGE_BUILD_IN_PROGRESS"
}

Last modified on November 11, 2026

Rebuild Image from Current Source

curl --request POST \
  --url https://api.vertracloud.app/v1/images/{image_id}/rebuild \
  --header 'Authorization: Bearer <token>'

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vertracloud.app/v1/images/{image_id}/rebuild', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vertracloud.app/v1/images/{image_id}/rebuild"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "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"
  }
}

Overview

Endpoints

Rebuild Image from Current Source

Response

Error Responses

​Response

​Error Responses

Response

Error Responses