# Hanzo

> What Hanzo Cloud serves and how to call it, written for an agent working in
> someone else's codebase.

One host answers for the whole platform, `https://api.hanzo.ai`, and one
credential opens it. Starting from nothing (no account, no key)? With a wallet
and no human, https://hanzoskills.com/hanzo.md signs in, mints a key, makes a
free call and tops up in USDC or USDT (the same file is drawn at
https://hanzo.ai/agents#headless). Otherwise read https://docs.hanzo.ai/docs/agents
first: sign-up over HTTP, the free tier, the
first call and how to pay. The section at the end lists every family the host serves;
it is read out of the API's own document on each build, so it cannot describe an
API that has moved on.

## Operate

- Work in the project you were asked about. Check which directory you are in
  before you write a file into it.
- The base is `https://api.hanzo.ai/v1`. `api` is the host, so `/api/` never
  appears in a path: `/v1/models`, not `/api/v1/models`.
- Call operations that exist. All of them are in the document at
  `https://api.hanzo.ai/v1/openapi.json`; a path absent from it answers 404.
  Never build a path out of a family name and a guess about the rest.
- `GET /v1/commands` is the same surface as a flat list — every operation with
  its method, its path, its summary and the arguments it takes. Read it when you
  need an exact one. Neither it nor the document asks for a credential.
- Say what a call returned, status included, and never report a call you did not
  make.

## Authenticate

Hanzo IAM issues the credential. One login, one bearer, and that one bearer opens
every family listed at the end.

```sh
hanzo auth login                          # opens a browser, once per machine
export HANZO_TOKEN="$(hanzo auth token)"  # prints the bearer on stdout, alone
```

Send it on every call:

```sh
curl -sS https://api.hanzo.ai/v1/billing/balance \
  -H "Authorization: Bearer $HANZO_TOKEN"
```

Check two different things, because one call cannot answer both.

`GET /v1/models` proves the **host and the path**. It carries no credential —
the document declares it open — and answers `200` with the model list whether or
not you send a bearer. `404` there means your path is wrong.

`GET /v1/billing/balance` proves the **credential**: `401` without a bearer,
`200` with a good one. Never test a token against a route that does not require
one; it will pass while your token is worthless.

And do not read `200` alone as success. Some IAM routes answer `200` carrying
`{"status":"error","msg":"please sign in first"}` in the body, so an agent that
only reads status codes will believe it is signed in when it is not. Read the
body.

## Install

The CLI, by the one line every Hanzo surface prints for it:

```sh
curl -fsSL https://hanzo.sh | sh
```

It puts `hanzo` in `~/.local/bin`, alongside `hanzo-mcp` and the `dev` agent. On
npm the same CLI is `@hanzo/cli`.

From code, one client per language, generated from the same document as this
file:

```sh
pip install "hanzoai>=8"   # Python 3.12+
npm i hanzoai              # TypeScript
```

The rest are at <https://hanzo.ai/sdks>.

## MCP

The MCP server to install is `@hanzo/mcp`, over stdio. One line adds it to
Claude Code; Codex, Cursor and Zed take the same command in their own config
(https://docs.hanzo.ai/docs/agents):

```sh
claude mcp add hanzo --env HANZO_API_KEY=$HANZO_API_KEY -- npx -y --package=@hanzo/mcp@latest hanzo-mcp serve
```

Name the package and the binary separately: in `npx -y @hanzo/mcp serve`, npx
reads `serve` as a second package. The server carries the Kai decision tools
(`kai_decide`, `kai_choice`, `kai_score`, `kai_noul` and more) beside files,
shell, git, code search and the browser, and calls api.hanzo.ai with
`HANZO_API_KEY`.

The fleet also answers MCP at `https://api.hanzo.ai/v1/mcp`: stateless JSON-RPC
over POST, one tool per subsystem plus `describe`, with the operation named in
`op` and its arguments in `input`; `tools/call` takes the same bearer. It
answers `initialize` with protocol revision 2026-07-28 only, so a client that
does not speak that revision (Claude Code 2.1 among them) refuses to connect;
use the local server there.

## Families

The document tags every operation by the first segment after `/v1/`, and that
segment is the family. Each line below is a tag the document declares, the
sentence is its own, and the count is how many operations carry it. Headings are
the categories Hanzo's catalog places a family in; `Rest` holds every family the
catalog sells no product for, and they answer exactly the same way.

129 families, 2570 operations, read from https://api.hanzo.ai/v1/openapi.json on 2026-10-30.

### AI

- `/v1/agent` — Autonomous agents for your org: define them, run them, keep every run. (60 operations)
- `/v1/ai` — Hanzo AI — the model API on /v1 (/v1/chat/completions, /v1/messages, /v1/models and the rest of hanzoai/ai's surface) — mounted into a cloud binary with the money, ingest and telemetry callbacks cloud BUILDS but cannot INSTALL. (313 operations)
- `/v1/prompt` — Your prompt library, versioned, so nothing changes silently. (6 operations)

### Science

- `/v1/benchmark` — One honest score for any model, on the tests everyone quotes. (9 operations)
- `/v1/eval` — Scoring a model on your own data, with a judge you choose. (16 operations)
- `/v1/experiment` — A/B testing anything: a flag, an ad, a subject line, a model. (7 operations)
- `/v1/search` — One ranked result set over everything your org has stored. (1 operation)

### Compute

- `/v1/compute` — The compute you rent from Hanzo: machines, GPUs and clusters — launch one, resize it, tear it down. (30 operations)
- `/v1/function` — Your serverless code: publish it, call it over HTTP, watch every run and what it cost. (11 operations)
- `/v1/platform` — Hanzo PaaS: deploy containers to your own tenant namespace — builds, releases, environments, logs, custom domains. (39 operations)
- `/v1/workflow` — Hanzo Workflow: durable workflows that survive a crash, with every run visible and replayable. (5 operations)

### Data

- `/v1/base` — Managed Hanzo Base: a hosted backend for your app — collections, records, access rules and sign-in. (5 operations)
- `/v1/provisioning` — One-click data add-ons: a SQL, key-value, document, vector, search or object store, wired straight into your app. (28 operations)
- `/v1/s3` — Object storage: your buckets and the files in them, with signed URLs for upload and download. (11 operations)

### Network

- `/v1/dns` — Your DNS records: the zones and records behind every name you point at Hanzo. (12 operations)
- `/v1/gateway` — Live control of the policy your API applies to every incoming request: CORS, rate limits, cache TTL and allowed methods, changed without a redeploy. (3 operations)
- `/v1/network` — Mounts the Hanzo Cloud NETWORKING surface: the tenant's Hanzo Zero Trust footprint — the overlay network, its routers and its services — served as clean, org-scoped REST off the unified cloud binary and fronting the Hanzo Zero Trust controller (hanzoai/zt, an ZT-based fabric). (9 operations)
- `/v1/validator` — One-click validator onboarding: prove your Genesis NFT, get a node provisioned, queue its registration. (4 operations)

### Security

- `/v1/authz` — The access decision behind an org-scoped call: who may do what, where, answered allow or deny. (3 operations)
- `/v1/iam` — Hanzo's identity provider: users, organizations, applications, and the OIDC/OAuth2 endpoints every Hanzo service authenticates against. (166 operations)
- `/v1/kms` — Secret custody: your org's secrets sealed at rest, plus threshold signing. (5 operations)

### Dev

- `/v1/code` — Search and symbols across your repos, for you and your agents. (7 operations)
- `/v1/provider` — How your org connects third-party accounts like Slack, and revokes them. (77 operations)

### Infrastructure

- `/v1/project` — Where your sites live: create one, deploy a build, roll back to any release. (30 operations)
- `/v1/registry` — Your container and package registry: push images, pull them back, see what you store. (6 operations)

### Observe

- `/v1/billing` — Your org's balance, what it has spent, and the cards it pays with. (54 operations)
- `/v1/event` — Product analytics: send an event, read back who did what. (13 operations)
- `/v1/o11y` — Your logs, metrics and traces: ship them in, query them, chart them. (341 operations)
- `/v1/pricing` — The price list: what every model, provider, GPU tier, tool and hosting plan costs. (26 operations)

### Web3

- `/v1/explorer` — Chain data: your block indexers and how far each has caught up, plus the on-chain price feeds. (2 operations)
- `/v1/wallet` — Blockchain key custody: create wallets, rotate their keys, and sign with them. (8 operations)
- `/v1/web3` — The chain-access surface: which chains this deployment can reach, a JSON-RPC endpoint onto each, and the two token reads every wallet UI needs. (4 operations)

### Apps

- `/v1/bot` — A bot doing your work on a real desktop, live, while you watch. (4 operations)
- `/v1/crawl` — Any web page turned into clean markdown a model can read. (1 operation)
- `/v1/referral` — Referral ATTRIBUTION: who referred whom, and whether that referee ever became a real customer. (3 operations)

### Rest

- `/v1/account` — Your own account: API keys you mint and revoke, and org onboarding. (11 operations)
- `/v1/ad` — Your paid ad campaigns, launched and paused from one place. (7 operations)
- `/v1/affiliate` — A partner program that pays commission on what your referrals spend. (10 operations)
- `/v1/allowance` — How much a plan lets you do without paying, and how much of it you have left today. (1 operation)
- `/v1/ask` — A plain-language question about your business, answered with real numbers. (2 operations)
- `/v1/audit` — Your org's tamper-evident audit trail: every security-relevant event, hash-chained and readable. (1 operation)
- `/v1/author` — A royalty for open-source work: your repo runs, you get paid. (5 operations)
- `/v1/auto` — Workflows that run themselves, on a schedule or a webhook. (30 operations)
- `/v1/blueprint` — What a template costs to run, worked out before you deploy. (3 operations)
- `/v1/books` — Double-entry accounting: chart of accounts, ledger, bank reconciliation, and the reports that prove the books balance. (23 operations)
- `/v1/campaign` — One go-to-market push across paid, organic and email at once. (11 operations)
- `/v1/captable` — Your cap table: stakeholders, share classes, grants, SAFEs, rounds, and who owns what. (31 operations)
- `/v1/catalog` — One place to browse every project, app and site built here. (1 operation)
- `/v1/channel` — One inbox for the chat apps you connect — Discord, Slack, Teams, Telegram. (9 operations)
- `/v1/ci` — Mounts the CI fleet dashboard as a capability of this binary. (2 operations)
- `/v1/cloudflare` — Your Cloudflare account, managed from Hanzo: zones, Pages, Workers, Workers AI, R2, KV and D1. (32 operations)
- `/v1/commerce` — Selling: checkout, subscriptions, invoices, spend alerts, payment webhooks and the storefront catalog. (157 operations)
- `/v1/company` — Incorporation end to end: pick a structure, add founders, pay, file, and e-sign. (23 operations)
- `/v1/compliance` — Your KYC/KYB onboarding, accreditation records, and the evidence trail behind them. (17 operations)
- `/v1/content` — Marketing content from draft to published, on every channel. (6 operations)
- `/v1/dataroom` — A secure document room you share by link and watch page by page. (26 operations)
- `/v1/dataset` — The per-org dataset plane of /v1/risk: a dataset is a VERSIONED, IMMUTABLE snapshot of one tenant's own event surface, and this is where it is declared, materialised, described, exported and disposed of. (7 operations)
- `/v1/deploy` — Hanzo CD: see what each app is running, sync it, and roll back a bad release. (14 operations)
- `/v1/destination` — Your events forwarded to the ad and analytics tools you use. (5 operations)
- `/v1/domain` — Hanzo Domains: search a name, see the price, buy it from your prepaid wallet. (7 operations)
- `/v1/email` (8 operations)
- `/v1/engine` — Hanzo Engine: which models the serving runtime has loaded, and the GPUs under it. (4 operations)
- `/v1/entitlement` — What your org may run: what the plan grants, and which of those products are switched on. (3 operations)
- `/v1/environment` — What a codebase is before its agent starts: the commands that install it, the command that starts it, and the secrets it reads. (6 operations)
- `/v1/esign` — A document out for signature, signed and filed with an audit trail. (13 operations)
- `/v1/exec` — The code interpreter: run a snippet in a sandbox, and move files in and out of the session that sandbox IS. (3 operations)
- `/v1/flag` — Feature flags: ship it dark, then turn it on for who you pick. (12 operations)
- `/v1/flow` — Hanzo Flow: build an agent workflow on a visual canvas, run it, and read every run. (8 operations)
- `/v1/framework` — Document types you define: describe a record once, then create, list, submit and cancel documents against it. (16 operations)
- `/v1/git` — Git hosting for your org: create repos, clone, push, and see what they cost. (51 operations)
- `/v1/graph` — One organization's entities and the relations between them, held as assertions: somebody, at some moment, from some evidence, asserted that this thing stands in that relation to that other thing. (16 operations)
- `/v1/guide` — The AI that builds an agentic company with you, one measured step at a time. (15 operations)
- `/v1/help` — A support desk: customers file tickets, your team answers them. (4 operations)
- `/v1/index` — Fast full-text search over your own data, typos forgiven. (17 operations)
- `/v1/ingress` — Your edge: automatic TLS certificates and hostname routing to any backend, changed live. (18 operations)
- `/v1/knowledge` — Your team's wiki and your agents' memory, searchable by meaning. (19 operations)
- `/v1/kv` — Your key-value store: buckets of versioned values your apps read and write by key. (6 operations)
- `/v1/label` — The ground-truth plane: what actually turned out to be fraud, who said so, and when they could first have said it. (7 operations)
- `/v1/leaderboard` — The ranking of who uses AI most, in your org and globally. (6 operations)
- `/v1/legal` — The paperwork your company needs, drafted, signed and filed. (11 operations)
- `/v1/library` — The Library: everything a person made, in one place. (6 operations)
- `/v1/licensing` — What an org has bought and may run: signed licenses to issue, verify and revoke, and the releases they unlock. (9 operations)
- `/v1/link` — The unified AI login manager's registry: the org+user-scoped record of WHICH provider accounts (Claude Max, ChatGPT Plus, a Hanzo API key, a raw provider key) a developer has signed into, ON WHICH MACHINES, with each account's latest usage snapshot. (11 operations)
- `/v1/lsp` — Live semantic code intelligence — definitions, references, types, hover, outline and diagnostics — over a repository AND its resolved dependencies, with no toolchain on the caller's machine. (5 operations)
- `/v1/market` — What trades on each chain, and how far the read of it got. (5 operations)
- `/v1/marketing` — Lifecycle email: drip sequences that reach the right people. (50 operations)
- `/v1/marketplace` — The one market between orgs: agents and personas to hire, apps, skills, MCP servers and tools to buy, each sold by the org that owns it, and the two-sided work one org buys from another. (23 operations)
- `/v1/meet` — The virtual office: it decides who may join a room and mints the short-lived token that lets them in. (7 operations)
- `/v1/metrics` (11 operations)
- `/v1/ml` — Model serving: deploy a model behind an endpoint and call it. (7 operations)
- `/v1/mq` — Queue and stream admin for your org: create them, watch them drain, ack what you pulled. (15 operations)
- `/v1/node` — Your machines: the ones you own, connected and ready to take a command. (4 operations)
- `/v1/notify` — Transactional email and SMS, sent through your org's own provider credential. (6 operations)
- `/v1/openapi` — The served contract: the OpenAPI document every client, tool list and command group is generated from, its command projection, the agent endpoint that offers the same operations over MCP, and the index a client follows from the API root to reach any of it. (5 operations)
- `/v1/patent` — The record of who thought of what, and when the machine was asked to write it. (12 operations)
- `/v1/patrol` — Stands watch over an estate: sites, units, tours, keys, cameras, and the incidents that interrupt them. (29 operations)
- `/v1/plan` — The plan catalog: every tier you can buy, what it costs, and what it grants. (14 operations)
- `/v1/pref` — Your own settings — theme, density, pinned nav — following you across every Hanzo app. (2 operations)
- `/v1/principal` — Serves an org as an economic principal: who it is, what it may pay, and which agents answer to it. (7 operations)
- `/v1/pubsub` — Your message bus: publish, subscribe, and durable streams your apps read at their own pace. (2 operations)
- `/v1/reference` — The lookup data a risk decision needs but cannot derive: which email domains hand out throwaway inboxes, which addresses belong to a datacentre or a Tor exit, which card scheme an issuer prefix belongs to, which browsers the fleet sees everywhere, and how current the designation lists the screening engine holds actually are. (5 operations)
- `/v1/risk` — HANZO RISK's model plane: the per-organisation feature surface and the per-organisation models trained on it. (11 operations)
- `/v1/sandbox` — The ONE compute primitive: a sandbox is a gVisor pod that runs somebody else's code, and every lifetime is the same object. (23 operations)
- `/v1/sbom` — What is inside a container image: every component, resolvable by digest or image ref. (1 operation)
- `/v1/security` — Secret scanning for your code: submit sources, get findings, masked never raw. (7 operations)
- `/v1/seo` — Search visibility as data: what a phrase is worth, what a site already places for, who places beside it, who links to it, and what one page gets wrong. (7 operations)
- `/v1/settings` — How an org configures each product it uses, secret fields included. (2 operations)
- `/v1/share` — A public URL for a service on your own machine, and a list of what you have open. (3 operations)
- `/v1/social` — Posting to every social account you own, now or on a schedule. (15 operations)
- `/v1/space` — Where work lives: drives, folders and the files in them. (7 operations)
- `/v1/standing` — Prices and tracks what it costs to KEEP a company, as distinct from what it cost to form one. (1 operation)
- `/v1/studio` — Hanzo Studio's workflow backend: every creation — an image, a poster, a document, a deck, a type system, a 3D model, an ad, a film, a voice, a song — is a run of a graph of steps that the person who started it owns. (34 operations)
- `/v1/sync` — Data sync: link two endpoints and keep them in step, on a webhook, on a schedule, or on demand. (6 operations)
- `/v1/task` — Hanzo Task: boards, the work items on them, and the filters that make a board. (14 operations)
- `/v1/tax` — How companies formed on Hanzo exchange W-9s, W-8s and 1099s with each other, from the payments that moved between them on Hanzo's rails. (28 operations)
- `/v1/taxonomy` — The product catalogue's shape: which categories exist, what each product is called, which category it sits in, what it is tagged with, and the order the two are shown in. (5 operations)
- `/v1/team` — Your org's shared space: documents edited together, files, seats, and agents as teammates. (45 operations)
- `/v1/tel` — The telecommunications surface: phone numbers, calls and messages, on whatever carrier the deployment is configured for. (10 operations)
- `/v1/template` — A gallery of starter kits you can deploy as they come. (5 operations)
- `/v1/tool` — Everything your org can call, in one list: connector actions, functions, agents, skills and your own MCP servers. (19 operations)
- `/v1/train` — The cloud's one training endpoint, /v1/train (HIP-1333): clients the caller drives on the engine, and jobs the org's linked machines or Hanzo's executor run, whose adaptation, protection, objective and output are fields and whose artifacts, bases and evaluations are what they produce. (35 operations)
- `/v1/translate` — Text in, the same text out in the language you asked for. (3 operations)
- `/v1/treasury` — The reserve fund behind every payout: real capital, held and accounted for. (2 operations)
- `/v1/trust` — Your trust centre: the controls you publish, the coverage they compute to, the documents a reviewer asks for, and who you send data to. (17 operations)
- `/v1/usage` — What your org ran and what it cost, broken down per account. (5 operations)
- `/v1/webhook` — How your app hears about events: register an endpoint, pick the events, get each one delivered and signed. (8 operations)
- `/v1/websearch` — A web search and a page fetch your agents can call. (11 operations)
- `/v1/world` — A live news feed filtered to what your project cares about. (6 operations)
- `/v1/x402` — Pay-per-request over HTTP 402: quote a price, take the payment, serve the resource. (2 operations)