API reference / RivetMSP
RivetMSP API
v1.0.0 110 endpoints OpenAPI 3
Companion REST API for RivetMSP, consumed by the RivetMSP mobile app and integrations (ITPanel Pro, RMM scripts). This spec documents the live endpoints served by /api/v1/index.php and its per-resource handlers.
Authentication: send a bearer token issued by POST /auth (Authorization: Bearer <token>) OR a legacy instance API key (X-Api-Key: <key>). The legacy key resolves to the first active admin and is intentionally denied on /credentials and /me. The /auth, /branding, /openapi and /docs endpoints are public (no token required).
Response conventions:
- Paged list endpoints return
{ "data": [ ... ], "total": <int> }(some also addpage/limit). - Some list endpoints return a bare JSON array (noted per-endpoint).
- Creates return
{ "id": <int> }(sometimes with extra fields). - Simple mutations return
{ "ok": true }. - Errors return
{ "error": "<message>" }with the matching HTTP status.
Base URL and authentication
Requests go to https://YOUR-HOST/api/v1, where YOUR-HOST is your own install.
-
bearerAuth
http, bearer
Token issued by POST /api/v1/auth
-
deviceAuth
http, bearer
Per-device credential issued by POST /agent_enroll (256-bit, only its SHA-256 stored, rotatable and revocable). Not a user token.
-
ApiKeyAuth
apiKey in header (X-Api-Key)
Legacy instance-wide API key (denied on /credentials and /me)
Quick start
-
1Get a token
Password login — returns a bearer token, or requires_2fa. Keep the token and send it as a bearer token on every call.
curl -X POST "https://YOUR-HOST/api/v1/auth" \ -H "Content-Type: application/json" \ -d '{"username":"string","password":"string"}'import requests response = requests.post( "https://YOUR-HOST/api/v1/auth", json={ "username": "string", "password": "string" }, ) print(response.json())const response = await fetch("https://YOUR-HOST/api/v1/auth", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ "username": "string", "password": "string" }), }); const data = await response.json();$ch = curl_init("https://YOUR-HOST/api/v1/auth"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => ["Content-Type: application/json"], CURLOPT_POSTFIELDS => '{"username":"string","password":"string"}', ]); $data = json_decode(curl_exec($ch), true);Example response
json{ "token": "string", "user": { "id": 1, "name": "string", "email": "string", "type": 1 } } -
2Make your first request
List tickets. Replace
TOKENwith the token from step 1.curl "https://YOUR-HOST/api/v1/tickets" \ -H "Authorization: Bearer $TOKEN"import requests response = requests.get( "https://YOUR-HOST/api/v1/tickets", headers={"Authorization": f"Bearer {TOKEN}"}, ) print(response.json())const response = await fetch("https://YOUR-HOST/api/v1/tickets", { method: "GET", headers: { "Authorization": `Bearer ${TOKEN}` }, }); const data = await response.json();$ch = curl_init("https://YOUR-HOST/api/v1/tickets"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"], ]); $data = json_decode(curl_exec($ch), true);
Find an endpoint
-
GET
/brandingPublic company identity for mobile sign-in and app branding Auth -
GET
/authBegin a WebAuthn/passkey assertion — returns a challenge Auth -
POST
/authPassword login — returns a bearer token, or requires_2fa Auth -
DELETE
/authLogout — revoke the current bearer token Auth -
POST
/crash-reportsReport a mobile app crash (logged to App Logs, category "mobile_crash") Diagnostics -
GET
/csatAggregate CSAT rating summary for public embedding (e.g. a website trust badge) Public -
GET
/dashboardAgent dashboard counters and personal ticket queue Dashboard -
GET
/ticketsList tickets (paged, filterable) Tickets -
POST
/ticketsCreate a ticket (JSON or multipart with files) Tickets -
GET
/tickets/{id}Ticket detail with replies and attachments Tickets -
POST
/tickets/{id}/replyAdd a reply or internal note (JSON or multipart with files) Tickets -
DELETE
/tickets/{id}/reply/{replyId}Delete a reply (and its attachments) Tickets -
POST
/tickets/{id}/timeLog time against a ticket (creates an internal reply) Tickets -
POST
/tickets/{id}/statusChange ticket status (setting a Closed status resolves it) Tickets -
POST
/tickets/{id}/attachmentsUpload one or more attachments to a ticket Tickets -
GET
/tickets/{id}/chatLive-chat messages for a ticket (add ?stream=1 for an SSE feed) Tickets -
POST
/tickets/{id}/chatSend a live-chat message Tickets -
GET
/tickets/{id}/chargesList charges on a ticket Tickets -
POST
/tickets/{id}/chargesAdd a charge to a ticket Tickets -
GET
/tickets/{id}/worksheetsList worksheets attached to a ticket Worksheets -
POST
/tickets/{id}/worksheetsCreate a worksheet on a ticket from a template Worksheets -
GET
/tickets/{id}/outtakesList device-outtake (pickup) forms for a ticket Outtakes -
POST
/tickets/{id}/outtakeCreate a device-outtake form on a ticket Outtakes -
GET
/statusesList active ticket statuses (bare array) Ticket Meta -
GET
/ticket-categoriesList ticket categories (bare array) Ticket Meta -
GET
/ticket-viewsList saved ticket views translated to list query params (bare array) Ticket Meta -
GET
/clientsList clients (paged) Clients -
GET
/clients/{id}Client detail with contacts and primary location Clients -
GET
/clients/{id}/ticketsRecent tickets for a client (bare array) Clients -
GET
/clients/{id}/assetsAssets for a client (bare array) Clients -
GET
/clients/{id}/locationsLocations for a client (bare array) Clients -
GET
/clients/{id}/credentialsCredential names for a client (no secrets; bare array) Clients -
GET
/clients/{id}/contractsContracts for a client (bare array) Clients -
GET
/clients/{id}/filesSigned outtake forms for a client (bare array) Clients -
GET
/clients/{id}/allowanceIncluded support-hours allowance vs. usage for a calendar month, rolled up across the client's active contracts plus a per-contract breakdown Clients -
GET
/contactsList contacts (paged, filterable by client) Contacts -
GET
/assetsList assets (paged, filterable) Assets -
GET
/assets/typesDistinct asset types in use (bare string array) Assets -
GET
/assets/{id}Asset detail Assets -
GET
/relationshipsLinks of one record (outgoing, referenced by, and what depends on it) Relationships -
POST
/relationshipsLink two records Relationships -
DELETE
/relationships/{id}Remove a link (derived rows cannot be removed here) Relationships -
GET
/credentialsList credentials (names/URIs only, no secrets; paged). Requires a user token — legacy API key is denied. Credentials -
GET
/credentials/{id}Decrypted credential detail — requires a signed biometric step-up challenge Credentials -
GET
/quotesList quotes (paged) Quotes -
GET
/quotes/{id}Quote detail with line items Quotes -
GET
/invoicesList invoices (paged) Invoices -
GET
/invoices/{id}Invoice detail with line items Invoices -
GET
/expensesList expenses (paged) Expenses -
POST
/expensesCreate an expense (multipart, optional receipt upload) Expenses -
GET
/worksheets/{id}Worksheet detail with fields and current responses Worksheets -
DELETE
/worksheets/{id}Delete a worksheet Worksheets -
POST
/worksheets/{id}/signSign a worksheet Worksheets -
POST
/worksheets/{id}/completeMark a worksheet complete or incomplete without signing Worksheets -
POST
/worksheets/{id}/responsesSave worksheet field responses (marks complete) Worksheets -
GET
/worksheet-templatesList worksheet templates (bare array) Worksheets -
GET
/outtakes/{id}Outtake form detail Outtakes -
DELETE
/outtakes/{id}Delete an outtake form Outtakes -
POST
/outtakes/{id}/signSign an outtake form Outtakes -
GET
/productsList products/services for charge selection (bare array) Products -
GET
/searchGlobal search across tickets, clients, assets, software, networks, services and linked records Search -
GET
/reports/timeTime logged grouped by client Reports -
GET
/reports/ticketsTicket volume by month for a year Reports -
GET
/reports/tickets-by-clientTicket counts by client Reports -
GET
/reports/time-by-techTime logged grouped by technician Reports -
GET
/reports/tech-performanceTechnician performance summary Reports -
GET
/reports/technician-performanceDetailed technician performance report Reports -
GET
/reports/service-deskService-desk report Reports -
GET
/reports/csatCustomer satisfaction (CSAT) report - 1-5 star ratings, distribution, trend, per-technician/per-client breakdowns, raw feedback feed Reports -
GET
/reports/mrrMonthly recurring revenue report Reports -
GET
/reports/rmm-healthRMM fleet health report Reports -
GET
/reports/unbilled-ticketsClients with unbilled billable closed tickets Reports -
GET
/reports/clients-with-balanceClients carrying an outstanding balance Reports -
GET
/reports/income-summaryIncome summary for a year Reports -
GET
/reports/expense-summaryExpense summary for a year Reports -
GET
/reports/profit-lossMonthly profit and loss for a year Reports -
GET
/reports/expiringDomains or certificates expiring within N days Reports -
GET
/reports/overviewOpen-ticket breakdown by priority/status/category plus avg resolution Reports -
GET
/kb/categoriesList KB categories (bare array) Knowledge Base -
GET
/kb/articlesList KB articles (paged, filterable) Knowledge Base -
GET
/kb/articles/{id}KB article detail (content + attachments) Knowledge Base -
GET
/meCurrent user profile. Requires a user token — legacy API key is denied. Profile -
POST
/meUpdate profile / password (alias of PUT - FCM push and biometric key registration require PUT) Profile -
PUT
/meUpdate profile / password, or register FCM push or biometric key Profile -
GET
/appointmentsList ticket appointments (bare array) Appointments -
POST
/appointmentsCreate a ticket appointment (schedule entry) Appointments -
GET
/notificationsList undismissed notifications (paged) Notifications -
POST
/notifications/{id}/readMark a single notification read/dismissed Notifications -
POST
/notifications/read-allMark all notifications read/dismissed Notifications -
GET
/notifications/streamServer-Sent Events stream of new notifications Notifications -
GET
/alertsList combined RMM and backup alerts Alerts -
POST
/alertsAcknowledge or resolve an alert Alerts -
GET
/validate_api_keyValidate the presented token/key (legacy compatibility probe) Meta -
GET
/openapiThis OpenAPI 3.0 spec as YAML (public) Meta -
GET
/docsHuman-readable HTML API reference (public, self-contained) Meta -
POST
/agent_enrollEnroll a Windows endpoint agent (device-facing, no Bearer) Endpoint agent -
POST
/agent_checkinDevice check-in: inventory, metrics, checks (device credential) Endpoint agent -
GET
/agent_jobsFetch this device's signed jobs (device credential, optional long poll) Endpoint agent -
POST
/agent_jobsReport a job's state or result (device credential) Endpoint agent -
POST
/agent_installerDownload the stamped per-client installer with an enrollment token (for RMM, Intune, GPO scripts) Endpoint agent -
GET
/agent_updateDownload the hosted agent release this device is currently offered (device credential) Endpoint agent -
GET
/agent_transferRead a range of a file the server holds for this device (device credential + one-time transfer token; file transfer switch) Endpoint agent -
POST
/agent_transferSend one chunk of a file to the server (device credential + one-time transfer token; file transfer switch) Endpoint agent -
POST
/agent_logsShip a batch of collected log entries (device credential; log collection switch) Endpoint agent -
GET
/endpoint_devicesList endpoint agent devices in the caller's clients Endpoint agent -
GET
/endpoint_devices/{id}Device detail with inventory, checks and recent jobs Endpoint agent -
GET
/endpoint_devices/{id}/jobsJob history for a device Endpoint agent -
POST
/endpoint_devices/{id}/jobsQueue a maintenance job (PowerShell, saved script, collect, reboot) Endpoint agent -
POST
/endpoint_devices/{id}/jobs/{job_id}/cancelCancel a queued job Endpoint agent -
POST
/endpoint_devices/{id}/remoteLaunch a MeshCentral remote session for a device Endpoint agent