Skip to main content
PUT
Rebuild Image
The request is multipart/form-data. The rebuild keeps the same image ID and, when it succeeds, adds a new version. 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.
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.
file
required
The new build context: a ZIP file, up to 100 MB, with a Dockerfile at its root.

Response

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

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