v41

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-055374134.9 KB

Pull and convert OCI image

post/images

Request body

namestring required

OCI image reference (e.g., docker.io/library/nginx:latest)

platformstring

Target platform as os/arch[/variant] (e.g. "linux/amd64"), matching Docker --platform. Omit for the host platform. Not a fixed enum: the os/arch[/variant] grammar is validated server-side and invalid values return 400 invalid_platform. Only os "linux" with arch amd64 or arm64 is accepted today.

tagsTags

User-defined key-value tags.

Example request

{
  "name": "docker.io/library/nginx:latest",
  "platform": "linux/amd64",
  "tags": {
    "team": "backend",
    "env": "staging"
  }
}

Response

Image build started (async)

namestring required

Normalized OCI image reference (tag or digest)

digeststring required

Resolved manifest digest

platformstring

Resolved image platform as os/arch[/variant] (e.g. "linux/amd64")

status'pending' | 'pulling' | 'converting' | 'ready' | 'failed' required

Build status

queue_positioninteger nullable

Position in build queue (null if not queued)

errorstring nullable

Error message if status is failed

size_bytesinteger nullable

Disk size in bytes (null until ready)

entrypointstring[] nullable

Entrypoint from container metadata

cmdstring[] nullable

CMD from container metadata

envobject

Environment variables from container metadata

tagsTags

User-defined key-value tags.

working_dirstring nullable

Working directory from container metadata

created_atstring date-time required

Creation timestamp (RFC3339)

Example response

{
  "name": "docker.io/library/nginx:latest",
  "digest": "sha256:abc123def456...",
  "platform": "linux/amd64",
  "status": "ready",
  "queue_position": 2,
  "error": "pull failed: connection timeout",
  "size_bytes": 536870912,
  "entrypoint": [
    "/docker-entrypoint.sh"
  ],
  "cmd": [
    "nginx",
    "-g",
    "daemon off;"
  ],
  "env": {
    "PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
  },
  "tags": {
    "team": "backend",
    "env": "staging"
  },
  "working_dir": "/app",
  "created_at": "2025-01-15T10:00:00Z"
}