Sign in
Deployments

Deploy from an external Docker image

Changed on

Triggers a deployment using a pre-built Docker image from an external registry. The image will be pulled and deployed to the specified environment.

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

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
  • Auth: HTTP bearer

Path parameters

project_idinteger required
environment_idinteger required

Request body

claim_localboolean

Claim an image already present in the platform host's Docker daemon. Temps retags it into a generated project-owned namespace and records its immutable image ID. Never set this for a registry image.

commandstring[] nullable

Optional container command override. Each entry is passed directly as one argv element; no shell parsing or interpolation is performed.

external_image_idinteger nullable

External image ID (if already registered). If provided without image_ref, the image reference will be fetched from the registered external image.

health_check_pathstring nullable

Optional HTTP health-check path override (e.g. "/api/healthz"). Image deploys can't read .temps.yaml, so this sets the path the deployer probes after the container starts and the path the environment's uptime monitor checks. Must start with '/'. When omitted, defaults to "/".

image_refstring nullable

Docker image reference (e.g., "ghcr.io/org/app:v1.0") Required if external_image_id is not provided

metadataunknown

Example request

{
  "health_check_path": "/api/healthz",
  "image_ref": "ghcr.io/myorg/myapp:v1.0"
}

Response

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