# 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. 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      # Python
npm install @hanzo/sdk   # TypeScript
```

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

## MCP

The fleet keeps an MCP server at `https://api.hanzo.ai/v1/mcp`, over streamable
HTTP, opened by the same bearer:

```json
{
  "mcpServers": {
    "hanzo": {
      "type": "http",
      "url": "https://api.hanzo.ai/v1/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}
```

It carries one tool per subsystem rather than one per operation, because a tool
list is a prompt and thousands of near-identical entries make a model choose
badly. Call the subsystem's tool, name the operation in `op`, and pass that
operation's own arguments in `input`. The `describe` tool answers with any one
operation's description and input schema, so a session can learn an argument list
without leaving the MCP server.

Tools for the machine you are on — filesystem, shell, code index, git — come from
a different server, `hanzo-mcp`, which the install line above also installs.

## 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.

120 families, 2329 operations, read from https://api.hanzo.ai/v1/openapi.json on 2026-09-16.

### AI

- `/v1/agent` — Autonomous agents for your org: define them, run them, keep every run. (41 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. (296 operations)
- `/v1/prompt` — Your prompt library, versioned, so nothing changes silently. (6 operations)

### 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. (36 operations)
- `/v1/tasks` — Hanzo Tasks: 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. (3 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. (6 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). (8 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. (157 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)

### Infrastructure

- `/v1/project` — Where your sites live: create one, deploy a build, roll back to any release. (57 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. (48 operations)
- `/v1/event` — Product analytics: send an event, read back who did what. (12 operations)
- `/v1/o11y` — Your logs, metrics and traces: ship them in, query them, chart them. (381 operations)
- `/v1/pricing` — The price list: what every model, provider, GPU tier, tool and hosting plan costs. (29 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)
- `/v1/x402` — Pay-per-request over HTTP 402: quote a price, take the payment, serve the resource. (1 operation)

### Apps

- `/v1/bot` — A bot doing your work on a real desktop, live, while you watch. (5 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. (2 operations)

### Rest

- `/v1/account` — Your own account: API keys you mint and revoke, and org onboarding. (10 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. (17 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. (25 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. (179 operations)
- `/v1/company` — Incorporation end to end: pick a structure, add founders, pay, file, and e-sign. (24 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. (20 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/engine` — Hanzo Engine: which models the serving runtime has loaded, and the GPUs under it. (6 operations)
- `/v1/entitlement` — What your org may run: what the plan grants, and which of those products are switched on. (3 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. (4 operations)
- `/v1/flag` — Feature flags: ship it dark, then turn it on for who you pick. (8 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. (9 operations)
- `/v1/guide` — The AI that builds an agentic company with you, one measured step at a time. (19 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. (10 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. (5 operations)
- `/v1/legal` — The paperwork your company needs, drafted, signed and filed. (11 operations)
- `/v1/licensing` — What an org has bought and may run: signed licenses to issue, verify and revoke, and the releases they unlock. (11 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. (35 operations)
- `/v1/marketplace` — The shop for tools and agents: browse, install into your project, publish your own free or priced. (6 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. (4 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/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/provider` — How your org connects third-party accounts like Slack, and revokes them. (56 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. (6 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. (21 operations)
- `/v1/sbom` — What is inside a container image: every component, resolvable by digest or image ref. (2 operations)
- `/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. (2 operations)
- `/v1/social` — Posting to every social account you own, now or on a schedule. (13 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/sync` — Data sync: link two endpoints and keep them in step, on a webhook, on a schedule, or on demand. (6 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. (21 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/todo` — Hanzo Todo: boards, the work items on them, and the filters that make a board. (13 operations)
- `/v1/tool` — Everything your org can call, in one list: connector actions, functions, agents, skills and your own MCP servers. (19 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. (7 operations)
- `/v1/world` — A live news feed filtered to what your project cares about. (6 operations)