API Reference

Platform REST and tRPC API for managing organizations, clusters, containers, and VMs

Hanzo Platform exposes two API surfaces: tRPC for the dashboard and REST for external integrations. Both share the same authentication and authorization layer.

Base URLs

Surface	Base	Auth	Use
Canonical control	`https://platform.hanzo.ai/v1`	`Authorization: Bearer <service-token>`	Container redeploy, observe/drift (machine)
Build pipeline	`https://platform.hanzo.ai/api`	`x-api-key: <key>`	Build/deploy applications via tRPC-over-OpenAPI

The /v1 surface is the canonical Hanzo control plane. The /api surface is the Dokploy-derived build pipeline, where each endpoint is a tRPC procedure exposed over HTTP as <router>.<procedure> (e.g. application.create, domain.create).

Authentication

The build-pipeline surface accepts an API key (machine) or an IAM bearer token (interactive):

curl https://platform.hanzo.ai/api/organization.all \
  -H "x-api-key: $PLATFORM_API_KEY"

The canonical /v1 surface uses a service token: Authorization: Bearer $PAAS_SERVICE_TOKEN. Both credential types come from Hanzo KMS. See Authentication for details.

tRPC Procedures

The build pipeline exposes these tRPC routers:

Router	Description
`organization`	Organization CRUD
`orgTeam`	Team member management
`cluster`	Cluster lifecycle
`application`	Application deployments (the unit a container maps to)
`compose`	Multi-service compose/stack units
`project`	Project management
`environment`	Environment configuration
`build`	Build pipelines
`log`	Log streaming
`registry`	Container registry
`domain`	Domain and DNS management
`git`	Git integration
`user`	User profile
`provisioner`	Infrastructure provisioning
`audit`	Audit log
`invitation`	Team invitations
`system`	System health and status

Request Format

tRPC requests use HTTP POST with a JSON body:

curl -X POST https://platform.hanzo.ai/api/cluster.create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production",
    "provider": "digitalocean",
    "region": "sfo3"
  }'

Response Format

All responses return JSON:

{
  "result": {
    "data": {
      "id": "cluster_abc123",
      "name": "production",
      "status": "provisioning"
    }
  }
}

Error Responses

Errors return an appropriate HTTP status code with a JSON body:

{
  "error": {
    "message": "Cluster not found",
    "code": "NOT_FOUND",
    "httpStatus": 404
  }
}

Code	Meaning
`BAD_REQUEST`	Invalid input
`UNAUTHORIZED`	Missing or invalid token
`FORBIDDEN`	Insufficient permissions
`NOT_FOUND`	Resource does not exist
`CONFLICT`	Resource already exists
`INTERNAL_SERVER_ERROR`	Server error

Rate Limits

Endpoint Type	Rate Limit
Read operations	100 requests/minute
Write operations	30 requests/minute
Log streaming	10 concurrent connections

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1709000000