Files
skills/public/hanzo-openapi.md

8.0 KiB

Hanzo OpenAPI - Unified API Specification for 26 Cloud Services

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-gateway.md, hanzo/hanzo-cloud.md, hanzo/python-sdk.md, hanzo/js-sdk.md, hanzo/go-sdk.md

Overview

Hanzo OpenAPI is the canonical OpenAPI 3.1.0 specification for all 26 Hanzo Cloud services. One master spec (hanzo.yaml) plus per-service specs, shared schemas, and everything needed to generate SDKs, validate APIs, and render documentation. Version 4.0.0.

Why Hanzo OpenAPI?

  • Single source of truth: Every Hanzo service endpoint, schema, and error is defined here
  • SDK generation: Feed any spec to openapi-generator to produce Python, TypeScript, Go, Rust clients
  • Documentation: Render with Redoc, Scalar, or Swagger UI
  • Validation: Lint specs with @redocly/cli before deploy
  • Gateway routing: Defines the contract that api.hanzo.ai enforces

Spec Format

  • OpenAPI 3.1.0 YAML files
  • Shared components in shared/ (auth, errors, pagination schemas)
  • Master unified spec: hanzo.yaml (33KB, all 26 services combined)
  • Per-service specs: <service>/openapi.yaml

OSS Base

Repo: hanzoai/openapi (1.8MB, 3 stars).

When to use

  • Adding or modifying any Hanzo API endpoint
  • Generating a new SDK client for a language
  • Validating API contracts before deployment
  • Rendering API documentation (docs.hanzo.ai)
  • Understanding the full surface area of Hanzo Cloud

Hard requirements

  1. OpenAPI 3.1.0 compliance for all specs
  2. Shared schemas must be referenced from shared/, not duplicated
  3. All services must appear in the master hanzo.yaml
  4. Auth uses Authorization: Bearer hk-... (API key) or OAuth2 JWT

Quick reference

Item Value
Master Spec hanzo.yaml (33KB)
Spec Version OpenAPI 3.1.0
API Version 4.0.0
Gateway api.hanzo.ai
Docs docs.hanzo.ai
Repo github.com/hanzoai/openapi
Branch main

Services Covered (26)

AI and Intelligence

Service Spec Endpoint
Cloud cloud/openapi.yaml (116KB) api.cloud.hanzo.ai
Chat chat/openapi.yaml hanzo.chat
Search search/openapi.yaml search.hanzo.ai
Bot bot/openapi.yaml app.hanzo.bot
Nexus nexus/openapi.yaml nexus.hanzo.ai
Vector vector/openapi.yaml vector.hanzo.ai

Automation

Service Spec Endpoint
Flow flow/openapi.yaml flow.hanzo.ai
Auto auto/openapi.yaml auto.hanzo.ai
Operative operative/openapi.yaml operative.hanzo.ai

Platform and Identity

Service Spec Endpoint
IAM iam/openapi.yaml hanzo.id
Commerce commerce/openapi.yaml commerce.hanzo.ai
Gateway gateway/openapi.yaml api.hanzo.ai
Console console/openapi.yaml console.hanzo.ai
KMS kms/openapi.yaml kms.hanzo.ai
Analytics analytics/openapi.yaml analytics.hanzo.ai

Infrastructure

Service Spec Endpoint
PaaS paas/openapi.yaml paas.hanzo.ai
Platform platform/openapi.yaml platform.hanzo.ai
DB db/openapi.yaml db.hanzo.ai
KV kv/openapi.yaml kv.hanzo.ai
MQ mq/openapi.yaml mq.hanzo.ai
Edge edge/openapi.yaml edge.hanzo.ai
Registry registry/openapi.yaml oci.hanzo.ai
Visor visor/openapi.yaml vm.hanzo.ai

Operations

Service Spec Endpoint
Engine engine/openapi.yaml engine.hanzo.ai
O11y o11y/openapi.yaml o11y.hanzo.ai
DNS dns/openapi.yaml dns.hanzo.ai
ZT zt/openapi.yaml zt.hanzo.ai

Repository Structure

openapi/
 hanzo.yaml # Master unified spec (all 26 services)
 LLM.md
 README.md
 shared/
 auth.yaml # Auth security schemes (API key, OAuth2, JWT)
 errors.yaml # Shared error response schemas
 pagination.yaml # Cursor/offset pagination schemas
 analytics/openapi.yaml
 auto/openapi.yaml
 bot/openapi.yaml
 chat/openapi.yaml
 cloud/openapi.yaml # Largest spec (116KB) -- LLM inference API
 commerce/openapi.yaml
 console/openapi.yaml
 db/openapi.yaml
 did/openapi.yaml
 dns/openapi.yaml
 edge/openapi.yaml
 engine/openapi.yaml
 flow/openapi.yaml
 gateway/openapi.yaml
 guard/openapi.yaml
 iam/openapi.yaml
 kms/openapi.yaml
 kv/openapi.yaml
 ml/openapi.yaml
 mq/openapi.yaml
 nexus/openapi.yaml
 o11y/openapi.yaml
 operative/openapi.yaml
 paas/openapi.yaml
 platform/openapi.yaml
 pricing/openapi.yaml
 pubsub/openapi.yaml
 registry/openapi.yaml
 s3/openapi.yaml
 search/openapi.yaml
 stream/openapi.yaml
 vector/openapi.yaml
 visor/openapi.yaml
 zt/openapi.yaml

Gateway Routes

All services accessible through api.hanzo.ai:

api.hanzo.ai/v1/chat/completions -> Cloud (LLM inference)
api.hanzo.ai/v1/models -> Cloud (model listing)
api.hanzo.ai/v1/chat/* -> Chat
api.hanzo.ai/v1/search/* -> Search
api.hanzo.ai/v1/bot/* -> Bot
api.hanzo.ai/v1/nexus/* -> Nexus
api.hanzo.ai/v1/vector/* -> Vector DB
api.hanzo.ai/v1/flow/* -> Flow
api.hanzo.ai/v1/operative/* -> Operative
api.hanzo.ai/v1/auth/* -> IAM
api.hanzo.ai/v1/billing/* -> Commerce
api.hanzo.ai/v1/kms/* -> KMS
api.hanzo.ai/v1/console/* -> Console
api.hanzo.ai/v1/analytics/* -> Analytics
api.hanzo.ai/v1/paas/* -> PaaS
api.hanzo.ai/v1/platform/* -> Platform
api.hanzo.ai/v1/db/* -> DB
api.hanzo.ai/v1/kv/* -> KV
api.hanzo.ai/v1/mq/* -> MQ
api.hanzo.ai/v1/edge/* -> Edge
api.hanzo.ai/v1/registry/* -> Registry
api.hanzo.ai/v1/vm/* -> Visor
api.hanzo.ai/v1/engine/* -> Engine
api.hanzo.ai/v1/o11y/* -> O11y
api.hanzo.ai/v1/dns/* -> DNS
api.hanzo.ai/v1/zt/* -> ZT

Authentication

All services use a single HANZO_API_KEY:

curl -H "Authorization: Bearer hk-your-api-key" https://api.hanzo.ai/v1/models
Method Use Case
API Key Server-to-server (Authorization: Bearer hk-...)
OAuth2 + PKCE User-facing apps via @hanzo/iam (hanzo.id/v1/iam/oauth/authorize)
Client Credentials Service-to-service (POST hanzo.id/v1/iam/oauth/token)
JWT After OAuth login (Authorization: Bearer eyJ...)

Common Operations

Validate All Specs

for spec in */openapi.yaml; do
 echo "Validating $spec..."
 openapi-generator validate -i "$spec"
done

# Master spec
npx @redocly/cli lint hanzo.yaml

Generate SDK from Spec

# Python
openapi-generator generate -i hanzo.yaml -g python -o clients/python

# TypeScript
openapi-generator generate -i hanzo.yaml -g typescript-axios -o clients/typescript

# Go
openapi-generator generate -i hanzo.yaml -g go -o clients/go

# Rust
openapi-generator generate -i hanzo.yaml -g rust -o clients/rust

Serve Docs Locally

npx @redocly/cli preview-docs hanzo.yaml # Redoc
npx @scalar/cli serve hanzo.yaml # Scalar
docker run -p 8080:8080 -e SWAGGER_JSON=/specs/hanzo.yaml \
 -v $(pwd):/specs swaggerapi/swagger-ui # Swagger UI

Open Source Orgs

GitHub Org Focus
@hanzoai Core platform (all 26 services)
@hanzozt Zero-trust networking
@hanzo-ml GPU/ML (kubeflow, kuberay)
@hanzodns DNS (coredns)
@hanzofn Edge functions (edge-runtime)
@hanzosql Databases (neon)
@hanzokv Key-value store (valkey)
@hanzocr Container registry (harbor)
@hanzomsg Messaging (nats-server, nats.go, nats.js, nats.py)
@hanzoo11y Observability (loki, grafana, clickhouse)
  • hanzo/hanzo-gateway.md - API gateway that enforces these specs
  • hanzo/hanzo-cloud.md - LLM inference (largest spec)
  • hanzo/python-sdk.md - Python SDK (generated from these specs)
  • hanzo/js-sdk.md - JavaScript SDK
  • hanzo/go-sdk.md - Go SDK
  • hanzo/rust-sdk.md - Rust SDK
  • hanzo/hanzo-sdk.md - Unified multi-language CLI SDK

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: openapi, api-specification, sdk-generation, documentation Prerequisites: OpenAPI 3.1.0 familiarity, REST API basics