API reference / RivetIT
RivetIT API
v1.0.0 141 endpoints OpenAPI 3
Companion REST API for RivetIT, consumed by the RivetIT mobile app and other integrations (RMM scripts and the like). This spec documents the live endpoints served by /api/v1/index.php and its per-resource handlers.
Authentication. There are two kinds of credential:
-
API keys (machines; the primary method: a Client ID + secret). Create a client under Administration > API Keys, exchange its Client ID and secret at
POST /oauth/token(OAuth2 client credentials) for a 10 minute signed access token and send it asAuthorization: Bearer <access token>. A token reaches a route only if it holds that route's scope (api:<resource>:read|write|delete,lms:*,directory:read); there is no wildcard, and the client's department scope applies. It never acts as a user or an administrator. -
User session tokens (a signed-in person, e.g. the mobile app): a bearer token issued by
POST /auth. Unrelated to integration clients and unchanged.
The old X-Api-Key header (legacy API keys) is not accepted any more: a request that sends it without a valid token is answered 401 with a message pointing at POST /oauth/token. Existing integrations must switch to an API key's Client ID + secret.
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.
-
integrationClient
oauth2
Primary machine authentication. OAuth2 client credentials: POST /oauth/token with grant_type=client_credentials, the integration client's Client ID and secret (form body or HTTP Basic) returns a 10 minute signed access token; send it as a Bearer token. The token carries the scopes the client holds (ask for fewer with the
scopeparameter). Deny by default, no wildcard; the client's department scope applies. -
integrationAuth
http, bearer
Access token from POST /oauth/token (an integration client, 10 minutes). It reaches a route only if it holds that route's scope (lms:*, directory:read, api:<resource>:read|write|delete); a route with no scope answers 403.
-
bearerAuth
http, bearer
User session token issued by POST /api/v1/auth (a signed-in person, e.g. the mobile app). Not an integration credential.
-
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.
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
/projectsList projects (paged, filterable) Projects -
GET
/projects/{id}Project detail with milestones, tasks and linked tickets Projects -
GET
/contractsList contracts (paged, filterable). Billing-adjacent client data - requires module_client. Contracts -
GET
/contracts/{id}Contract detail with SLA, current-month hours-allowance usage, and documents Contracts -
POST
/tasksCreate a project task (scope api:tasks:write; project_id and name required) Projects -
GET
/tasks/{id}One task, with priority, description, colour and labels Projects -
PUT
/tasks/{id}Same as PATCH (only the fields sent change) Projects -
PATCH
/tasks/{id}Change the fields sent (scope api:tasks:write); PUT behaves the same Projects -
DELETE
/tasks/{id}Delete a task and its label links (scope api:tasks:delete; Service Desk level 3) Projects -
GET
/tasks/{id}/checklistA task's checklist items (database 2.6.208) Projects -
POST
/tasks/{id}/checklistAdd a checklist item at the end (scope api:tasks:write) Projects -
PATCH
/tasks/{id}/checklist/{itemId}Change an item's text and/or done flag (scope api:tasks:write) Projects -
DELETE
/tasks/{id}/checklist/{itemId}Delete an item (scope api:tasks:delete) Projects -
GET
/tasks/{id}/subtasksA task's subtasks (database 2.6.208) Projects -
POST
/tasks/{id}/subtasksCreate a subtask (scope api:tasks:write). A subtask cannot have subtasks. Projects -
GET
/tasks/{id}/commentsA task's comments, oldest first (database 2.6.208) Projects -
POST
/tasks/{id}/commentsAdd a comment as the caller (scope api:tasks:write) Projects -
PATCH
/tasks/{id}/comments/{commentId}Edit a comment (its author only; scope api:tasks:write) Projects -
DELETE
/tasks/{id}/comments/{commentId}Delete a comment (its author, or an administrator; scope api:tasks:delete) Projects -
GET
/tasks/{id}/attachmentsMetadata of a task's files (database 2.6.209); never the stored name Projects -
POST
/tasks/{id}/attachmentsAttach a file (multipart/form-data, field "file"; scope api:tasks:write). Scripts, web pages and installers are refused; up to 25 MB and 50 files per task. Projects -
GET
/tasks/{id}/attachments/{attachmentId}Download a file (always sent as an attachment, application/octet-stream, nosniff) Projects -
DELETE
/tasks/{id}/attachments/{attachmentId}Delete a file (the uploader, or Service Desk level 3 / an administrator; scope api:tasks:delete) Projects -
POST
/tasks/{id}/toggleToggle a task's completed state (works for both project-only tasks and ticket-linked tasks) Projects -
POST
/milestones/{id}/toggleToggle a project milestone's completed state Projects -
GET
/credentialsList credentials (names/URIs only, no secrets; paged). Requires a user token (API keys are denied). Credentials -
GET
/credentials/{id}Decrypted credential detail — requires a signed biometric step-up challenge Credentials -
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
/searchGlobal search across tickets, clients, assets, software, networks, services, contacts, credentials, KB articles 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/rmm-healthRMM fleet health report Reports -
GET
/reports/unbilled-ticketsClients with unbilled billable closed tickets 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 (API keys are 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
/approvalsApprovals the caller may decide right now (service catalog requests + workflow approval tasks) Mobile -
POST
/approvalsApprove or reject one approval Mobile -
GET
/service_catalogActive service catalog items with their request forms Mobile -
POST
/service_catalogRaise a ticket from a catalog item Mobile -
GET
/workflow_tasksOpen onboarding/offboarding checklist tasks Mobile -
POST
/workflow_tasksComplete or skip a checklist task Mobile -
GET
/ticket_attachmentsList a ticket's attachments, or download one Mobile -
POST
/ticket_attachmentsUpload one attachment (multipart) Mobile -
GET
/alertsList combined RMM and backup alerts Alerts -
POST
/alertsAcknowledge or resolve an alert Alerts -
GET
/validate_api_keyValidate the presented access token (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-department 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
/endpoint_devicesList endpoint agent devices in the caller's departments 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 -
POST
/oauth/tokenOAuth2 client-credentials token for an integration client Integration -
GET
/lms/coursesPublished course catalog Integration -
GET
/lms/courses/{id}One published course Integration -
GET
/lms/assignmentsList assignments Integration -
POST
/lms/assignmentsCreate (or reuse) an assignment Integration -
GET
/lms/assignments/{id}One assignment Integration -
GET
/lms/completionsList completions Integration -
GET
/lms/completions/{id}One completion Integration -
GET
/lms/completions/{id}/evidenceThe completion's evidence file Integration -
GET
/employeesEmployee directory Integration -
GET
/employees/{id}One employee Integration -
GET
/departmentsDepartment directory Integration -
GET
/departments/{id}One department Integration