Hanzo
OpenapiAgents

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

Addresshttps://api.hanzo.ai/v1/agents/targets/{id}/claim
MethodPOST
Operationpost_agents_targets_by_id_claim
AuthAuthorization: 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.

FieldInTypeRequiredDescription
idpathstringyesID is the target to act on, from the path.

Response

StatusBodyMeaning
200routedRunOutok

200 body — 8 fields.

FieldInTypeAlwaysDescription
basebodystringBase is the branch to start FROM.
branchbodystringBranch 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…
cloneUrlbodystringCloneURL 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…
projectbodystringProject is the product slug the run is filed under, so the machine can tag what it produces.
promptbodystringPrompt is the task, in full, as the person wrote it.
repobodystringRepo is the repository to work in and CloneURL is how to fetch it.
sessionIdbodystringSessionID is the live session opened at dispatch; the machine streams its turns into it.
timeoutSecondsbodyintegerTimeoutSeconds 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>

Agents API · All Hanzo APIs · Interactive reference

How is this guide?

On this page