API
The REST API reference for every Hanzo Cloud service -- one base URL, one bearer key, at api.hanzo.ai/v1.
API
Every Hanzo service exposes a REST API under one base URL. One credential works across all of them, and the request shape is uniform: a bearer token, a JSON body, a JSON response.
Base URL and Authentication
https://api.hanzo.ai/v1Authenticate every request with a bearer token in the Authorization header. Use an API key (hk-...) for server-to-server calls, or an IAM access token for user-facing apps:
Authorization: Bearer hk-...All traffic is TLS-only and passes through the Gateway, which authenticates, rate-limits, and routes it. See API Keys to create a key and Authentication for OIDC tokens.
Service Namespaces
Each service is namespaced under /v1:
| Path | Service |
|---|---|
/v1/chat/completions, /v1/embeddings, /v1/models | AI gateway (OpenAI-compatible) |
/v1/iam | Identity, orgs, and roles |
/v1/kms | Secrets and keys |
/v1/authz | Authorization checks |
/v1/mpc | Threshold signing |
/v1/billing, /v1/pricing | Usage, credits, and pricing |
The API is versioned at v1; it evolves additively, so integrations stay stable.
Example Request
curl https://api.hanzo.ai/v1/models \
-H "Authorization: Bearer hk-..."Responses are JSON. Errors use standard HTTP status codes -- 401 for a bad or missing key, 403 when authenticated but forbidden, 429 when rate-limited, 402 when out of credits.
Related
- API Keys -- create and manage
hk-credentials - Authentication -- OAuth 2.0 + OIDC for user tokens
- Gateway -- the entry point every request passes through
- OpenAPI -- machine-readable specs and generated references
- SDKs -- Python, TypeScript, Go, and Rust clients
How is this guide?