Containers API

The Containers API manages container deployments across your clusters. It supports Docker images from any registry and handles the full deployment lifecycle.

Endpoints

Procedure	Method	Description
`container.all`	GET	List all containers in a project
`container.one`	GET	Get container details
`container.create`	POST	Create a new container deployment
`container.update`	PATCH	Update container configuration
`container.remove`	DELETE	Remove a container
`container.deploy`	POST	Trigger a new deployment
`container.restart`	POST	Restart running instances
`container.stop`	POST	Stop a container
`container.start`	POST	Start a stopped container
`container.logs`	GET	Stream container logs

List Containers

GET /api/container.all?projectId=proj_abc123

curl "https://app.platform.hanzo.ai/api/container.all?projectId=proj_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "result": {
    "data": [
      {
        "id": "ctr_abc123",
        "name": "web",
        "image": "ghcr.io/myorg/web:v1.2.3",
        "status": "running",
        "replicas": 3,
        "port": 3000,
        "clusterId": "cluster_abc123",
        "createdAt": "2025-09-01T10:00:00Z"
      },
      {
        "id": "ctr_def456",
        "name": "worker",
        "image": "ghcr.io/myorg/worker:v1.2.3",
        "status": "running",
        "replicas": 1,
        "port": null,
        "clusterId": "cluster_abc123",
        "createdAt": "2025-09-01T10:05:00Z"
      }
    ]
  }
}

Get Container

GET /api/container.one?containerId=ctr_abc123

curl "https://app.platform.hanzo.ai/api/container.one?containerId=ctr_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "result": {
    "data": {
      "id": "ctr_abc123",
      "name": "web",
      "image": "ghcr.io/myorg/web:v1.2.3",
      "status": "running",
      "replicas": 3,
      "port": 3000,
      "clusterId": "cluster_abc123",
      "env": [
        { "key": "NODE_ENV", "value": "production" },
        { "key": "DATABASE_URL", "value": "***" }
      ],
      "resources": {
        "cpuLimit": "500m",
        "memoryLimit": "512Mi"
      },
      "domains": ["app.example.com"],
      "healthCheck": {
        "path": "/health",
        "port": 3000,
        "interval": 30
      },
      "createdAt": "2025-09-01T10:00:00Z",
      "lastDeployedAt": "2026-02-20T15:30:00Z"
    }
  }
}

Create Container

POST /api/container.create

curl -X POST https://app.platform.hanzo.ai/api/container.create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_abc123",
    "clusterId": "cluster_abc123",
    "name": "web",
    "image": "ghcr.io/myorg/web:v1.2.3",
    "port": 3000,
    "replicas": 3,
    "env": [
      { "key": "NODE_ENV", "value": "production" }
    ],
    "resources": {
      "cpuLimit": "500m",
      "memoryLimit": "512Mi"
    },
    "healthCheck": {
      "path": "/health",
      "port": 3000,
      "interval": 30
    }
  }'

Parameters:

Field	Type	Required	Description
`projectId`	string	Yes	Project ID
`clusterId`	string	Yes	Target cluster
`name`	string	Yes	Container name
`image`	string	Yes	Docker image reference
`port`	number	No	Exposed port
`replicas`	number	No	Number of instances (default: 1)
`env`	array	No	Environment variables
`resources`	object	No	CPU and memory limits
`healthCheck`	object	No	Health check configuration

Response: 201 Created

Update Container

PATCH /api/container.update

Update configuration without triggering a new deployment. Use container.deploy to roll out changes.

curl -X PATCH https://app.platform.hanzo.ai/api/container.update \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "containerId": "ctr_abc123",
    "replicas": 5,
    "env": [
      { "key": "NODE_ENV", "value": "production" },
      { "key": "LOG_LEVEL", "value": "info" }
    ]
  }'

Deploy

POST /api/container.deploy

Trigger a new deployment with an updated image tag or configuration.

curl -X POST https://app.platform.hanzo.ai/api/container.deploy \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "containerId": "ctr_abc123",
    "image": "ghcr.io/myorg/web:v1.3.0"
  }'

Response:

{
  "result": {
    "data": {
      "deploymentId": "dep_xyz789",
      "status": "in_progress",
      "previousImage": "ghcr.io/myorg/web:v1.2.3",
      "newImage": "ghcr.io/myorg/web:v1.3.0",
      "triggeredAt": "2026-02-26T10:00:00Z"
    }
  }
}

Deployments use a rolling update strategy by default. If the health check fails, the deployment is automatically rolled back.

Lifecycle Operations

Restart

curl -X POST https://app.platform.hanzo.ai/api/container.restart \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "containerId": "ctr_abc123" }'

Stop

curl -X POST https://app.platform.hanzo.ai/api/container.stop \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "containerId": "ctr_abc123" }'

Start

curl -X POST https://app.platform.hanzo.ai/api/container.start \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "containerId": "ctr_abc123" }'

Logs

GET /api/container.logs?containerId=ctr_abc123

Stream logs from all replicas of a container.

curl "https://app.platform.hanzo.ai/api/container.logs?containerId=ctr_abc123&tail=100" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query parameters:

Parameter	Type	Default	Description
`containerId`	string	--	Container ID
`tail`	number	100	Number of recent lines
`since`	string	--	ISO 8601 timestamp
`follow`	boolean	false	Stream logs in real time

Delete Container

DELETE /api/container.remove

curl -X DELETE https://app.platform.hanzo.ai/api/container.remove \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "containerId": "ctr_abc123" }'

Response: 204 No Content

Deleting a container stops all running instances and removes associated domains and volumes. This cannot be undone.

Container Status Values

Status	Description
`creating`	Container is being provisioned
`running`	All replicas are healthy
`deploying`	A new deployment is rolling out
`stopped`	Container is stopped
`error`	One or more replicas have failed
`deleting`	Container is being removed

On this page