Skip to content

API reference / RivetIT

Endpoint agent

POST /agent_enroll Public

Enroll a Windows endpoint agent (device-facing, no Bearer)

Exchanges a short-lived enrollment token (carried in the body) for a unique per-device credential, shown once; only its SHA-256 is stored. Same install_id again, or a reinstall of the same machine (machine_guid or serial), keeps the device id and rotates the credential. Two different machines are never merged: ambiguous, out-of-department, hostname-only or already-owned matches return status pending_approval or ambiguous and wait for an administrator. TLS required. Rate limited per address (429 + Retry-After). See docs/ENDPOINT_AGENT.md.

Request body (application/json, required)

FieldTypeDescription
enrollment_tokenrequired string
devicerequired object
device.install_idrequired string (uuid)
device.machine_guid string
device.hostnamerequired string
device.osrequired string (windows)
device.os_versionrequired string
device.archrequired string (amd64 | arm64)
device.serial string
device.manufacturer string
device.model string
device.mac_addresses array of string
device.agent_versionrequired string

Example request

curl -X POST "https://YOUR-HOST/api/v1/agent_enroll" \
  -H "Content-Type: application/json" \
  -d '{"enrollment_token":"string","device":{"install_id":"string","machine_guid":"string","hostname":"string","os":"windows","os_version":"string","arch":"amd64","serial":"string","manufacturer":"string","model":"string","mac_addresses":["string"],"agent_version":"string"}}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/agent_enroll",
    json={
        "enrollment_token": "string",
        "device": {
            "install_id": "string",
            "machine_guid": "string",
            "hostname": "string",
            "os": "windows",
            "os_version": "string",
            "arch": "amd64",
            "serial": "string",
            "manufacturer": "string",
            "model": "string",
            "mac_addresses": [
                "string"
            ],
            "agent_version": "string"
        }
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/agent_enroll", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
      "enrollment_token": "string",
      "device": {
          "install_id": "string",
          "machine_guid": "string",
          "hostname": "string",
          "os": "windows",
          "os_version": "string",
          "arch": "amd64",
          "serial": "string",
          "manufacturer": "string",
          "model": "string",
          "mac_addresses": [
              "string"
          ],
          "agent_version": "string"
      }
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/agent_enroll");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"enrollment_token":"string","device":{"install_id":"string","machine_guid":"string","hostname":"string","os":"windows","os_version":"string","arch":"amd64","serial":"string","manufacturer":"string","model":"string","mac_addresses":["string"],"agent_version":"string"}}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

201Enrolled

FieldTypeDescription
device_id integer
device_token string Shown once
check_in_interval_s integer
server_time string (date-time)
status string (linked | pending_approval | ambiguous)
matched_asset_id integer
signing_public_key string base64 Ed25519 public key
signing_key_id string
config object
config.checks array of object
config.checks[].key string
config.checks[].type string (service | disk | pending_reboot | script)
config.checks[].params object
config.checks[].interval_s integer
config.checks[].signature string Ed25519 over the canonical JSON of the other fields
config.collect_interval_s integer
Example response
json
{
    "device_id": 1,
    "device_token": "string",
    "check_in_interval_s": 1,
    "server_time": "2026-01-01T09:00:00Z",
    "status": "linked",
    "matched_asset_id": 1,
    "signing_public_key": "string",
    "signing_key_id": "string",
    "config": {
        "checks": [
            {
                "key": null,
                "type": "service",
                "params": null,
                "interval_s": null,
                "signature": null
            }
        ],
        "collect_interval_s": 1
    }
}

401Error code invalid_token, revoked or expired

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

403Service disabled, token exhausted, or the device was revoked/retired (code forbidden)

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

409install_id belongs to a different machine (code conflict)

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

413Body too large

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

422Invalid body (code invalid)

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

429Too many attempts (Retry-After header)

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal
POST /agent_checkin Bearer token or API key

Device check-in: inventory, metrics, checks (device credential)

Idempotent by (device_id, seq): a retried check-in is acknowledged but never double counted. A missing metric (null or absent) is never stored as zero. collected_at must not be in the future (5 minutes skew) or older than the retention window; invalid buffered samples are dropped, not fatal. Feeds the existing asset RMM link, device metrics and RMM alerts (debounced, deduplicated). Optional extra field update_result {version, state ok|failed|rolled_back, detail} reports the last agent update.

Request body (application/json, required)

FieldTypeDescription
seqrequired integer
collected_atrequired string (date-time)
agent_versionrequired string
inventory object
metrics object
metrics.cpu_pct number
metrics.mem_pct number
metrics.disk array of object
metrics.disk[].mount string
metrics.disk[].used_pct number
metrics.net_rx_bps number
metrics.net_tx_bps number
checks array of object
checks[].key string
checks[].status string (ok | warn | fail | unknown)
checks[].detail string
buffered array of object
update_result object

Example request

curl -X POST "https://YOUR-HOST/api/v1/agent_checkin" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"seq":1,"collected_at":"2026-01-01T09:00:00Z","agent_version":"string","inventory":{},"metrics":{"cpu_pct":1.5,"mem_pct":1.5,"disk":[{"mount":null,"used_pct":null}],"net_rx_bps":1.5,"net_tx_bps":1.5},"checks":[{"key":"string","status":"ok","detail":"string"}],"buffered":[{}],"update_result":{}}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/agent_checkin",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "seq": 1,
        "collected_at": "2026-01-01T09:00:00Z",
        "agent_version": "string",
        "inventory": {},
        "metrics": {
            "cpu_pct": 1.5,
            "mem_pct": 1.5,
            "disk": [
                {
                    "mount": None,
                    "used_pct": None
                }
            ],
            "net_rx_bps": 1.5,
            "net_tx_bps": 1.5
        },
        "checks": [
            {
                "key": "string",
                "status": "ok",
                "detail": "string"
            }
        ],
        "buffered": [
            {}
        ],
        "update_result": {}
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/agent_checkin", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
      "seq": 1,
      "collected_at": "2026-01-01T09:00:00Z",
      "agent_version": "string",
      "inventory": {},
      "metrics": {
          "cpu_pct": 1.5,
          "mem_pct": 1.5,
          "disk": [
              {
                  "mount": null,
                  "used_pct": null
              }
          ],
          "net_rx_bps": 1.5,
          "net_tx_bps": 1.5
      },
      "checks": [
          {
              "key": "string",
              "status": "ok",
              "detail": "string"
          }
      ],
      "buffered": [
          {}
      ],
      "update_result": {}
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/agent_checkin");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"seq":1,"collected_at":"2026-01-01T09:00:00Z","agent_version":"string","inventory":{},"metrics":{"cpu_pct":1.5,"mem_pct":1.5,"disk":[{"mount":null,"used_pct":null}],"net_rx_bps":1.5,"net_tx_bps":1.5},"checks":[{"key":"string","status":"ok","detail":"string"}],"buffered":[{}],"update_result":{}}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Accepted

FieldTypeDescription
ok boolean
next_check_in_s integer
jobs_pending integer
config object
config.checks array of object
config.checks[].key string
config.checks[].type string (service | disk | pending_reboot | script)
config.checks[].params object
config.checks[].interval_s integer
config.checks[].signature string Ed25519 over the canonical JSON of the other fields
config.collect_interval_s integer
update object
update.version string
update.url string
update.sha256 string
update.signature string base64 Ed25519 over the lowercase hex sha256
update.min_version string
server_time string (date-time)
signing_key_id string
Example response
json
{
    "ok": true,
    "next_check_in_s": 1,
    "jobs_pending": 1,
    "config": {
        "checks": [
            {
                "key": null,
                "type": "service",
                "params": null,
                "interval_s": null,
                "signature": null
            }
        ],
        "collect_interval_s": 1
    },
    "update": {
        "version": "string",
        "url": "string",
        "sha256": "string",
        "signature": "string",
        "min_version": "string"
    },
    "server_time": "2026-01-01T09:00:00Z",
    "signing_key_id": "string"
}

401Credential invalid_token, revoked or expired

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

403Service disabled

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

413Body over 1 MiB

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

422Invalid payload

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

429Rate limited (Retry-After header)

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal
GET /agent_jobs Bearer token or API key

Fetch this device's signed jobs (device credential, optional long poll)

Returns only the calling device's queued jobs, each signed (Ed25519 over the canonical JSON of the job fields). wait=1..5 holds the request open up to that many seconds. A destructive job (reboot, or flagged) is offered at most once; a harmless job whose acknowledgement was lost is re-offered with attempt + 1. A revoked device gets 401 revoked immediately.

Parameters

NameInTypeDescription
waitqueryinteger

Example request

curl "https://YOUR-HOST/api/v1/agent_jobs" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/agent_jobs",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/agent_jobs", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/agent_jobs");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Jobs (possibly empty)

FieldTypeDescription
jobs array of object
jobs[].job_id string (uuid)
jobs[].attempt integer
jobs[].type string (powershell | reboot | collect)
jobs[].script string
jobs[].params object
jobs[].timeout_s integer
jobs[].max_output_bytes integer
jobs[].issued_at string (date-time)
jobs[].expires_at string (date-time)
jobs[].signature string base64 Ed25519 over the canonical JSON of all other fields
Example response
json
{
    "jobs": [
        {
            "job_id": "string",
            "attempt": 1,
            "type": "powershell",
            "script": "string",
            "params": {},
            "timeout_s": 1,
            "max_output_bytes": 1,
            "issued_at": "2026-01-01T09:00:00Z",
            "expires_at": "2026-01-01T09:00:00Z",
            "signature": "string"
        }
    ]
}

401Credential invalid_token, revoked or expired

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

429Rate limited

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal
POST /agent_jobs Bearer token or API key

Report a job's state or result (device credential)

Idempotent for a repeated identical final state; a conflicting final state, a cancelled/expired job, or a state going back to running is 409. Output is credential-redacted and capped before storage. A late real result replaces a server-side result_lost.

Request body (application/json, required)

FieldTypeDescription
job_idrequired string (uuid)
attemptrequired integer
staterequired string (running | succeeded | failed | timed_out | cancelled)
exit_code integer
output string
started_at string (date-time)
finished_at string (date-time)

Example request

curl -X POST "https://YOUR-HOST/api/v1/agent_jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"job_id":"string","attempt":1,"state":"running","exit_code":1,"output":"string","started_at":"2026-01-01T09:00:00Z","finished_at":"2026-01-01T09:00:00Z"}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/agent_jobs",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "job_id": "string",
        "attempt": 1,
        "state": "running",
        "exit_code": 1,
        "output": "string",
        "started_at": "2026-01-01T09:00:00Z",
        "finished_at": "2026-01-01T09:00:00Z"
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/agent_jobs", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
      "job_id": "string",
      "attempt": 1,
      "state": "running",
      "exit_code": 1,
      "output": "string",
      "started_at": "2026-01-01T09:00:00Z",
      "finished_at": "2026-01-01T09:00:00Z"
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/agent_jobs");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"job_id":"string","attempt":1,"state":"running","exit_code":1,"output":"string","started_at":"2026-01-01T09:00:00Z","finished_at":"2026-01-01T09:00:00Z"}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Recorded

FieldTypeDescription
ok boolean
Example response
json
{
    "ok": true
}

401Credential invalid

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

404Unknown job for this device

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

409Conflict

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

413Body over 256 KiB

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

422Invalid body

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal
POST /agent_installer Public

Download the stamped per-department installer with an enrollment token (for RMM, Intune, GPO scripts)

Public, token-gated. The enrollment token goes in the JSON or form body (or an Authorization Bearer header), NEVER in the query string (a token in the URL is refused with 400 so it stays out of access logs). Returns the current agent executable for the architecture with the department's installer payload and a 52-byte footer appended (see docs/ENDPOINT_AGENT.md section 'Stamped installer format'), streamed with an exact Content-Length. Any token that is not usable now (unknown, wrong, revoked, expired, used up) gets the same generic 404. Rate limited per address and per token from the database (429 + Retry-After). Successes and rejections are audited. The download does not consume an enrollment use; enrolling does.

Request body (application/json, required)

FieldTypeDescription
token string rvte1.<selector>.<secret>; may instead be sent as Authorization Bearer
archrequired string (amd64 | arm64)

Example request

curl -X POST "https://YOUR-HOST/api/v1/agent_installer" \
  -H "Content-Type: application/json" \
  -d '{"token":"string","arch":"amd64"}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/agent_installer",
    json={
        "token": "string",
        "arch": "amd64"
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/agent_installer", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
      "token": "string",
      "arch": "amd64"
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/agent_installer");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"token":"string","arch":"amd64"}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

200The stamped installer (RivetIT-Agent-Setup-<department>-<arch>.exe)

Example response
json
"string"

400Token supplied in the query string (code token_in_url)

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

403Service disabled

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

404Generic: the token is not usable

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

405Use POST

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

409No published binary for that architecture, or no https service URL (code unavailable)

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

413Body over 4 KiB

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

422token or arch missing or invalid

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

429Too many requests (Retry-After header)

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal
GET /agent_update Bearer token or API key

Download the hosted agent release this device is currently offered (device credential)

Streams the UNSTAMPED agent executable of the server-hosted release named by the update manifest (its url points here). Only the release the manifest offers THIS device right now is served, only for its own architecture, and only while the stored file still matches the manifest SHA-256. Anything else is a generic 404. Content-Length exact, nosniff, no-store.

Parameters

NameInTypeDescription
archrequiredquerystring (amd64 | arm64)
versionrequiredquerystring

Example request

curl "https://YOUR-HOST/api/v1/agent_update?arch=1&version=1" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/agent_update",
    headers={"Authorization": f"Bearer {TOKEN}"},
    params={"arch":1,"version":1},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/agent_update?arch=1&version=1", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/agent_update?arch=1&version=1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200The agent executable

Example response
json
"string"

401Credential invalid_token, revoked or expired

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

404Not offered to this device (or damaged)

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

422arch or version invalid

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

429Rate limited

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

503The stored binary is missing or failed its integrity check

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal
GET /endpoint_devices Bearer token or API key

List endpoint agent devices in the caller's departments

Needs a user token and RMM (module_rmm) view access. Module-only logins and API keys get 403.

Parameters

NameInTypeDescription
limitqueryinteger
offsetqueryinteger
statusquerystring

Example request

curl "https://YOUR-HOST/api/v1/endpoint_devices" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/endpoint_devices",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/endpoint_devices", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/endpoint_devices");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Devices

FieldTypeDescription
data array of object
data[].device_id integer
data[].hostname string
data[].asset_id integer
data[].client_id integer
data[].link_state string (linked | pending_approval | rejected)
data[].status string (online | offline | stale | never)
data[].last_checkin_at string (date-time)
data[].offline_since string (date-time)
data[].agent_version string
data[].ring string
data[].inventory object
data[].checks array of object
data[].jobs array of object
total integer
Example response
json
{
    "data": [
        {
            "device_id": 1,
            "hostname": "string",
            "asset_id": 1,
            "client_id": 1,
            "link_state": "linked",
            "status": "online",
            "last_checkin_at": "2026-01-01T09:00:00Z",
            "offline_since": "2026-01-01T09:00:00Z",
            "agent_version": "string",
            "ring": "string",
            "inventory": {},
            "checks": [
                null
            ],
            "jobs": [
                null
            ]
        }
    ],
    "total": 1
}

401Missing or invalid credentials

FieldTypeDescription
error string

403Authenticated but not permitted

FieldTypeDescription
error string
GET /endpoint_devices/{id} Bearer token or API key

Device detail with inventory, checks and recent jobs

A device outside the caller's departments is a 404 (indistinguishable from a missing one). Job output needs module_rmm_scripts level 2.

Parameters

NameInTypeDescription
idrequiredpathinteger

Example request

curl "https://YOUR-HOST/api/v1/endpoint_devices/1" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/endpoint_devices/1",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/endpoint_devices/1", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/endpoint_devices/1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Device

FieldTypeDescription
device_id integer
hostname string
asset_id integer
client_id integer
link_state string (linked | pending_approval | rejected)
status string (online | offline | stale | never)
last_checkin_at string (date-time)
offline_since string (date-time)
agent_version string
ring string
inventory object
checks array of object
jobs array of object
Example response
json
{
    "device_id": 1,
    "hostname": "string",
    "asset_id": 1,
    "client_id": 1,
    "link_state": "linked",
    "status": "online",
    "last_checkin_at": "2026-01-01T09:00:00Z",
    "offline_since": "2026-01-01T09:00:00Z",
    "agent_version": "string",
    "ring": "string",
    "inventory": {},
    "checks": [
        {}
    ],
    "jobs": [
        {}
    ]
}

401Missing or invalid credentials

FieldTypeDescription
error string

403Authenticated but not permitted

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string
GET /endpoint_devices/{id}/jobs Bearer token or API key

Job history for a device

Parameters

NameInTypeDescription
idrequiredpathinteger

Example request

curl "https://YOUR-HOST/api/v1/endpoint_devices/1/jobs" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.get(
    "https://YOUR-HOST/api/v1/endpoint_devices/1/jobs",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/endpoint_devices/1/jobs", {
  method: "GET",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/endpoint_devices/1/jobs");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Jobs

FieldTypeDescription
data array of object
Example response
json
{
    "data": [
        {}
    ]
}

404Resource not found

FieldTypeDescription
error string
POST /endpoint_devices/{id}/jobs Bearer token or API key

Queue a maintenance job (PowerShell, saved script, collect, reboot)

Authorization is decided server-side per call: free-form PowerShell needs module_rmm_scripts level 3, a saved script, reboot or collect level 2, always with module_rmm view access and the device's department. Module-only logins are refused. A reboot or any destructive job needs "confirm": true and is never retried automatically.

Parameters

NameInTypeDescription
idrequiredpathinteger

Request body (application/json, required)

FieldTypeDescription
typerequired string (powershell | reboot | collect)
script string
script_id integer A saved PowerShell script from the RMM script library
params object Scalar values only (strings, whole numbers, booleans)
timeout_s integer
destructive boolean
confirm boolean Required for reboot and destructive jobs

Example request

curl -X POST "https://YOUR-HOST/api/v1/endpoint_devices/1/jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"powershell","script":"string","script_id":1,"params":{},"timeout_s":1,"destructive":true,"confirm":true}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/endpoint_devices/1/jobs",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "type": "powershell",
        "script": "string",
        "script_id": 1,
        "params": {},
        "timeout_s": 1,
        "destructive": True,
        "confirm": True
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/endpoint_devices/1/jobs", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
      "type": "powershell",
      "script": "string",
      "script_id": 1,
      "params": {},
      "timeout_s": 1,
      "destructive": true,
      "confirm": true
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/endpoint_devices/1/jobs");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"type":"powershell","script":"string","script_id":1,"params":{},"timeout_s":1,"destructive":true,"confirm":true}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

201Queued

FieldTypeDescription
job_id string
state string
Example response
json
{
    "job_id": "string",
    "state": "string"
}

403Authenticated but not permitted

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string

422Invalid or confirmation_required

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal
POST /endpoint_devices/{id}/jobs/{job_id}/cancel Bearer token or API key

Cancel a queued job

Parameters

NameInTypeDescription
idrequiredpathinteger
job_idrequiredpathstring

Example request

curl -X POST "https://YOUR-HOST/api/v1/endpoint_devices/1/jobs/1/cancel" \
  -H "Authorization: Bearer $TOKEN"
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/endpoint_devices/1/jobs/1/cancel",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/endpoint_devices/1/jobs/1/cancel", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}` },
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/endpoint_devices/1/jobs/1/cancel");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Success

FieldTypeDescription
ok boolean
Example response
json
{
    "ok": true
}

403Authenticated but not permitted

FieldTypeDescription
error string

404Resource not found

FieldTypeDescription
error string

409Only a queued job can be cancelled

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal
POST /endpoint_devices/{id}/remote Bearer token or API key

Launch a MeshCentral remote session for a device

Needs module_rmm_remote_connect, module_rmm view, the device's department, and a device mapped to a MeshCentral node. Returns a one-time login URL minted for this request (never stored or logged) and a safe session id. Unmapped is 404, offline/not configured/retired 409 (set force to launch an offline-looking device anyway), MeshCentral unreachable 503.

Parameters

NameInTypeDescription
idrequiredpathinteger

Request body (application/json)

FieldTypeDescription
force boolean

Example request

curl -X POST "https://YOUR-HOST/api/v1/endpoint_devices/1/remote" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"force":true}'
import requests

response = requests.post(
    "https://YOUR-HOST/api/v1/endpoint_devices/1/remote",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "force": True
    },
)
print(response.json())
const response = await fetch("https://YOUR-HOST/api/v1/endpoint_devices/1/remote", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
      "force": true
  }),
});
const data = await response.json();
$ch = curl_init("https://YOUR-HOST/api/v1/endpoint_devices/1/remote");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"force":true}',
]);
$data = json_decode(curl_exec($ch), true);

Responses

200Launch URL

FieldTypeDescription
url string
session_id string
Example response
json
{
    "url": "string",
    "session_id": "string"
}

403Authenticated but not permitted

FieldTypeDescription
error string

404Not found, or code unmapped

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

409device_offline, not_configured or device_retired

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal

503MeshCentral unavailable

FieldTypeDescription
errorrequired string
coderequired string invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal