Hanzo Cloud

API reference · Hanzo Cloud API → — every endpoint, generated from the OpenAPI spec.

Hanzo Cloud is the core AI Cloud OS that powers api.hanzo.ai. It provides a unified model gateway (ZAP protocol), knowledge base with RAG, container orchestration, and infrastructure management across the Hanzo ecosystem.

Features

Three Protocols: REST API, MCP (Model Context Protocol), ZAP (Zero-overhead API Protocol)
Model Gateway: One host and one key for inference — enso and Zen served first-party
Knowledge Base: RAG-powered document stores with vector embeddings
Container Cloud: Kubernetes application templates and management
Outside Providers: Connect Anthropic, OpenAI, Fireworks or DO-AI when a workflow needs a specific model
IAM Authentication: OAuth2/OIDC via Hanzo IAM, API keys (hk-*), widget keys (hz-*)
Usage Billing: Per-request metering via Hanzo Commerce API
Rate Limiting: Dynamic tier-based limits (free → enterprise)
Node Management: Remote infrastructure via VNC/RDP

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                        HANZO CLOUD                               │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────────┐    ┌──────────────────────────────┐    │
│  │   ZAP Model Gateway │    │     Knowledge / RAG          │    │
│  │  ┌───────┐ ┌──────┐ │    │  ┌────────┐  ┌───────────┐  │    │
│  │  │enso   │ │OpenAI│ │    │  │ Stores │  │ Vectors   │  │    │
│  │  │Zen    │ │Anthro│ │    │  │ (docs) │  │ (embeds)  │  │    │
│  │  │models │ │Firew.│ │    │  └────────┘  └───────────┘  │    │
│  │  └───────┘ └──────┘ │    └──────────────────────────────┘    │
│  └─────────────────────┘                                        │
│                                                                  │
│  ┌─────────────────────┐    ┌──────────────────────────────┐    │
│  │   Auth & Billing    │    │     Container Cloud          │    │
│  │  ┌───────┐ ┌──────┐ │    │  ┌────────┐  ┌───────────┐  │    │
│  │  │ IAM   │ │Comm. │ │    │  │  K8s   │  │ Templates │  │    │
│  │  │ OIDC  │ │ API  │ │    │  │ Apps   │  │           │  │    │
│  │  └───────┘ └──────┘ │    │  └────────┘  └───────────┘  │    │
│  └─────────────────────┘    └──────────────────────────────┘    │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Endpoints

Environment	URL	Purpose
Production	`https://api.hanzo.ai`	API gateway
Console	`https://console.hanzo.ai`	Admin UI
Lux Cloud	`https://cloud.lux.network`	Lux network instance

Quick Start

Get an API Key

Create an API key at console.hanzo.ai or via the API:

curl -X POST https://api.hanzo.ai/v1/add-token \
  -H "Authorization: Bearer $IAM_TOKEN" \
  -d '{"name": "my-key", "organization": "hanzo"}'

Chat Completion

curl https://api.hanzo.ai/v1/chat/completions \
  -H "Authorization: Bearer hk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zen5-flash",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

SDK Usage

import Hanzo from '@hanzo/ai'

const client = new Hanzo({ apiKey: 'hk-your-api-key' })

const response = await client.chat.completions.create({
  model: 'zen5-flash',
  messages: [{ role: 'user', content: 'Hello' }]
})

Protocols

Hanzo Cloud exposes three protocols for accessing AI services:

Protocol	Transport	Use Case
REST	HTTPS (JSON)	Chat completions, embeddings and model listing over plain JSON
MCP	stdio / SSE	Model Context Protocol — 260+ tools for AI agents (filesystem, search, browser, etc.)
ZAP	WebSocket (binary)	Zero-overhead API Protocol — native binary streaming for low-latency inference

REST

curl https://api.hanzo.ai/v1/chat/completions \
  -H "Authorization: Bearer hk-your-key" \
  -d '{"model": "zen5-flash", "messages": [{"role": "user", "content": "Hello"}]}'

/v1/chat/completions, /v1/embeddings and /v1/models take and return the chat-completions JSON shape, so an HTTP client already written against it works here once its base URL points at https://api.hanzo.ai/v1 and it sends an hk-* key. Model ids do not carry across vendors — zen5 and enso are Hanzo models and resolve only here.

MCP (Model Context Protocol)

npx @hanzo/mcp --api-key hk-your-key

Or configure in your AI client's MCP settings:

{
  "mcpServers": {
    "hanzo": {
      "command": "npx",
      "args": ["@hanzo/mcp", "--api-key", "hk-your-key"]
    }
  }
}

ZAP (WebSocket)

const ws = new WebSocket('wss://api.hanzo.ai/zap')
ws.send(JSON.stringify({
  type: 'chat.completions',
  model: 'zen5-flash',
  messages: [{ role: 'user', content: 'Hello' }]
}))

Authentication

Hanzo Cloud supports multiple auth methods:

Method	Format	Use Case
IAM API Key	`hk-*`	Server-side API access
IAM JWT	Bearer token	User sessions via hanzo.id
Provider Key	`sk-*`	Direct provider passthrough
Widget Key	`hz-*`	Public-facing chat widgets

All auth flows integrate with Hanzo IAM for identity management.

Rate Limits

Tier	Requests/min	Set By
Free	10	Default
Starter	60	Commerce billing
Pro	300	Commerce billing
Enterprise	1000	Commerce billing

KMS Integration

All secrets (provider API keys, database credentials, IAM client secrets) are managed by Hanzo KMS. See KMS Service Integration for the pattern.

Next Steps

Core concepts: providers, stores, vectors, chats

Configure model, storage, and embedding providers

Pointing existing chat clients and SDKs at Hanzo Cloud

Kubernetes application management

Hanzo Cloud

On this page