API reference
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.
POST /v1/agent/poll
Marks the device as seen, returns its current policy and claims the oldest queued job it may run.
Auth: agent device token
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
version | string | No | up to 32 characters |
platform | string | No | up to 64 characters |
features | string[] | No | up to 20 items; each up to 32 characters |
connected | boolean | No |
Response 200
{
push?: {
url: string
}
policy: {
capabilities: string[]
networkMode?: "allowlist" | "full"
hosts?: string[]
}
job: null | {
jobId: string
type: "http.batch" | "exec" | "browser.batch"
label?: string
hosts?: string[]
input: unknown
uploadUrl: string
}
nextPollMs: number
}POST /v1/agent/jobs/:jobId/complete
Reports a claimed job as done or failed.
Auth: agent device token
| Path parameter | Description |
|---|---|
:jobId | Job id (job_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
status | "done" | "failed" | "canceled" | Yes | |
error | string | No | up to 2,000 characters |
Response 200
{
ok: true
}Errors
| Status | Message |
|---|---|
404 | Job not found |
POST /v1/agent/jobs/:jobId/heartbeat
Sent every 20 s while a job runs: keeps the device online and says whether to stop.
Auth: agent device token
| Path parameter | Description |
|---|---|
:jobId | Job id (job_…). |
Response 200
{
cancel: boolean
}Errors
| Status | Message |
|---|---|
404 | Job not found |
POST /v1/agent/jobs/:jobId/upload-url
Returns a fresh results upload URL for a job the device is still running.
Auth: agent device token
| Path parameter | Description |
|---|---|
:jobId | Job id (job_…). |
Response 200
{
uploadUrl: string
}Errors
| Status | Message |
|---|---|
404 | Job not found |
POST /v1/agent/network-requests
Asks for access to a host outside the device's allowlist. Shows up in Cloud → Agents.
Auth: agent device token
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
host | string | Yes | 3–253 characters |
reason | string | No | up to 500 characters |
Response 200
{
ok: true
}