API
Agent device endpoints
The endpoints a self-hosted agent calls with its device token.
Only the agent itself calls these, with its device token. They're listed so the job contract is complete.
Every route below, with its parameters, request and response, errors and samples, is in the API reference.
| Route | What it does |
|---|---|
POST /v1/agent/poll | Marks the device as seen, returns its current policy and claims the oldest queued job it may run. |
POST /v1/agent/jobs/:jobId/complete | Reports a claimed job as done or failed. |
POST /v1/agent/jobs/:jobId/pipeline | A pipeline job this device claimed: the job's token for the runner, which then talks to /v1/runner like a hosted runner. Only the device holding the claim gets it. |
POST /v1/agent/jobs/:jobId/heartbeat | Sent every 20 s while a job runs: keeps the device online and says whether to stop. |
POST /v1/agent/jobs/:jobId/upload-url | Returns a fresh results upload URL for a job the device is still running. |
POST /v1/agent/code/:jobId/events | A Code mode session's events from the machine running it, in order (seq from 1). Secrets are taken out again; an event sent twice is kept once. |
POST /v1/agent/code/:jobId/streams | Pieces of a Code mode session's replies and terminal output from the machine running it (at most 64 of 256 KB), kept an hour; a terminal's output has known kinds of keys taken out again. |
POST /v1/agent/code/:jobId/commands | A Code mode session's commands for the machine after after (their seq). Only the device holding the session's job gets them. |
POST /v1/agent/code/:jobId/model | A model step for a session on Caity's Bedrock provider (docs/caity/code.md → Providers), billed to its person. |
POST /v1/agent/code/:jobId/checkout | A cloud session's build: its repository's git URL and a short credential (pull, push its work branch only). |
POST /v1/agent/code/:jobId/finish | A cloud session's build pushed its work: the pull request opens and the session ends. |
POST /v1/agent/network-requests | Asks for access to a host outside the device's allowlist. Shows up in Cloud → Agents. |