API Reference

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

Base URL

platform.hanzo.ai is the Studio — a browser UI. Do not call it programmatically. It answers, which is what makes it a trap:

• platform.hanzo.ai/v1/<anything> → 401 {"message":"Unauthorized"} — the same answer for a path that does not exist, and the same answer when you present a valid bearer. It is a browser-session wall, not a challenge a token can satisfy, so a 401 there never means "get a better token". Only /v1/health answers 200.
• platform.hanzo.ai/api/<anything> → 404, text/html — the Studio's page shell, not an error you can parse.
• app.platform.hanzo.ai is the same origin one redirect away: it 301s to platform.hanzo.ai, so every path above behaves identically there.

The programmatic host is api.hanzo.ai, and it distinguishes: api.hanzo.ai/v1/platform/projects → 403 (real, needs org context), api.hanzo.ai/v1/platform/zzz-bogus → 404 (no such route). There is no x-api-key header, no tRPC procedure surface on this host, and no /api prefix on any Hanzo endpoint.

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

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" }

Rate limits

Rate-limit headers ride every response:

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