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: {
    ownerName: null | string
    version?: string
    platform?: string
    features?: 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: {
    waiting?: null | {
      reason: "no_devices"
    } | {
      reason: "offline"
      devices: {
        deviceId: string
        name: string
      }[]
    } | {
      reason: "blocked"
      devices: {
        deviceId: string
        name: string
        online: boolean
        capability?: "exec" | "http" | "browser"
        hosts?: string[]
        network?: "full-or-sandbox"
      }[]
    }
    status: string
    type: "http.batch" | "exec" | "browser.batch"
    error?: string
    hosts?: string[]
    label?: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    createdBy: string
    expiresAt: number
    deviceId?: string
    jobId: string
    cancelRequestedAt?: number
    canceledBy?: string
    heartbeatAt?: number
    queueTtl?: number
    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
`capabilities`	`("http" \| "browser" \| "exec")[]`	No	1–3 items

Response 200

{
  ok: true
}

Errors

Status	Message
`403`	Only the device's owner can add capabilities or allow full network access.
`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
`ttlSeconds`	`integer`	No		60–604800

Response 201

{
  jobId: string
  expiresAt: number
}

Errors

Status	Message
`400`	Invalid browser.batch input. …
`400`	callbackUrl must be a public https URL.
`400`	ttlSeconds must be between 60 and 604800.
`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: {
    status: string
    type: "http.batch" | "exec" | "browser.batch"
    error?: string
    hosts?: string[]
    label?: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    createdBy: string
    expiresAt: number
    deviceId?: string
    jobId: string
    cancelRequestedAt?: number
    canceledBy?: string
    heartbeatAt?: number
    queueTtl?: number
    resultKey?: string
    callbackUrl?: string
    claimedAt?: number
    completedAt?: number
  }
  resultsUrl: null | string
}

Errors

Status	Message
`404`	Job not found

`POST /v1/orgs/:orgId/agents/jobs/:jobId/cancel`

Cancels a queued job, or asks the device running it to stop (canceling until it does).

Auth: user access token or platform agent key · Scope: agents:run

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:jobId`	Job id (`job_…`).

Response 200

{
  status: "canceled" | "canceling"
}

Errors

Status	Message
`404`	Job not found
`409`	This job already ….

`POST /v1/orgs/:orgId/agents/jobs/:jobId/request-access`

For a queued job a device can't run: files network requests for the hosts it lacks and emails the device's owner what else it needs (capability, full network access). Nothing changes until someone approves.

Auth: user access token or platform agent key · Scope: agents:run

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:jobId`	Job id (`job_…`).

Request body

Field	Type	Required	Notes
`deviceId`	`string`	Yes	at least 1 character

Response 200

{
  requested: []
  notified: false
}
| {
  requested: string[]
  notified: false
  missing: {
    capability?: "exec" | "http" | "browser"
    hosts?: string[]
    network?: "full-or-sandbox"
  }
}

Errors

Status	Message
`404`	Job not found
`404`	Device not found
`409`	Only queued jobs wait for access.

Agents

On this page