OpenapiAgents
Updates one machine in place.
Updates one machine in place. Every field is optional; a field the request omits is left alone.
PATCH /v1/agents/targets/{id}
| Address | https://api.hanzo.ai/v1/agents/targets/{id} |
| Method | PATCH |
| Operation | patch_agents_targets_by_id |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Updates one machine in place. Every field is optional; a field the request omits is left alone. A metrics patch IS a heartbeat — the server stamps its own clock, so a client can neither forge nor backdate staleness.
Request
24 fields, body application/json (required).
| Field | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the target to update, from the path. |
capacity | body | string | — | Capacity rewrites the human summary, up to 256 characters. |
host | body | string | — | Host re-points the hostname sessions are matched by. |
id | body | string | — | ID is the target to update, from the path. |
kind | body | string | — | Kind re-files it under laptop | cloud | gpu | cluster | machine. |
label | body | string | — | Label renames the machine, up to 128 characters. |
metrics | body | Metrics | — | |
metrics.at | body | integer | — | unix seconds, server-stamped |
metrics.gpuUtil | body | number | — | 0..1 aggregate utilization |
metrics.load1 | body | number | — | Load1 is the machine's own one-minute load average — a count of runnable and uninterruptible tasks, NOT a percentage and NOT already divided by core count, so… |
metrics.load5 | body | number | — | Load5 is the same figure averaged over five minutes. |
metrics.load15 | body | number | — | Load15 is the same figure over fifteen. The three together are what separate a machine that is busy right now from one that has been busy all along — which is… |
metrics.memFree | body | integer | — | bytes |
metrics.memUsed | body | integer | — | bytes |
spec | body | Spec | — | |
spec.arch | body | string | — | amd64 | arm64 | ... |
spec.cpus | body | integer | — | logical cores |
spec.gpus | body | GPU[] | — | GPUs is every accelerator the machine advertises, one entry each, capped at 32 on write. |
spec.gpus[].memory | body | integer | — | VRAM bytes, 0 = unknown |
spec.gpus[].model | body | string | — | "GB10", "8060S", "RTX 4090" |
spec.gpus[].vendor | body | string | — | nvidia | amd | apple | intel | ... |
spec.memory | body | integer | — | total RAM, bytes |
spec.os | body | string | — | linux | darwin | windows |
status | body | string | — | Status sets operator INTENT: online | offline | draining. Draining is how a machine is taken out of dispatch without ending what is already on it. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | targetView | ok |
200 body — 28 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
capacity | body | string | — | Capacity is a human summary of what the machine has ("8 vCPU / 32G", "1× GB10"), up to 256 characters. |
createdAt | body | string | — | CreatedAt is when the machine was first registered, RFC 3339 in UTC. |
host | body | string | — | Host is the hostname sessions on this machine report, and it is a JOIN KEY, not a label: a session naming this host counts against the load below even when it… |
id | body | string | — | ID is the machine's handle, minted as "tgt_" + 32 hex characters. |
kind | body | string | — | Kind is what sort of destination this is, from a closed five: laptop | cloud | gpu | cluster | machine. |
label | body | string | — | Label is the name a person gave the machine ("workshop"), up to 128 characters. |
metrics | body | Metrics | — | |
metrics.at | body | integer | — | unix seconds, server-stamped |
metrics.gpuUtil | body | number | — | 0..1 aggregate utilization |
metrics.load1 | body | number | — | Load1 is the machine's own one-minute load average — a count of runnable and uninterruptible tasks, NOT a percentage and NOT already divided by core count, so… |
metrics.load5 | body | number | — | Load5 is the same figure averaged over five minutes. |
metrics.load15 | body | number | — | Load15 is the same figure over fifteen. The three together are what separate a machine that is busy right now from one that has been busy all along — which is… |
metrics.memFree | body | integer | — | bytes |
metrics.memUsed | body | integer | — | bytes |
metricsAt | body | string | — | MetricsAt is when that heartbeat was recorded, RFC 3339 in UTC, and the SERVER stamps it — a client cannot backdate or forge the staleness clock. |
running | body | integer | — | Running is how many of those are in running right now — the number a dispatcher weighs against Capacity. |
sessions | body | integer | — | Sessions is how many of the org's sessions are mapped to this machine, by target id OR by matching Host. |
spec | body | Spec | — | |
spec.arch | body | string | — | amd64 | arm64 | ... |
spec.cpus | body | integer | — | logical cores |
spec.gpus | body | GPU[] | — | GPUs is every accelerator the machine advertises, one entry each, capped at 32 on write. |
spec.gpus[].memory | body | integer | — | VRAM bytes, 0 = unknown |
spec.gpus[].model | body | string | — | "GB10", "8060S", "RTX 4090" |
spec.gpus[].vendor | body | string | — | nvidia | amd | apple | intel | ... |
spec.memory | body | integer | — | total RAM, bytes |
spec.os | body | string | — | linux | darwin | windows |
status | body | string | — | Status is the EFFECTIVE liveness — online | offline | draining — not the stored one. |
updatedAt | body | string | — | UpdatedAt is the last write to the row, same format — which for a beating machine is its last heartbeat, since a heartbeat IS a write. |
Failure carries the platform error shape — see Errors.
Examples
hanzo agents targets update <id>import { Configuration, AgentsApi } from 'hanzoai';
const api = new AgentsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.patchAgentsTargetsById({ id: 'id', capacity: "<capacity>", host: "<host>" });from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AgentsApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AgentsApi(client).patch_agents_targets_by_id(id='id', capacity="<capacity>", host="<host>")cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.AgentsAPI.PatchAgentsTargetsById(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, agents_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = agents_api::patch_agents_targets_by_id(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AgentsApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new AgentsApi(client).patchAgentsTargetsById();curl -X PATCH https://api.hanzo.ai/v1/agents/targets/<id> \
-H "Authorization: Bearer $HANZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"capacity": "<capacity>",
"host": "<host>"
}'The door reaches agents through the agents tool, which names its 36 operations with its own verbs — this one among them, under a name only the door declares. describe explains any of them:
curl -X POST https://api.hanzo.ai/v1/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "describe",
"arguments": {
"op": "list_agent_conversations"
}
}
}'How is this guide?