API Reference

The one Hanzo PaaS API surface — api.hanzo.ai/v1/platform for projects and apps, api.hanzo.ai/v1/runner for builds.

Hanzo PaaS has one API surface, on the one Hanzo API host.

Base URL

Surface	Base	Auth
Control plane	`https://api.hanzo.ai/v1/platform`	`Authorization: Bearer <iam-jwt>`
Builds	`https://api.hanzo.ai/v1/runner`	`Authorization: Bearer <iam-jwt>` (org admin) or the fabric build token

platform.hanzo.ai is the Studio — the browser UI. It is not an API host: platform.hanzo.ai/v1/* answers 500 Service token is not configured on the server, and platform.hanzo.ai/api/* answers the Studio's HTML shell with a 404. There is no x-api-key header, no tRPC procedure surface, and no /api prefix anywhere in Hanzo.

Authentication

One bearer, minted from a machine identity in Hanzo KMS or from an interactive Hanzo IAM login:

TOKEN=$(curl -sS -X POST https://api.hanzo.ai/v1/kms/auth/login \
  -H 'Content-Type: application/json' \
  -d "{\"clientId\":\"$KMS_CLIENT_ID\",\"clientSecret\":\"$KMS_CLIENT_SECRET\"}" | jq -r .accessToken)

curl -fsS https://api.hanzo.ai/v1/platform/projects \
  -H "Authorization: Bearer $TOKEN"

See Authentication.

Endpoints

Method	Path	Purpose
`GET` · `POST`	`/v1/platform/projects`	List / create projects
`GET` · `DELETE`	`/v1/platform/projects/{project}`	Inspect / delete a project
`GET` · `POST`	`/v1/platform/projects/{project}/apps`	List / create apps
`GET` · `DELETE`	`/v1/platform/projects/{project}/apps/{app}`	Inspect / delete an app
`POST`	`/v1/platform/projects/{project}/apps/{app}/deploy`	Roll the app forward
`POST`	`/v1/platform/projects/{project}/apps/{app}/start`	Start the workload
`POST`	`/v1/platform/projects/{project}/apps/{app}/stop`	Stop the workload
`GET`	`/v1/platform/projects/{project}/apps/{app}/deployments`	Deployment history
`GET`	`/v1/platform/projects/{project}/apps/{app}/deployments/{id}`	One deployment
`GET`	`/v1/platform/projects/{project}/apps/{app}/deployments/{id}/logs`	Deployment logs
`GET` · `POST`	`/v1/platform/sites`	Static sites
`GET`	`/v1/platform/health`	Liveness
`POST`	`/v1/runner`	Enqueue an in-cluster image build

Request format

JSON in, JSON out. Requests are plain REST — no envelope, no procedure names:

curl -fsS -X POST https://api.hanzo.ai/v1/platform/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "web", "name": "Web" }'

Error responses

Errors are a flat JSON object with the HTTP status echoed in the body:

{ "status": 403, "error": "X-Org-Id required" }

Status	Meaning
`400`	Invalid input
`401`	Missing or invalid bearer
`403`	Validated principal lacks the scope (or no org context)
`404`	Resource does not exist
`409`	Conflict (stale version, duplicate slug)
`500`	Server error

Rate limits

Rate-limit headers ride every response:

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