Machines
Per-org cloud machine lifecycle
Per-org cloud machine lifecycle
| Base URL | https://api.hanzo.ai |
| Operations | 11 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Bindings
Get a machine's agent binding
GET /v1/machines/{id}/agent-binding
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Unbind the agent from a machine
DELETE /v1/machines/{id}/agent-binding
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Bind a cloud Agent to a machine
POST /v1/machines/{id}/bind-agent
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
agentName | string | yes | |
botVersion | string | — |
machines
Returns the agent binding of one of the caller org's machines, or 404 when the machine runs no bot runtime.
GET /v1/machines/{id}/agent
Returns the agent binding of one of the caller org's machines, or 404 when the machine runs no bot runtime.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the machine's org-scoped NAME — the stable key Visor addresses a machine by (owner/name), not the ephemeral provid |
Binds a cloud Agent to one of the caller org's machines: the machine is recorded as running that Agent's @hanzo/bot runtime.
PUT /v1/machines/{id}/agent
Binds a cloud Agent to one of the caller org's machines: the machine is recorded as running that Agent's @hanzo/bot runtime. The owning org is the validated tenant, never a client field.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the machine to bind, from the URL path. |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
agentName | string | — | AgentName is the cloud Agent (/v1/agents) the machine will run. |
botVersion | string | — | BotVersion pins the @hanzo/bot runtime version; empty takes the default. |
id | string | — | ID is the machine to bind, from the URL path. |
Detaches the agent runtime from one of the caller org's machines.
DELETE /v1/machines/{id}/agent
Detaches the agent runtime from one of the caller org's machines. The machine stays — this halts the bot, it does not terminate the compute. Answers 204.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the machine's org-scoped NAME — the stable key Visor addresses a machine by (owner/name), not the ephemeral provid |
Returns one of the caller org's machines by its org-scoped name.
GET /v1/machines/{id}
Returns one of the caller org's machines by its org-scoped name. Visor keys the lookup by owner/name, so an id belonging to another tenant resolves to not-found rather than another org's machine.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the machine's org-scoped NAME — the stable key Visor addresses a machine by (owner/name), not the ephemeral provid |
Terminates one of the caller org's machines.
DELETE /v1/machines/{id}
Terminates one of the caller org's machines. Visor takes the machine identity as owner+name, and the owner is the validated principal, so a caller can only ever terminate its own tenant's machine. Answers 204.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the machine's org-scoped NAME — the stable key Visor addresses a machine by (owner/name), not the ephemeral provid |
Returns every agent↔machine binding in the caller's org — which machines are running which cloud Agent, with vm's own reconciled status.
GET /v1/machines/agents
Returns every agent↔machine binding in the caller's org — which machines are running which cloud Agent, with vm's own reconciled status.
Returns every machine the caller's org has — Visor's registry, the live DigitalOcean droplets and the DOKS worker nodes (deduped into one union), plus the BYO machines that dialed in via hanzo link (provider "byo").
GET /v1/machines
Returns every machine the caller's org has — Visor's registry, the
live DigitalOcean droplets and the DOKS worker nodes (deduped into one union),
plus the BYO machines that dialed in via hanzo link (provider "byo").
A source Visor cannot answer for is logged and skipped, never an error: one wedged upstream must not hide the machines the other sources can see.
Launch a machine (or dryRun for a price quote)
POST /v1/machines
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | — | |
size | string | — | Machine size slug (or use instanceType) |
instanceType | string | — | |
region | string | — | |
dryRun | boolean | — | When true, return a price quote and spend nothing |
How is this guide?