ClaimRoutedRun is the machine's long poll for work: it authenticates the…
ClaimRoutedRun is the machine's long poll for work: it authenticates the daemon, stamps the liveness the dispatch gate reads (the poll IS the proof a…
POST /v1/agents/targets/{id}/claim
| Address | https://api.hanzo.ai/v1/agents/targets/{id}/claim |
| Method | POST |
| Operation | post_agents_targets_by_id_claim |
| Auth | Authorization: Bearer $HANZO_API_KEY |
ClaimRoutedRun is 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 | routedRunOut | ok |
200 body — 8 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… |
cloneUrl | body | string | — | CloneURL is how to fetch the repository. It carries NO credential — the machine authenticates with the git identity it already holds — which is why this whole… |
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 | — | TimeoutSeconds bounds the run on the machine; 0 means the machine's own default. |
Failure carries the platform error shape — see Errors.
Examples
hanzo agents targets claim <id>import { Configuration, AgentsApi } from 'hanzoai';
const api = new AgentsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postAgentsTargetsByIdClaim({ id: 'id' });from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AgentsApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AgentsApi(client).post_agents_targets_by_id_claim(id='id')cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.AgentsAPI.PostAgentsTargetsByIdClaim(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, agents_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = agents_api::post_agents_targets_by_id_claim(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AgentsApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new AgentsApi(client).postAgentsTargetsByIdClaim();curl -X POST https://api.hanzo.ai/v1/agents/targets/<id>/claim \
-H "Authorization: Bearer $HANZO_API_KEY"The door reaches agents through the agents tool, which names its 36 operations with its own verbs — this one among them, under a name only the door 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"
}
}
}'How is this guide?