Create targets

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

POST /v1/agent/targets

Agent → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/agent/targets`
Method	`POST`
Operation	`post_agent_targets`
Auth	`Authorization: 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

42 fields, body application/json (required).

Field	In	Type	Required	Description
`capacity`	body	string	—	Capacity is a human summary of the machine's size, up to 256 characters.
`host`	body	string	—	Host is the hostname sessions on this machine will report.
`kind`	body	string	—	Kind is laptop \| cloud \| gpu \| cluster \| machine.
`label`	body	string	—	Label is the name to show for this 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 it is read against Spec.CPUs: 8.0 is idle on 16 cores and swamped on 4.
`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.
`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 is online \| offline \| draining.

Response

Status	Body	Meaning
`200`	agent.targetView	ok
`default`	problem-details	refused

200 body — 49 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 names no target id, and a re-link of the same (org, host, owner) refreshes this row instead of creating a second.
`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 it is read against Spec.CPUs: 8.0 is idle on 16 cores and swamped on 4.
`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.
`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.
`serving`	body	boolean	—	Serving says whether a run the caller sends here now would be taken: the machine is the caller's (or the caller is an org admin), and it is online with a runner that polled for work within the last 90 seconds — the online and runner half is what dispatch checks (TargetDispatchable).
`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

CLI

SDK

HTTP

MCP

hanzo agent targets create

.ts

.py

.go

.rs

.java

import { Configuration, AgentApi } from 'hanzoai';

const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postAgentTargets({ 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).post_agent_targets(capacity="<capacity>", host="<host>")

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

resp, _, err := client.AgentAPI.PostAgentTargets(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::post_agent_targets(&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).postAgentTargets();

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

MCP reaches agent through the agent tool, which names its 38 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_agents"
         }
       }
     }'

Agent API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousCreate report NextCreate agent