API
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.
Every route below, with its parameters, request and response, errors and samples, is in the API reference.
| Route | What it does |
|---|---|
GET /v1/orgs/:orgId/agents | Devices, pending network requests and recent jobs. |
PATCH /v1/orgs/:orgId/agents/devices/:deviceId | Renames a device or changes its network mode and host allowlist. |
DELETE /v1/orgs/:orgId/agents/devices/:deviceId | Revokes a device. Its credential stops working on the next request. |
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. |
POST /v1/orgs/:orgId/agents/jobs | Queues a job. The first eligible device that polls claims it. |
GET /v1/orgs/:orgId/agents/jobs/:jobId | A job's status, with a temporary resultsUrl once it's done. |
POST /v1/orgs/:orgId/agents/jobs/:jobId/cancel | Cancels a queued job, or asks the device running it to stop (canceling until it does). |
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. |