API reference
Agents
Manage self-hosted agent devices, network approvals and jobs.
See Self-hosted agents for how devices are approved and what each job type does.
GET /v1/orgs/:orgId/agents
Devices, pending network requests and recent jobs.
Auth: user access token or platform agent key · Scope: agents:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Response 200
{
devices: {
version?: string
platform?: string
capabilities: string[]
networkMode?: "allowlist" | "full"
hosts?: string[]
userId: string
name: string
status?: "active" | "revoked"
createdAt?: number
updatedAt?: number
orgId: string
deviceId: string
lastSeenAt?: number
}[]
requests: {
status?: "pending" | "approved" | "denied"
createdAt?: number
updatedAt?: number
orgId: string
deviceId: string
host: string
reason?: string
}[]
jobs: {
type: "http.batch" | "exec" | "browser.batch"
error?: string
hosts?: string[]
label?: string
status?: "queued" | "expired" | "claimed" | "done" | "failed"
createdAt?: number
updatedAt?: number
orgId: string
expiresAt: number
createdBy: string
deviceId?: string
jobId: string
resultKey?: string
callbackUrl?: string
claimedAt?: number
completedAt?: number
}[]
}PATCH /v1/orgs/:orgId/agents/devices/:deviceId
Renames a device or changes its network mode and host allowlist.
Auth: user access token or platform agent key · Scope: agents:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:deviceId | Device id (dev_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
networkMode | "allowlist" | "full" | No | |
hosts | string[] | No | up to 200 items; each matches ^(\*\.)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$ |
name | string | No | 1–64 characters |
Response 200
{
ok: true
}Errors
| Status | Message |
|---|---|
404 | Device not found |
DELETE /v1/orgs/:orgId/agents/devices/:deviceId
Revokes a device. Its credential stops working on the next request.
Auth: user access token or platform agent key · Scope: agents:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:deviceId | Device id (dev_…). |
Response 204 with no body.
Errors
| Status | Message |
|---|---|
404 | Device not found |
POST /v1/orgs/:orgId/agents/requests/:deviceId/:host/:decision
Answers a device's request for a host. Approving adds the host to the device's allowlist.
Auth: user access token or platform agent key · Scope: agents:write
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:deviceId | Device id (dev_…). |
:host | The requested hostname. |
:decision | approve adds the host; any other value denies it. |
Response 200
{
ok: true
}Errors
| Status | Message |
|---|---|
404 | Request not found |
POST /v1/orgs/:orgId/agents/jobs
Queues a job. The first eligible device that polls claims it.
Auth: user access token or platform agent key · Scopes: agents:run, agents:write (when body.type === "exec")
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Request body
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
type | "http.batch" | "exec" | "browser.batch" | Yes | ||
label | string | No | up to 120 characters | |
input | any JSON | Yes | ||
hosts | string[] | No | [] | up to 50 items; each matches ^(\*\.)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$ |
callbackUrl | string | No | URL |
Response 201
{
jobId: string
}Errors
| Status | Message |
|---|---|
400 | Invalid browser.batch input. … |
400 | callbackUrl must be a public https URL. |
413 | Job input too large (300 KB max). |
GET /v1/orgs/:orgId/agents/jobs/:jobId
A job's status, with a temporary resultsUrl once it's done.
Auth: user access token or platform agent key · Scope: agents:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:jobId | Job id (job_…). |
Response 200
{
job: {
type: "http.batch" | "exec" | "browser.batch"
error?: string
hosts?: string[]
label?: string
status?: "queued" | "expired" | "claimed" | "done" | "failed"
createdAt?: number
updatedAt?: number
orgId: string
expiresAt: number
createdBy: string
deviceId?: string
jobId: string
resultKey?: string
callbackUrl?: string
claimedAt?: number
completedAt?: number
}
resultsUrl: null | string
}Errors
| Status | Message |
|---|---|
404 | Job not found |