mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
8.0 KiB
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-generatorto produce Python, TypeScript, Go, Rust clients - Documentation: Render with Redoc, Scalar, or Swagger UI
- Validation: Lint specs with
@redocly/clibefore deploy - Gateway routing: Defines the contract that
api.hanzo.aienforces
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
- OpenAPI 3.1.0 compliance for all specs
- Shared schemas must be referenced from
shared/, not duplicated - All services must appear in the master
hanzo.yaml - 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) |
Related Skills
hanzo/hanzo-gateway.md- API gateway that enforces these specshanzo/hanzo-cloud.md- LLM inference (largest spec)hanzo/python-sdk.md- Python SDK (generated from these specs)hanzo/js-sdk.md- JavaScript SDKhanzo/go-sdk.md- Go SDKhanzo/rust-sdk.md- Rust SDKhanzo/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