# Create targets URL: https://docs.hanzo.ai/docs/openapi/agent/post-agent-targets > Registers a machine as an agent target, or re-links one that is already registered. `POST /v1/agent/targets` > [Agent →](https://docs.hanzo.ai/docs/openapi/agent) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | --------------------------------------- | | **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](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo agent targets create ``` **SDK** **.ts** ```ts import { Configuration, AgentApi } from 'hanzoai'; const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.postAgentTargets({ capacity: "", host: "" }); ``` **.py** ```python 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="", host="") ``` **.go** ```go 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 } ``` **.rs** ```rust 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?; ``` **.java** ```java 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(); ``` **HTTP** ```bash curl -X POST https://api.hanzo.ai/v1/agent/targets \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "capacity": "", "host": "" }' ``` **MCP** 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: ```bash 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](https://docs.hanzo.ai/docs/openapi/agent) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)