Move an agent's work to the cloud, to a paired machine, or to the best paired machine.
A shorthand for POST /agents/{id}/move with only a target and the agent's own model: "cloud", a node id, or "local" for the first paired machine (not a cloud worker) that can take it now.
POST/api/v1/agents/{id}/handoff
Scopecrews
When an API key calls it, the timeline records who did what and the outcome. No query parameters.
Path parameters.
idstringrequired
The agent's id.
Headers.
Idempotency-Keystring
Makes a retry safe: the same key with the same request returns the first answer and does nothing else.
Body.
target"cloud" | "local" | stringrequired
cloud, local (the best paired machine for it) or a machine id. At least 5 characters.
Response.
200 OK: a JSON object. The example has placeholder values.
- 409 conflict
- Refused with
409 conflictand the reason for each machine when none can. - 422 validation_failed
- The body does not match its schema; each problem is in
details.