Hanzo
OpenapiAgents

Registers a machine as an agent target, or re-links one that is already…

Registers a machine as an agent target, or re-links one that is already registered.

POST /v1/agents/targets

Addresshttps://api.hanzo.ai/v1/agents/targets
MethodPOST
Operationpost_agents_targets
AuthAuthorization: Bearer $HANZO_API_KEY

Registers a machine as an agent target, or re-links one that is already registered. Re-linking is idempotent and keyed on org+host+owner, so a machine that reconnects refreshes its own row rather than piling up duplicates; it answers 200, while a first registration answers 201.

Request

22 fields, body application/json (required).

FieldInTypeRequiredDescription
capacitybodystringCapacity is a human summary of the machine's size, up to 256 characters.
hostbodystringHost is the hostname sessions on this machine will report.
kindbodystringKind is laptop | cloud | gpu | cluster | machine.
labelbodystringLabel is the name to show for this 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 is online | offline | draining. Empty registers online.

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 create

Agents API · All Hanzo APIs · Interactive reference

How is this guide?

On this page