Hanzo
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}

Addresshttps://api.hanzo.ai/v1/agents/targets/{id}
MethodPATCH
Operationpatch_agents_targets_by_id
AuthAuthorization: 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).

FieldInTypeRequiredDescription
idpathstringyesID is the target to update, from the path.
capacitybodystringCapacity rewrites the human summary, up to 256 characters.
hostbodystringHost re-points the hostname sessions are matched by.
idbodystringID is the target to update, from the path.
kindbodystringKind re-files it under laptop | cloud | gpu | cluster | machine.
labelbodystringLabel renames the machine, up to 128 characters.
metricsbodyMetrics
metrics.atbodyintegerunix seconds, server-stamped
metrics.gpuUtilbodynumber0..1 aggregate utilization
metrics.load1bodynumberLoad1 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.load5bodynumberLoad5 is the same figure averaged over five minutes.
metrics.load15bodynumberLoad15 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.memFreebodyintegerbytes
metrics.memUsedbodyintegerbytes
specbodySpec
spec.archbodystringamd64 | arm64 | ...
spec.cpusbodyintegerlogical cores
spec.gpusbodyGPU[]GPUs is every accelerator the machine advertises, one entry each, capped at 32 on write.
spec.gpus[].memorybodyintegerVRAM bytes, 0 = unknown
spec.gpus[].modelbodystring"GB10", "8060S", "RTX 4090"
spec.gpus[].vendorbodystringnvidia | amd | apple | intel | ...
spec.memorybodyintegertotal RAM, bytes
spec.osbodystringlinux | darwin | windows
statusbodystringStatus sets operator INTENT: online | offline | draining. Draining is how a machine is taken out of dispatch without ending what is already on it.

Response

StatusBodyMeaning
200targetViewok

200 body — 28 fields.

FieldInTypeAlwaysDescription
capacitybodystringCapacity is a human summary of what the machine has ("8 vCPU / 32G", "1× GB10"), up to 256 characters.
createdAtbodystringCreatedAt is when the machine was first registered, RFC 3339 in UTC.
hostbodystringHost 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…
idbodystringID is the machine's handle, minted as "tgt_" + 32 hex characters.
kindbodystringKind is what sort of destination this is, from a closed five: laptop | cloud | gpu | cluster | machine.
labelbodystringLabel is the name a person gave the machine ("workshop"), up to 128 characters.
metricsbodyMetrics
metrics.atbodyintegerunix seconds, server-stamped
metrics.gpuUtilbodynumber0..1 aggregate utilization
metrics.load1bodynumberLoad1 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.load5bodynumberLoad5 is the same figure averaged over five minutes.
metrics.load15bodynumberLoad15 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.memFreebodyintegerbytes
metrics.memUsedbodyintegerbytes
metricsAtbodystringMetricsAt is when that heartbeat was recorded, RFC 3339 in UTC, and the SERVER stamps it — a client cannot backdate or forge the staleness clock.
runningbodyintegerRunning is how many of those are in running right now — the number a dispatcher weighs against Capacity.
sessionsbodyintegerSessions is how many of the org's sessions are mapped to this machine, by target id OR by matching Host.
specbodySpec
spec.archbodystringamd64 | arm64 | ...
spec.cpusbodyintegerlogical cores
spec.gpusbodyGPU[]GPUs is every accelerator the machine advertises, one entry each, capped at 32 on write.
spec.gpus[].memorybodyintegerVRAM bytes, 0 = unknown
spec.gpus[].modelbodystring"GB10", "8060S", "RTX 4090"
spec.gpus[].vendorbodystringnvidia | amd | apple | intel | ...
spec.memorybodyintegertotal RAM, bytes
spec.osbodystringlinux | darwin | windows
statusbodystringStatus is the EFFECTIVE liveness — online | offline | draining — not the stored one.
updatedAtbodystringUpdatedAt 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>

Agents API · All Hanzo APIs · Interactive reference

How is this guide?

On this page