Sign in
Deployments

Deploy from an uploaded Docker image tarball

Changed on

Uploads a Docker image tarball (from docker save) and deploys it directly. The image is imported using docker load and then deployed to the specified environment. This is useful when you want to deploy an image without pushing to a registry first.

The uploaded file should be a tarball created by docker save myimage:tag > image.tar or docker save myimage:tag | gzip > image.tar.gz (gzip compressed tarballs are also supported).

post/projects/{project_id}/environments/{environment_id}/deploy/image-upload

Request

  • Base URL: /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/projects/{project_id}/environments/{environment_id}/deploy/image-upload
  • Auth: HTTP bearer

Path parameters

project_idinteger required
environment_idinteger required

Query parameters

tagstring nullable

Deprecated display hint retained for wire compatibility. Temps always generates the actual project-scoped internal image reference.

health_check_pathstring nullable

Optional HTTP health-check path override (e.g. "/api/healthz"). Must start with '/'. When omitted, defaults to "/".

upload_request_idstring nullable

Client-generated UUID identifying this upload attempt. When a deployment already exists for this project, environment, and ID, that deployment is returned as-is instead of importing and deploying the image again — this makes a client retry after a lost response safe. Callers that omit it get no such protection (each call always creates a new deployment), so the CLI always sends one.

Response

Image imported and deployment started

created_atstring date-time required
environment_idinteger required
idinteger required
project_idinteger required
slugstring required
source_typestring required
statestring required

Example response

{
  "created_at": "2025-10-12T12:15:47.609192Z"
}

Changes