Endpoint agent
- POST/agent_enroll
- POST/agent_checkin
- GET/agent_jobs
- POST/agent_jobs
- POST/agent_installer
- GET/agent_update
- GET/endpoint_devices
- GET/endpoint_devices/{id}
- GET/endpoint_devices/{id}/jobs
- POST/endpoint_devices/{id}/jobs
- POST/endpoint_devices/{id}/jobs/{job_id}/cancel
- POST/endpoint_devices/{id}/remote
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)
| Field | Type | Description |
|---|---|---|
| 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
| Field | Type | Description |
|---|---|---|
| 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
{
"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
| Field | Type | Description |
|---|---|---|
| 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)
| Field | Type | Description |
|---|---|---|
| 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)
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
413Body too large
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
422Invalid body (code invalid)
| Field | Type | Description |
|---|---|---|
| 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)
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
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)
| Field | Type | Description |
|---|---|---|
| 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
| Field | Type | Description |
|---|---|---|
| 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
{
"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
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
403Service disabled
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
413Body over 1 MiB
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
422Invalid payload
| Field | Type | Description |
|---|---|---|
| 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)
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
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
| Name | In | Type | Description |
|---|---|---|---|
| wait | query | integer |
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)
| Field | Type | Description |
|---|---|---|
| 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
{
"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
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
429Rate limited
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
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)
| Field | Type | Description |
|---|---|---|
| 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
| Field | Type | Description |
|---|---|---|
| ok | boolean |
Example response
{
"ok": true
}
401Credential invalid
| Field | Type | Description |
|---|---|---|
| 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
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
409Conflict
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
413Body over 256 KiB
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
422Invalid body
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
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)
| Field | Type | Description |
|---|---|---|
| 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
"string"
400Token supplied in the query string (code token_in_url)
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
403Service disabled
| Field | Type | Description |
|---|---|---|
| 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
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
405Use POST
| Field | Type | Description |
|---|---|---|
| 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)
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
413Body over 4 KiB
| Field | Type | Description |
|---|---|---|
| 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
| Field | Type | Description |
|---|---|---|
| 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)
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
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
| Name | In | Type | Description |
|---|---|---|---|
| archrequired | query | string (amd64 | arm64) | |
| versionrequired | query | string |
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
"string"
401Credential invalid_token, revoked or expired
| Field | Type | Description |
|---|---|---|
| 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)
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
422arch or version invalid
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
429Rate limited
| Field | Type | Description |
|---|---|---|
| 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
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
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
| Name | In | Type | Description |
|---|---|---|---|
| limit | query | integer | |
| offset | query | integer | |
| status | query | string |
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
| Field | Type | Description |
|---|---|---|
| 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
{
"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
| Field | Type | Description |
|---|---|---|
| error | string |
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
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
| Name | In | Type | Description |
|---|---|---|---|
| idrequired | path | integer |
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
| Field | Type | Description |
|---|---|---|
| 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
{
"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
| Field | Type | Description |
|---|---|---|
| error | string |
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
404Resource not found
| Field | Type | Description |
|---|---|---|
| error | string |
Job history for a device
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| idrequired | path | integer |
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
| Field | Type | Description |
|---|---|---|
| data | array of object |
Example response
{
"data": [
{}
]
}
404Resource not found
| Field | Type | Description |
|---|---|---|
| error | string |
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
| Name | In | Type | Description |
|---|---|---|---|
| idrequired | path | integer |
Request body (application/json, required)
| Field | Type | Description |
|---|---|---|
| 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
| Field | Type | Description |
|---|---|---|
| job_id | string | |
| state | string |
Example response
{
"job_id": "string",
"state": "string"
}
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
404Resource not found
| Field | Type | Description |
|---|---|---|
| error | string |
422Invalid or confirmation_required
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
Cancel a queued job
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| idrequired | path | integer | |
| job_idrequired | path | string |
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
| Field | Type | Description |
|---|---|---|
| ok | boolean |
Example response
{
"ok": true
}
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
404Resource not found
| Field | Type | Description |
|---|---|---|
| error | string |
409Only a queued job can be cancelled
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
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
| Name | In | Type | Description |
|---|---|---|---|
| idrequired | path | integer |
Request body (application/json)
| Field | Type | Description |
|---|---|---|
| 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
| Field | Type | Description |
|---|---|---|
| url | string | |
| session_id | string |
Example response
{
"url": "string",
"session_id": "string"
}
403Authenticated but not permitted
| Field | Type | Description |
|---|---|---|
| error | string |
404Not found, or code unmapped
| Field | Type | Description |
|---|---|---|
| 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
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |
503MeshCentral unavailable
| Field | Type | Description |
|---|---|---|
| errorrequired | string | |
| coderequired | string | invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal |