Claim targets
The machine's long poll for work: it authenticates the daemon, stamps the liveness the dispatch gate reads (the poll IS the proof a runner is listening), and waits up to 25 seconds for the next run addressed to THIS machine.
POST /v1/agent/targets/{id}/claim
| Address | https://api.hanzo.ai/v1/agent/targets/{id}/claim |
| Method | POST |
| Operation | post_agent_targets_by_id_claim |
| Auth | Authorization: Bearer $HANZO_API_KEY |
The machine's long poll for work: it authenticates the daemon, stamps the liveness the dispatch gate reads (the poll IS the proof a runner is listening), and waits up to 25 seconds for the next run addressed to THIS machine. It answers the run when one arrives and 204 with no body when the window elapses, on which the daemon re-polls immediately.
TWO independent proofs are required and both fail closed to the same 403: the caller must own this machine (or be an org admin) AND present its claim key in X-Target-Key. A run offered to one machine is unreachable from another's claim.
Request
1 field.
| Field | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the target to act on, from the path. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | agent.routedRunOut | ok |
default | problem-details | refused |
200 body — 11 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
base | body | string | — | Base is the branch to start FROM. |
branch | body | string | — | Branch is the ref the run must push its work to, and the ONLY one it is permitted to write: the forge's ref policy refuses anything else from this run's credential. |
cloneUrl | body | string | — | CloneURL is how to fetch the repository. |
effort | body | string | — | Effort is how hard that model reasons: low, medium or high. |
instructions | body | string | — | Instructions are the person's own instructions for their runs, as they set them in their settings: the machine's harness reads them as its user's, the way AGENTS.md or CLAUDE.md in its home is read. |
model | body | string | — | Model is the model the person asked the run's agent to think with, by the id GET /v1/models lists. |
project | body | string | — | Project is the product slug the run is filed under, so the machine can tag what it produces. |
prompt | body | string | — | Prompt is the task, in full, as the person wrote it. |
repo | body | string | — | Repo is the repository to work in and CloneURL is how to fetch it. |
sessionId | body | string | — | SessionID is the live session opened at dispatch; the machine streams its turns into it. |
timeoutSeconds | body | integer (int64) | — | TimeoutSeconds bounds the run on the machine; 0 means the machine's own default. |
Failure carries the platform error shape — see Errors.
Examples
hanzo agent targets claim <id>import { Configuration, AgentApi } from 'hanzoai';
const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postAgentTargetsByIdClaim({ id: 'id' });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_by_id_claim(id='id')cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)
resp, _, err := client.AgentAPI.PostAgentTargetsByIdClaim(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_by_id_claim(&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).postAgentTargetsByIdClaim();curl -X POST https://api.hanzo.ai/v1/agent/targets/<id>/claim \
-H "Authorization: Bearer $HANZO_API_KEY"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"
}
}
}'