Clusters
Package visor is the compute you rent from Hanzo: machines, GPUs and clusters — launch one, resize it, tear it down.
Package visor is the compute you rent from Hanzo: machines, GPUs and clusters — launch one, resize it, tear it down.
| Base URL | https://api.hanzo.ai |
| Operations | 6 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
clusters
POST /v1/clusters/{clusterId}/pools/{poolId}/scale
Resizes a node pool to an absolute node count and returns the pool as Visor reports it after the change.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
clusterId | path | string | yes | ClusterID and PoolID address the pool, from the URL path. |
poolId | path | string | yes |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
clusterId | string | — | ClusterID and PoolID address the pool, from the URL path. |
count | integer | — | Count is the node count to scale TO — an absolute target, not a delta, and never negative. |
poolId | string | — | |
provider | string | — | Provider is the cloud the cluster lives on. |
DELETE /v1/clusters/{clusterId}/pools/{poolId}
Removes a node pool from one of the caller org's clusters. The owner scopes the delete to the caller's tenant; provider+clusterId drive the provider-side removal. Answers 204.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
clusterId | path | string | yes | ClusterID and PoolID address the pool, from the URL path. |
poolId | path | string | yes | |
provider | query | string | — | Provider is the cloud the cluster lives on, from ?provider=. |
POST /v1/clusters/{clusterId}/pools
Adds a node pool to one of the caller org's clusters and answers 201 with the created pool. Only the CreateNodePoolSpec fields are forwarded; owner/provider/clusterId ride in the query exactly as Visor expects them.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
clusterId | path | string | yes | ClusterID is the cluster to add the pool to, from the URL path. |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
autoScale | boolean | — | AutoScale turns the provider's cluster autoscaler on for this pool. |
clusterId | string | — | ClusterID is the cluster to add the pool to, from the URL path. |
count | integer | — | Count is how many nodes the pool starts with. |
maxNodes | integer | — | |
minNodes | integer | — | MinNodes and MaxNodes bound the autoscaler; they are ignored unless AutoScale is set. |
name | string | — | Name is the pool's name. |
provider | string | — | Provider is the cloud the cluster lives on (e.g. "digitalocean"). Required — Visor routes the create by it. |
size | string | — | Size is the provider size slug for each node (e.g. |
DELETE /v1/clusters/{id}
Removes a BYO cluster from the caller org's fleet. It only ever touches BYO clusters — a managed cluster's nodes are removed through the node-pool routes — and answers 404 when the name is not in this org's fleet.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the cluster's fleet name (the name it was attached under), matched lower-cased. |
GET /v1/clusters
Returns the caller org's clusters from both sources: the managed clusters projected from Visor's node pools, and the BYO clusters attached to the caller's project. A Visor outage costs the managed half only — the BYO half still lists, because a page that 502s on an optional provider is worse than a page that shows what it can.
POST /v1/clusters
Attaches a BYO cluster to the caller's org — the kubeconfig is validated, KMS-sealed and added to the fleet — and answers 201 with the cluster as it now appears on GET /v1/clusters. Billed the nominal management fee: the customer brings the compute, Hanzo meters the management plane.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
default | boolean | — | Default marks this the org's default cluster for scheduling. |
kubeconfig | string | — | Kubeconfig is the cluster's kubeconfig, verbatim. |
name | string | — | Name is the fleet-local name for the cluster; lower-cased, and the key the detach route addresses it by. |
provider | string | — | Provider is a free-form label for where the cluster runs ("gke", "on-prem"); it is display only, not a routing key. |
How is this guide?