Update targets

Updates one machine in place. Every field is optional; a field the request omits is left alone.

PATCH /v1/agent/targets/{id}

Agent → · All API references → · Get started →


Address	`https://api.hanzo.ai/v1/agent/targets/{id}`
Method	`PATCH`
Operation	`patch_agent_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

44 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	agent.Metrics	—
`metrics.at`	body	integer (int64)	—	unix seconds, server-stamped
`metrics.cpuTemp`	body	number (double)	—	CPUTemp is the CPU package temperature in °C.
`metrics.cpuUtil`	body	number (double)	—	CPUUtil is the busy fraction of all cores over the sample window, 0..1.
`metrics.decode`	body	number (double)	—	Decode is generation throughput over the sample window, in tokens per second.
`metrics.diskRead`	body	number (double)	—	DiskRead is the block-device read rate in bytes per second.
`metrics.diskTotal`	body	integer (int64)	—	DiskTotal is the size of those filesystems, in bytes.
`metrics.diskUsed`	body	integer (int64)	—	DiskUsed is the space used across local block filesystems, in bytes.
`metrics.diskWrite`	body	number (double)	—	DiskWrite is the block-device write rate in bytes per second.
`metrics.gpuMemTotal`	body	integer (int64)	—	GPUMemTotal is dedicated VRAM in bytes; absent when the GPU shares system memory (unified).
`metrics.gpuMemUsed`	body	integer (int64)	—	GPUMemUsed is the memory held by GPU processes, in bytes.
`metrics.gpuPower`	body	number (double)	—	GPUPower is the total GPU power draw in watts.
`metrics.gpuPowerLimit`	body	number (double)	—	GPUPowerLimit is the total enforced GPU power limit in watts; absent when the driver reports none.
`metrics.gpuTemp`	body	number (double)	—	GPUTemp is the hottest GPU's temperature in °C.
`metrics.gpuUtil`	body	number (double)	—	0..1 aggregate utilization
`metrics.kvCache`	body	number (double)	—	KVCache is the KV-cache occupancy, 0..1.
`metrics.load1`	body	number (double)	—	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 (double)	—	Load5 is the same figure averaged over five minutes.
`metrics.load15`	body	number (double)	—	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 (int64)	—	bytes
`metrics.memUsed`	body	integer (int64)	—	bytes
`metrics.model`	body	string	—	Model is the model id(s) served on this machine, comma-separated, at most 128 bytes.
`metrics.netRx`	body	number (double)	—	NetRx is the receive rate of physical interfaces in bytes per second.
`metrics.netTx`	body	number (double)	—	NetTx is the transmit rate of physical interfaces in bytes per second.
`metrics.prefill`	body	number (double)	—	Prefill is prompt (prefill) throughput over the sample window, in tokens per second.
`metrics.running`	body	integer (int64)	—	Running is the number of requests being served now.
`metrics.ttft`	body	number (double)	—	TTFT is the mean time to first token, in seconds, of requests that started in the window.
`metrics.waiting`	body	integer (int64)	—	Waiting is the number of requests queued.
`spec`	body	agent.Spec	—
`spec.arch`	body	string	—	amd64 \| arm64 \| ...
`spec.cpus`	body	integer (int64)	—	logical cores
`spec.gpus`	body	agent.GPU[]	—	GPUs is every accelerator the machine advertises, one entry each, capped at 32 on write.
`spec.gpus[].memory`	body	integer (int64)	—	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 (int64)	—	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`	agent.targetView	ok
`default`	problem-details	refused

200 body — 48 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	agent.Metrics	—
`metrics.at`	body	integer (int64)	—	unix seconds, server-stamped
`metrics.cpuTemp`	body	number (double)	—	CPUTemp is the CPU package temperature in °C.
`metrics.cpuUtil`	body	number (double)	—	CPUUtil is the busy fraction of all cores over the sample window, 0..1.
`metrics.decode`	body	number (double)	—	Decode is generation throughput over the sample window, in tokens per second.
`metrics.diskRead`	body	number (double)	—	DiskRead is the block-device read rate in bytes per second.
`metrics.diskTotal`	body	integer (int64)	—	DiskTotal is the size of those filesystems, in bytes.
`metrics.diskUsed`	body	integer (int64)	—	DiskUsed is the space used across local block filesystems, in bytes.
`metrics.diskWrite`	body	number (double)	—	DiskWrite is the block-device write rate in bytes per second.
`metrics.gpuMemTotal`	body	integer (int64)	—	GPUMemTotal is dedicated VRAM in bytes; absent when the GPU shares system memory (unified).
`metrics.gpuMemUsed`	body	integer (int64)	—	GPUMemUsed is the memory held by GPU processes, in bytes.
`metrics.gpuPower`	body	number (double)	—	GPUPower is the total GPU power draw in watts.
`metrics.gpuPowerLimit`	body	number (double)	—	GPUPowerLimit is the total enforced GPU power limit in watts; absent when the driver reports none.
`metrics.gpuTemp`	body	number (double)	—	GPUTemp is the hottest GPU's temperature in °C.
`metrics.gpuUtil`	body	number (double)	—	0..1 aggregate utilization
`metrics.kvCache`	body	number (double)	—	KVCache is the KV-cache occupancy, 0..1.
`metrics.load1`	body	number (double)	—	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 (double)	—	Load5 is the same figure averaged over five minutes.
`metrics.load15`	body	number (double)	—	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 (int64)	—	bytes
`metrics.memUsed`	body	integer (int64)	—	bytes
`metrics.model`	body	string	—	Model is the model id(s) served on this machine, comma-separated, at most 128 bytes.
`metrics.netRx`	body	number (double)	—	NetRx is the receive rate of physical interfaces in bytes per second.
`metrics.netTx`	body	number (double)	—	NetTx is the transmit rate of physical interfaces in bytes per second.
`metrics.prefill`	body	number (double)	—	Prefill is prompt (prefill) throughput over the sample window, in tokens per second.
`metrics.running`	body	integer (int64)	—	Running is the number of requests being served now.
`metrics.ttft`	body	number (double)	—	TTFT is the mean time to first token, in seconds, of requests that started in the window.
`metrics.waiting`	body	integer (int64)	—	Waiting is the number of requests queued.
`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 (int64)	—	Running is how many of those are in `running` right now — the number a dispatcher weighs against Capacity.
`sessions`	body	integer (int64)	—	Sessions is how many of the org's sessions are mapped to this machine, by target id OR by matching Host.
`spec`	body	agent.Spec	—
`spec.arch`	body	string	—	amd64 \| arm64 \| ...
`spec.cpus`	body	integer (int64)	—	logical cores
`spec.gpus`	body	agent.GPU[]	—	GPUs is every accelerator the machine advertises, one entry each, capped at 32 on write.
`spec.gpus[].memory`	body	integer (int64)	—	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 (int64)	—	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 agent targets update <id>

import { Configuration, AgentApi } from 'hanzoai';

const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.patchAgentTargetsById({ id: 'id', capacity: "<capacity>", host: "<host>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AgentApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AgentApi(client).patch_agent_targets_by_id(id='id', capacity="<capacity>", host="<host>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.AgentAPI.PatchAgentTargetsById(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, agent_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = agent_api::patch_agent_targets_by_id(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AgentApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new AgentApi(client).patchAgentTargetsById();

The method above is the one at the current release of the document. [email protected] (npm) was generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl -X PATCH https://api.hanzo.ai/v1/agent/targets/<id> \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "capacity": "<capacity>",
       "host": "<host>"
     }'

MCP reaches agent through the agents tool, which names its 36 operations with its own verbs — this one among them, under a name only MCP 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"
         }
       }
     }'

Agent API · All Hanzo APIs · Interactive reference

Request

Response

Examples

On this page