API Reference
The unified REST API reference for every Hanzo product — 38 services, one key, generated from OpenAPI 3.1 specs.
Hanzo API Reference
One platform, one credential. Every Hanzo product speaks REST over HTTPS, shares a single API key, and is documented here from its OpenAPI 3.1 specification — 38 services, 2,000+ endpoints. Each reference links to its concept guide, and every guide links back here.
Authentication
All services accept the same bearer credential — a Hanzo IAM JWT or an hk- API
key. Most products are reachable both on their own host and through the unified
gateway at api.hanzo.ai.
curl -H "Authorization: Bearer $HANZO_API_KEY" https://api.hanzo.ai/v1/modelsGet your API key at console.hanzo.ai.
SDKs
Prefer a typed client over raw HTTP:
| Language | Package | Install |
|---|---|---|
| Python | hanzoai | pip install hanzoai |
| TypeScript | hanzoai | npm install hanzoai |
| Go | go-sdk | go get github.com/hanzoai/go-sdk |
| Rust | hanzo-ai | cargo add hanzo-ai |
| C/C++ | c-sdk | CMake FetchContent |
AI & Models
AI — Inference
OpenAI- & Claude-compatible chat, completions, embeddings, images, audio, rerank
Cloud
Cloud API — model management, inference, usage tracking, RAG, accounts
Chat
Multi-model AI chat with conversations, MCP tools, and file uploads
Search
AI-powered search — indexing, semantic query, generative results
Bot
AI assistant framework — skills, channels, webhook integrations
Nexus
RAG pipeline — document ingestion, chunking, embedding, retrieval
Vector
Vector database — collections, embeddings, similarity search
ML
MLOps — pipelines, model registry, training jobs, deployment
Engine
Inference engine — GPU clusters, model loading, quantization, scheduling
Evals
LLM evaluation — LLM-as-judge scoring, datasets, metrics, presets
Flow
Visual workflow builder — triggers, actions, branching logic
Auto
Event-driven automation — schedules, webhooks, task chains
Operative
Computer-use agent — browser automation, desktop control, sessions
Compute & Deploy
App
App projects & deployments — build and host sites/apps on hanzo.app
PaaS
Platform-as-a-Service — deployments, domains, managed databases
Platform
Application hosting — projects, Git-push deploy, scaling, logs
Edge
Edge functions — serverless compute at global locations
Registry
Container registry — Docker images, OCI artifacts, scanning
Visor
Cluster management — VM & Kubernetes monitoring, resource visualization
Data & Storage
DB
Serverless PostgreSQL — projects, branches, pgvector, connection pooling
KV
Key-value store — Redis/Valkey-compatible, pub/sub, streams
S3
Object storage — S3-compatible buckets, objects, presigned URLs
Base
Collections — schema-driven records store over IAM-native collections
MQ
Message queue — publish/subscribe subjects, durable delivery
Stream
Kafka-compatible streaming — topics, consumers, partitions
PubSub
Pub/sub messaging — JetStream subjects, durable consumers
Identity & Security
IAM
Identity — users, organizations, SSO, OIDC, OAuth2, SAML, JWKS
DID
Decentralized identity — W3C DIDs, profiles, verifiable credentials
KMS
Secrets & keys — enveloped secrets, threshold-key ops, certificates, sync
Guard
AI safety — PII redaction, prompt-injection detection, content filtering
ZT
Zero-trust networking — tunnels, access policies, service mesh
Commerce & Business
Commerce
Headless commerce — accounts, carts, orders, payments, subscriptions
Pricing
Pricing API — model costs, subscription plans, GPU tiers
Console
LLM observability — tracing, prompt management, evaluations
Analytics
Usage analytics — requests, tokens, cost tracking, per-model metrics
Infrastructure & Observability
Gateway
API gateway — unified routing, chat-completions proxy, rate limiting
O11y
Observability — metrics, logs, traces, alerts, dashboards
DNS
DNS management — zones, records, Cloudflare integration
Conventions
Every Hanzo API follows the same conventions, so a client written against one service works against all of them. The shared components live in hanzoai/openapi/shared.
| Base URL | Each product is reachable on its own host (e.g. https://commerce.hanzo.ai) and, for most, through the gateway at https://api.hanzo.ai. |
| Versioning | All routes are namespaced under /v1. There is no /v2; changes are additive and backward-compatible. |
| Authentication | HTTP Bearer — a Hanzo IAM JWT or an hk- API key. One credential across every service. See auth.yaml. |
| Errors | A consistent JSON error envelope (error.type, error.message, error.code) with standard HTTP status codes. See errors.yaml. |
| Pagination | Cursor-based (limit + starting_after / ending_before), returning has_more and data. See pagination.yaml. |
| Identity headers | The gateway resolves identity from the JWT and injects X-Org-Id, X-User-Id, X-User-Email; client-supplied identity headers are stripped. |
Unified Spec
The complete OpenAPI 3.1 document covering every service in one file:
- hanzo.yaml — all 38 services, one spec
Every individual spec lives in the hanzoai/openapi repository.
How is this guide?
Last updated on