API reference

Agents

Manage self-hosted agent devices, network approvals and jobs.

Read the Guide

GET/v1/orgs/:orgId/agents

Devices, pending network requests and recent jobs.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: agents:read

Get an API key

Path parameters

orgId
Organization id (org_…).

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/agents' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  devices: {
    ownerName: null | string
    version?: string
    platform?: string
    features?: string[]
    codeFolders?: string[]
    capabilities: string[]
    networkMode?: "allowlist" | "full"
    hosts?: string[]
    userId: string
    name: string
    status?: "active" | "revoked"
    createdAt?: number
    updatedAt?: number
    orgId: string
    lastSeenAt?: number
    deviceId: string
    labels?: string[]
  }[]
  requests: {
    status?: "pending" | "approved" | "denied"
    createdAt?: number
    updatedAt?: number
    orgId: string
    reason?: string
    deviceId: string
    host: string
  }[]
  jobs: {
    waiting?: null | {
      reason: "no_devices"
    } | {
      reason: "offline"
      devices: {
        deviceId: string
        name: string
      }[]
    } | {
      reason: "blocked"
      devices: {
        deviceId: string
        name: string
        online: boolean
        capability?: "browser" | "code" | "exec" | "pipelines" | "http"
        hosts?: string[]
        network?: "full" | "full-or-sandbox"
        labels?: string[]
        update?: true
        access?: string
        owner?: true
      }[]
    }
    status: string
    type: "http.batch" | "exec" | "browser.batch" | "pipeline" | "code.session"
    error?: string
    hosts?: string[]
    label?: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    createdBy: string
    expiresAt: number
    deviceId?: string
    labels?: string[]
    jobId: string
    cancelRequestedAt?: number
    canceledBy?: string
    heartbeatAt?: number
    queueTtl?: number
    resultKey?: string
    callbackUrl?: string
    runAs?: string
    claimedAt?: number
    completedAt?: number
    resultsHidden?: true
  }[]
}

PATCH/v1/orgs/:orgId/agents/devices/:deviceId

Renames a device or changes its network mode and host allowlist.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: agents:write

Get an API key

Path parameters

orgId
Organization id (org_…).
deviceId
Device id: an agent's (dev_…); under /v1/me/notifications a phone's install id; under /v1/me/sign-in-approvals a phone that approves sign-ins (apd_…); under /v1/me/vault the id a device made for its vault (22 base64url characters).

Request body

networkMode"allowlist" | "full"
hostsstring[]
Up to 200 items. Each matches ^(\*\.)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$.
namestring
1–64 characters.
capabilities("http" | "browser" | "exec" | "pipelines" | "code")[]
1–5 items.

Errors

403Only the device's owner can add capabilities, allow hosts or allow full network access.
404Device not found

curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/agents/devices/{deviceId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "networkMode": "allowlist",
    "hosts": [
      "example"
    ],
    "name": "Example"
  }'

Send it from this page with your session or a key.

Response 200

{
  ok: true
}

DELETE/v1/orgs/:orgId/agents/devices/:deviceId

Revokes a device. Its credential stops working on the next request.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: agents:write

Get an API key

Path parameters

orgId
Organization id (org_…).
deviceId
Device id: an agent's (dev_…); under /v1/me/notifications a phone's install id; under /v1/me/sign-in-approvals a phone that approves sign-ins (apd_…); under /v1/me/vault the id a device made for its vault (22 base64url characters).

Errors

404Device not found

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/agents/devices/{deviceId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 204 with no body

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: A person's token or an API key, as Authorization: Bearer.
Scope: agents:write

Get an API key

Path parameters

orgId
Organization id (org_…).
deviceId
Device id: an agent's (dev_…); under /v1/me/notifications a phone's install id; under /v1/me/sign-in-approvals a phone that approves sign-ins (apd_…); under /v1/me/vault the id a device made for its vault (22 base64url characters).
host
The requested hostname.
decision
approve adds the host; any other value denies it.

Errors

403Only the device's owner can allow it to reach a new host.
404Request not found

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/agents/requests/{deviceId}/{host}/{decision}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  ok: true
}

POST/v1/orgs/:orgId/agents/jobs

Queues a job. The first eligible device that polls claims it.

Auth: A person's token or an API key, as Authorization: Bearer.
Scopes: agents:run, agents:write (when body.type === "exec")

Get an API key

Path parameters

orgId
Organization id (org_…).

Request body

type"http.batch" | "exec" | "browser.batch"required
labelstring
Up to 120 characters.
inputany JSONrequired
hostsstring[]
Default []. Up to 50 items. Each matches ^(\*\.)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$.
callbackUrlstring
URL.
ttlSecondsinteger
60–604800.

Errors

400Invalid browser.batch input. …
400callbackUrl must be a public https URL.
400ttlSeconds must be between 60 and 604800.
413Job input too large (300 KB max).

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/agents/jobs' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "http.batch",
    "input": {}
  }'

Send it from this page with your session or a key.

Response 201

{
  jobId: string
  expiresAt: number
}

GET/v1/orgs/:orgId/agents/jobs/:jobId

A job's status, with a temporary resultsUrl once it's done.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: agents:read

Get an API key

Path parameters

orgId
Organization id (org_…).
jobId
Job id: an agent job (job_…), under pipelines a pipeline job (pjb_…), or under crm an import or export (cjb_…); under marketing a list import (mkj_…).

Errors

404Job not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/agents/jobs/{jobId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  job: {
    status: string
    type: "http.batch" | "exec" | "browser.batch" | "pipeline" | "code.session"
    hosts?: string[]
    label?: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    createdBy: string
    expiresAt: number
    deviceId?: string
    labels?: string[]
    jobId: string
    cancelRequestedAt?: number
    canceledBy?: string
    heartbeatAt?: number
    queueTtl?: number
    runAs?: string
    claimedAt?: number
    completedAt?: number
    resultsHidden: true
  }
  resultsUrl: null
}
| {
  job: {
    status: string
    type: "http.batch" | "exec" | "browser.batch" | "pipeline" | "code.session"
    error?: string
    hosts?: string[]
    label?: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    createdBy: string
    expiresAt: number
    deviceId?: string
    labels?: string[]
    jobId: string
    cancelRequestedAt?: number
    canceledBy?: string
    heartbeatAt?: number
    queueTtl?: number
    resultKey?: string
    callbackUrl?: string
    runAs?: string
    claimedAt?: number
    completedAt?: number
  }
  resultsUrl: null | string
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: agents:run

Get an API key

Path parameters

orgId
Organization id (org_…).
jobId
Job id: an agent job (job_…), under pipelines a pipeline job (pjb_…), or under crm an import or export (cjb_…); under marketing a list import (mkj_…).

Errors

404Job not found
409This job already ….

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/agents/jobs/{jobId}/cancel' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  status: "canceled" | "canceling"
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: agents:run

Get an API key

Path parameters

orgId
Organization id (org_…).
jobId
Job id: an agent job (job_…), under pipelines a pipeline job (pjb_…), or under crm an import or export (cjb_…); under marketing a list import (mkj_…).

Request body

deviceIdstringrequired
At least 1 character.

Errors

404Job not found
404Device not found
409Only queued jobs wait for access.
409… runs shell commands only for its owner.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/agents/jobs/{jobId}/request-access' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "deviceId": "<deviceId>"
  }'

Send it from this page with your session or a key.

Response 200

{
  requested: []
  notified: false
}
| {
  requested: string[]
  notified: false
  missing: {
    capability?: "browser" | "code" | "exec" | "pipelines" | "http"
    hosts?: string[]
    network?: "full" | "full-or-sandbox"
    labels?: string[]
    update?: true
    access?: string
    owner?: true
  }
}