Cloud
Package venue is bring your own cloud: link a DigitalOcean, AWS or GCP account and its clusters show up ready to run work.
Package venue is bring your own cloud: link a DigitalOcean, AWS or GCP account and its clusters show up ready to run work.
| Base URL | https://api.hanzo.ai |
| Operations | 5 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
cloud
POST /v1/cloud/{provider}/accounts/{label}/sync
Re-discovers one already-linked cloud account and reconciles what it folded: kubeconfigs are refreshed, clusters that appeared since the last sync are folded, and clusters this account folded that the provider no longer returns are detached — only this account's own, in the fleet shard it was linked into.
It is idempotent, it reads the credential already sealed at link time, and a discovery failure leaves the existing fold set alone rather than mass-detaching it. An account this org has not linked is not found. Requires org admin.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | string | yes | Provider is the cloud the account belongs to: digitalocean, aws, gcp or azure. |
label | path | string | yes | Label is the org-chosen name of the account within that provider. |
DELETE /v1/cloud/{provider}/accounts/{label}
Forgets one linked cloud account: it detaches every fleet cluster THIS account folded (its own names, in its own shard — a neighbour's cluster of the same name is untouched), deletes the sealed credential, and drops the index row.
It is idempotent and deliberately not an existence oracle: an account this org does not hold answers exactly the same as one it just removed. A cluster that fails to detach is logged and the unlink continues, so a dead provider cannot strand a credential. Requires org admin.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | string | yes | Provider is the cloud the account belongs to: digitalocean, aws, gcp or azure. |
label | path | string | yes | Label is the org-chosen name of the account within that provider. |
POST /v1/cloud/{provider}/accounts
Links one of the caller org's cloud accounts and folds the Kubernetes clusters it finds there into the ONE Hanzo fleet, so they appear at /v1/clusters and can run work like any managed or bring-your-own cluster. Answers 201.
The credential is verified LIVE against the provider BEFORE anything is stored, so a bad one is refused and nothing is written; it is then sealed in the org's own KMS namespace and never appears in a response, the account index, or a log line. Discovery follows, and a cluster that fails to fold is reported as DATA in the clusters list rather than failing the link.
Re-linking a label that already exists re-seals its credential and re-folds it, so this is how a rotated token is replaced. Requires org admin.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | string | yes | Provider is the cloud being linked, from the path: digitalocean, aws, gcp or azure. |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
clientId | string | — | ClientID is the Azure AD application id. |
clientSecret | string | — | ClientSecret selects the service-principal flow. |
credentialJson | string | — | CredentialJSON is a Google credentials document — an external_account (workload identity federation, keyless) or a… |
externalId | string | — | ExternalID pins that role assumption to Hanzo, which is what closes the confused-deputy hole. |
label | string | — | Label is the org-chosen name for this account within the provider, which is how a second account at the same provider… |
projectIds | string[] | — | ProjectIDs bounds the GKE cluster sweep. |
provider | string | — | Provider is the cloud being linked, from the path: digitalocean, aws, gcp or azure. |
regions | string[] | — | Regions bounds the AWS EKS cluster sweep. |
roleArn | string | — | RoleARN is the AWS role Hanzo assumes into the account — the keyless path, so no access key is ever stored. |
subscriptionIds | string[] | — | SubscriptionIDs bounds the AKS cluster sweep. |
tenantId | string | — | TenantID is the Azure AD tenant of the app. |
token | string | — | Token is the DigitalOcean personal access token. |
GET /v1/cloud/accounts
Lists the caller org's linked cloud accounts across every provider: which account each one is at the provider, which fleet clusters it folded, and when it was last discovered. Metadata only — a sealed credential never appears in a response. Another org's accounts are not visible and not countable.
GET /v1/cloud
Returns the clouds this deployment can link and what linking each one needs — the DigitalOcean token, the AWS role and external id, the GCP credential JSON, the Azure app — plus whether the provider can be linked without storing any long-lived secret. It is the catalog a "connect a cloud" screen renders; it reports no account and no credential.
How is this guide?
Chat
Package ai is 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…
Cloudflare
Package cloudflare is your Cloudflare account, managed from Hanzo: zones, Pages, Workers, Workers AI, R2, KV and D1.