Agent and connector API
These endpoints are used by agents and connectors only. They are not part of the portal's OpenAPI spec; their message formats are on Agent and connector protocol.
- Requests authenticate with
Authorization: Bearer <agent or connector key>. Keys are stored as SHA-256 hashes and cached for 60 s; a revoked key's WebSocket is closed at once with code 4003 on every replica. - The per-IP rate limit of
/api/v1does not apply here (many agents share NAT addresses); only enrollment is limited (RMM_ENROLL_RATE_PER_MINUTE). - Unknown JSON fields are ignored, so newer agents keep working with older servers.
Agent (/api/agent/v1)
| Method | Path | Notes |
|---|---|---|
| POST | /enroll | {enrollment_token, hostname, fqdn, domain, machine_guid, machine_sid, os, agent_version} → 201 {agent_id, device_id, agent_key, ws_url, config}. 401 unknown token, 409 exhausted, 410 expired or revoked, 422 invalid request. Re-enrolling the same machine (matched by machine_guid, then machine_sid) keeps the device and rotates the key. |
| GET | /ws | WebSocket upgrade. |
| GET | /config | Current agent config (intervals, feature flags). |
| GET | /jobs/pending | HTTP fallback polling when WebSockets are blocked. |
| POST | /jobs/{id}/ack, /jobs/{id}/progress, /jobs/{id}/result | HTTP fallback. |
| PUT | /jobs/{id}/output | Full output of a run_script job (Content-Encoding: gzip, text, at most 10 MiB) → 204. |
| POST | /inventory | Full or delta report, also used when a report exceeds the 1 MB WebSocket frame. Content-Encoding: gzip accepted; 32 MB on the wire, 64 MB decoded. |
| POST | /heartbeat | HTTP fallback. |
| GET | /packages/{id}/download-url | {url, sha256, size_bytes, expires_at}: a fresh one-hour link for a ready package of the agent's tenant or a global one; 404 otherwise. |
| GET | /releases/winget | {files: [{name, url, size_bytes, role: bundle or dependency}]}: the App Installer files under releases/winget/; 404 winget_bootstrap_unavailable when none are hosted. |
| GET | /releases/latest?component=agent&channel=stable | {version, url, sha256, signature}. |
Connector (/api/connector/v1)
| Method | Path | Notes |
|---|---|---|
| POST | /enroll | {enrollment_token, hostname, domain, version} → 201 {connector_id, connector_key, ws_url}. Only tokens of kind connector (401 otherwise). The same machine (tenant, hostname, domain) re-enrolling rotates its key and closes the old connection. |
| GET | /ws | WebSocket; the server pushes adsync.run, ldap.test, ldap.ous, push_agent, wake, update_agent jobs. |
| POST | /heartbeat | HTTP fallback. |
| GET | /jobs/pending | HTTP fallback. |
| POST | /jobs/{id}/ack, /jobs/{id}/progress, /jobs/{id}/result | HTTP fallback. |
| POST | /adsync/runs/{id}/chunk | {seq, computers[], complete, total?} (at most 1,000 computers) for chunks above the WebSocket frame limit; gzip accepted, 16 MiB → 202. |
| POST | /push/targets | HTTP fallback of push.target. |
| GET | /releases/latest?component=connector | Latest connector release. |