Skip to content

Docs / RivetMSP / Reference

RivetMSP REST API

The narrative guide to the /api/v1 REST API that powers the Android app.

What this is#

RivetMSP ships a REST API used by the RivetMSP mobile app, ITPanel Pro, RMM automation scripts, and any custom tooling you want to build against your RivetMSP instance. It's the same API surface the built-in mobile app runs on — nothing about it is a stripped-down or read-only subset held back from external integrations.

Base path: all endpoints below are relative to /api/v1 on your RivetMSP install, e.g. https://your-instance.example.com/api/v1/tickets.

Versioning: the API is currently unversioned beyond the /v1 path segment (spec version 1.0.0 in info.version). There is no v2 today; breaking changes would arrive under a new path prefix rather than silently changing /v1 behavior.

Machine-readable spec: the full OpenAPI 3.0 document is served live from the running instance at GET /api/v1/openapi.yaml. Import it into Swagger UI, Postman, or Insomnia to browse and try every endpoint interactively, including full request/response JSON Schemas that this document intentionally does not restate in full (see Where to find full schemas).

Human-readable browsing: the same spec is also rendered as a searchable, dark-console-styled HTML reference at GET /api/v1/docs (also linked from Settings → API Docs in the admin panel). It's generated live from openapi.yaml, so it's always in sync with what the server actually does.

This document is a narrative companion to those two — read this first to understand the shape of the API and how auth/pagination/errors work, then use /openapi or /docs for the exact fields on any one endpoint.


Authentication#

Every endpoint except the handful marked public below requires one of two credentials, sent on every request:

A per-user token issued by POST /api/v1/auth (password or passkey login — see Auth). This is the primary mechanism for anything acting as a specific technician or contact: the mobile app, a personal automation script, anything where "who did this" matters. Tokens are revoked with DELETE /api/v1/auth (logout).

Use bearer tokens when you need:

  • Actions attributed to a specific user (ticket replies, time entries, worksheet signatures)
  • Access to /me or /credentials (both explicitly deny legacy API keys — see below)
  • Push token / biometric key registration (mobile app)

2. X-Api-Key: <key> — legacy instance API keys#

A long-lived, instance-wide key managed under Settings → API Keys in the admin panel. It resolves internally to the instance's first active admin user rather than to a specific person, which is why it's blocked from /credentials (decrypted secrets) and /me (a per-user profile) — there's no real "current user" to answer either request as.

Legacy keys are a good fit for server-to-server integrations and scripts that aren't acting as any one technician: RMM webhook receivers, backup-report ingestion, nightly export jobs, that kind of thing.

Two scoping options apply to a legacy key, both set when creating/editing it under Settings → API Keys:

  • Client scope — a key can be locked to a single client, in which case every client-scoped resource (tickets, assets, credentials list, contracts, etc.) is filtered to that client and cross-client requests are rejected.
  • Permission (read / write) — new in this release. A key's Permission field is either write (the default — full access, same as before) or read. A read key may only issue GET requests; any POST/PUT/PATCH/DELETE with a read-only key is rejected with 403 {"error": "This API key is read-only"} before it reaches the resource handler. Use a read-only key for anything that only needs to pull data (dashboards, reporting pulls, read-only RMM lookups) so a leaked key can't be used to modify data.

Public endpoints (no credential required)#

A small set of endpoints are intentionally reachable with no Authorization header and no X-Api-Key at all:

Endpoint Why
POST /auth, GET /auth You don't have a token yet — this is how you get one.
POST /crash-reports Semi-public: honors a bearer token when present (for correlation) but never requires one, because the crash worth capturing most is often the one that happens before login succeeds or while a token has just expired.
GET /csat Fully public aggregate rating summary, meant to be embedded on a public marketing site (see Public).
GET /openapi, GET /docs The spec and its rendered reference need to be readable before you have credentials to explore anything else.

Biometric step-up (credential secrets only)#

Decrypted credential secrets (GET /credentials/{id}) require more than a bearer token: a signed biometric challenge, on top of normal auth. The flow is:

  1. Call GET /auth to obtain a challenge (PasskeyBeginResponse, including a challengeToken).
  2. Sign the challenge locally with the device's registered biometric key (registered previously via PUT /me with device_public_key_pem).
  3. Send the request with two extra headers: X-Biometric-Challenge-Token: <challengeToken> and X-Biometric-Signature: <base64 signature>.

This is the same challenge mechanism used for passkey login completion — GET /auth is the one place a challenge originates from, whether you're about to complete a passkey login or about to prove device possession to unseal a credential.


Conventions#

These hold across (almost) every endpoint; exceptions are called out per-endpoint in the tables below.

Lists return a JSON object:

{ "data": [ ... ], "total": 137 }

Some paged endpoints also echo back page and limit. A handful of list endpoints intentionally return a bare JSON array instead of this envelope — usually small, unpaged reference lists (statuses, categories, asset types, worksheet templates) or nested "everything for this one client/ticket" lists. Each one is marked bare array in the tables below.

Creates return the new row's id:

{ "id": 4821 }

sometimes with a few extra fields alongside it (e.g. ticket creation also returns number and any attachments uploaded with it).

Simple mutations (status changes, marking things read, signing, acknowledging alerts) return:

{ "ok": true }

Errors are always a JSON object with an error string, paired with the matching HTTP status code:

{ "error": "Ticket not found" }

Common status codes you'll see: 400 (bad request — missing/invalid fields), 401 (missing or invalid credential), 403 (authenticated but not permitted — wrong client scope, read-only key doing a write, missing biometric step-up), 404 (not found), 429 (rate limited).

Pagination — where supported, page (default 1) and limit (default 20) query parameters control paging; combine with total in the response to compute page count. Most list endpoints also accept a search query parameter for a simple text filter, and many accept resource-specific filters (client_id, status, priority, etc. — see each endpoint's table row and the OpenAPI spec for the exact parameter set).

Rate limiting — 300 requests per 60 seconds per caller (per token or per API key; unauthenticated callers are limited by IP). Exceeding it returns 429 with a Retry-After header telling you how many seconds to wait. POST /crash-reports has its own tighter limit (20 requests / 5 minutes per IP) since it's reachable without auth.

Content types — most endpoints take application/json. A few accept file uploads and support either application/json or multipart/form-data on the same route (ticket creation, ticket replies); a few are multipart-only (attachments, expense receipts). These are noted per-endpoint below.

Streaming — two endpoints (GET /tickets/{id}/chat?stream=1 and GET /notifications/stream) return text/event-stream (Server-Sent Events) instead of a single JSON response. Treat these as long-lived connections (EventSource in a browser, or an HTTP client that doesn't buffer/timeout the response) rather than a normal request/response call.

Where to find full schemas#

To keep this document maintainable and accurate, it does not attempt to reproduce full request/response JSON Schemas for all 91 endpoints. For the exact shape of any request body or response — field names, types, which fields are required, enum values — use:

  • GET /api/v1/openapi.yaml — the canonical OpenAPI 3.0 document, importable into Swagger UI / Postman / Insomnia for interactive "try it" requests against your own instance.
  • GET /api/v1/docs (or Settings → API Docs in the admin panel) — the same spec rendered as a searchable human-readable page.

Quick start#

A minimal end-to-end flow: log in, list open tickets, create one, reply to it.

1. Log in with a username/password

curl -X POST https://your-instance.example.com/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
        "username": "jdoe",
        "password": "correct horse battery staple",
        "device_name": "jdoe-macbook"
      }'

Response is either a token:

{ "token": "eyJ...", "user": { "id": 7, "name": "Jane Doe", "email": "[email protected]", "type": 3 } }

or, if the account has 2FA enabled:

{ "requires_2fa": true }

— in which case re-POST the same request with a totp_code field added.

Save the token and send it as Authorization: Bearer <token> on every subsequent request. (Passkey/WebAuthn login instead begins with GET /auth for a challenge, then POST /auth with passkey_response + challenge_token.)

2. List your open tickets

curl -H "Authorization: Bearer $TOKEN" \
  "https://your-instance.example.com/api/v1/tickets?status=open&mine=1&limit=20"

3. Create a ticket

curl -X POST https://your-instance.example.com/api/v1/tickets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "subject": "Printer offline",
        "details": "Front desk printer is not responding to print jobs.",
        "client_id": 42,
        "priority": "medium"
      }'
{ "id": 1183, "number": 1183, "attachments": [] }

4. Reply to the ticket (and log time in the same call)

curl -X POST https://your-instance.example.com/api/v1/tickets/1183/reply \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "reply": "Power-cycled the printer and cleared a paper jam. Confirmed working.",
        "type": "reply",
        "time_worked": "00:15:00"
      }'

Using a legacy instance key instead of a bearer token — swap the Authorization header for X-Api-Key:

curl -H "X-Api-Key: $ITFLOW_API_KEY" \
  "https://your-instance.example.com/api/v1/clients"

Endpoint reference#

91 endpoints across 24 resource groups. Method color/verb meaning follows normal REST convention: GET read, POST create/action, PUT update, DELETE remove.

Auth#

Login (password or passkey), passkey challenge issuance, and logout. Public except logout.

Method Path Description
POST /auth Password login — returns a bearer token, or requires_2fa. Also accepts a completed passkey response. Public.
GET /auth Begin a WebAuthn/passkey assertion — returns a challenge (also reused for the credential biometric step-up flow). Public.
DELETE /auth Logout — revokes the current bearer token.

Dashboard#

The agent home-screen summary: open-ticket counters and the caller's personal ticket queue.

Method Path Description
GET /dashboard Agent dashboard counters and personal ticket queue.

Tickets#

Core service-desk workflow: list/create/view tickets, reply (with optional file attachments, inline or via a separate upload call), log time, change status, run the live chat channel, and add billable charges.

Method Path Description
GET /tickets List tickets — paged, filterable by status, status_id, mine, assigned, priority, onsite, category_id, board_id, tag_id, client_id, contact_id, overdue, due_today, search. priority, onsite, assigned, status_id, category_id, board_id and tag_id take several values (comma list or repeated name[]): OR inside a filter, AND between filters; overdue and due_today together match either.
POST /tickets Create a ticket (JSON or multipart with files). Requires subject.
GET /tickets/{id} Ticket detail with replies and attachments.
POST /tickets/{id}/reply Add a reply or internal note (JSON or multipart with files). Requires reply; type distinguishes reply/note/client-portal.
DELETE /tickets/{id}/reply/{replyId} Delete a reply and its attachments.
POST /tickets/{id}/time Log time against a ticket (creates an internal reply). Requires time_worked (HH:MM:SS).
POST /tickets/{id}/status Change ticket status; setting a Closed-type status resolves the ticket. Requires status_id.
POST /tickets/{id}/attachments Upload one or more attachments to a ticket (multipart).
GET /tickets/{id}/chat Live-chat messages for a ticket. Add ?stream=1 for a text/event-stream SSE feed instead of a JSON snapshot; since_id for incremental polling.
POST /tickets/{id}/chat Send a live-chat message. Requires message; optional contact_id to post on behalf of a client contact.
GET /tickets/{id}/charges List charges on a ticket, plus a running total.
POST /tickets/{id}/charges Add a charge to a ticket. Requires name; optional description, quantity, unit_price.

Ticket Meta#

Small reference lists used to populate ticket forms/filters in a client app.

Method Path Description
GET /statuses List active ticket statuses. Bare array.
GET /ticket-categories List ticket categories. Bare array.
GET /ticket-views List saved ticket views, translated into ready-to-use list query params (several values are comma lists); is_default marks the agent's default view. Bare array.

Clients#

Client records and everything scoped to one client — tickets, assets, locations, credential names, contracts, files, and (new) included-hours allowance usage.

Method Path Description
GET /clients List clients — paged, search.
GET /clients/{id} Client detail with contacts and primary location.
GET /clients/{id}/tickets Recent tickets for a client. Bare array.
GET /clients/{id}/assets Assets for a client. Bare array.
GET /clients/{id}/locations Locations for a client. Bare array.
GET /clients/{id}/credentials Credential names/URIs for a client — no secrets. Bare array.
GET /clients/{id}/contracts Contracts for a client. Bare array.
GET /clients/{id}/files Signed outtake (device pickup) forms for a client. Bare array.
GET /clients/{id}/allowance New. Included support-hours allowance vs. usage for a calendar month, rolled up across the client's active contracts plus a per-contract breakdown. Optional month (1-12) / year query params, default current month. When no active contract configures an allowance, included/remaining/pct come back null — treat that as "feature inactive," not zero.

Contacts#

Client contact records.

Method Path Description
GET /contacts List contacts — paged, filterable by client_id, search.

Assets#

Managed devices/equipment.

Method Path Description
GET /assets List assets — paged, filterable by type, client_id, search.
GET /assets/types Distinct asset types currently in use. Bare array of strings.
GET /assets/{id} Asset detail.

Credentials#

Stored client passwords/secrets. Both endpoints deny legacy X-Api-Key auth — a user bearer token is required.

Method Path Description
GET /credentials List credentials — names/URIs only, no secrets. Paged, filterable by client_id, search. Bearer token only.
GET /credentials/{id} Decrypted credential detail. Bearer token only, plus the biometric step-up headers X-Biometric-Challenge-Token and X-Biometric-Signature (see Biometric step-up).

Quotes#

Method Path Description
GET /quotes List quotes — paged, filterable by client_id, search.
GET /quotes/{id} Quote detail with line items.

Invoices#

Method Path Description
GET /invoices List invoices — paged, filterable by client_id, status.
GET /invoices/{id} Invoice detail with line items.

Expenses#

Method Path Description
GET /expenses List expenses — paged.
POST /expenses Create an expense (multipart). Requires description, amount; optional date, currency, reference, payment_method, client_id, and a receipt file upload.

Worksheets#

Structured checklists/forms attached to tickets, built from admin-defined templates — created on a ticket, filled in, and optionally signed off.

Method Path Description
GET /tickets/{id}/worksheets List worksheets attached to a ticket.
POST /tickets/{id}/worksheets Create a worksheet on a ticket from a template. Requires template_id; optional is_outtake flag.
GET /worksheets/{id} Worksheet detail with fields and current responses.
DELETE /worksheets/{id} Delete a worksheet.
POST /worksheets/{id}/sign Sign a worksheet.
POST /worksheets/{id}/complete Mark a worksheet complete or incomplete without signing.
POST /worksheets/{id}/responses Save worksheet field responses (marks the worksheet complete).
GET /worksheet-templates List worksheet templates. Bare array.

Outtakes#

Device pickup/drop-off ("outtake") forms — a specialized worksheet-like form for logging equipment handed to or received from a client, with signature capture.

Method Path Description
GET /tickets/{id}/outtakes List device-outtake forms for a ticket.
POST /tickets/{id}/outtake Create a device-outtake form on a ticket.
GET /outtakes/{id} Outtake form detail.
DELETE /outtakes/{id} Delete an outtake form.
POST /outtakes/{id}/sign Sign an outtake form.

Products#

Method Path Description
GET /products List products/services for charge selection. Filterable by type, search. Bare array.
Method Path Description
GET /search Global search across tickets, clients, and assets. Requires q (min length 2); returns results grouped by resource type.

Reports#

Operational and financial reporting. Most accept a year query parameter (default current year); a few take their own filters as noted. All return a report-shaped JSON object whose exact fields are report-specific — see the OpenAPI spec for each one's schema.

Method Path Description
GET /reports/time Time logged, grouped by client. period (week/month/all), mine.
GET /reports/tickets Ticket volume by month for a year.
GET /reports/tickets-by-client Ticket counts by client. Optional month.
GET /reports/time-by-tech Time logged, grouped by technician.
GET /reports/tech-performance Technician performance summary.
GET /reports/technician-performance Detailed technician performance report.
GET /reports/service-desk Service-desk report. from, to (YYYY-MM-DD), maintenance (include default, exclude, only: tickets made from RMM alerts). SLA figures only count tickets that count toward SLA.
GET /reports/csat Customer satisfaction report — ratings distribution and trend, per-technician/per-client breakdowns, raw feedback feed.
GET /reports/mrr Monthly recurring revenue report.
GET /reports/rmm-health RMM fleet health report.
GET /reports/unbilled-tickets Clients with unbilled billable closed tickets.
GET /reports/clients-with-balance Clients carrying an outstanding balance.
GET /reports/income-summary Income summary for a year.
GET /reports/expense-summary Expense summary for a year.
GET /reports/profit-loss Monthly profit and loss for a year.
GET /reports/expiring Domains or certificates expiring within N days. type (domains/certificates), days (default 30).
GET /reports/overview Open-ticket breakdown by priority/status/category, plus average resolution time.

Knowledge Base#

Method Path Description
GET /kb/categories List KB categories. Bare array.
GET /kb/articles List KB articles — paged, filterable by category_id, client_id, search.
GET /kb/articles/{id} KB article detail (content + attachments).

Profile#

The calling user's own profile — also doubles as the endpoint for registering a mobile push token or a biometric public key. Both deny legacy X-Api-Key auth.

Method Path Description
GET /me Current user profile. Bearer token only.
PUT /me Update profile/password, or register an fcm_token (push) or device_public_key_pem (biometric key).
POST /me Alias of PUT for profile/password updates. (Push token and biometric key registration require PUT.)

Appointments#

Scheduled/onsite entries against a ticket.

Method Path Description
GET /appointments List ticket appointments. when (past/today/future), mine, client_id. Bare array.
POST /appointments Create a ticket appointment. Requires ticket_id, schedule_start.

Endpoint agent (optional RMM module, off by default)#

Only when the RMM module is switched on (Administration > Settings > Endpoint agent; see docs/RMM_MODULE.md). While it is off the device endpoints answer 503 {"code":"module_disabled"} with Retry-After: 3600, and endpoint_devices answers 404 {"code":"disabled"} after authentication.

Method Path Notes
POST /agent_enroll, /agent_installer Device-facing, enrollment-token gated, no Bearer.
POST /agent_checkin Device-facing (per-device credential).
GET, POST /agent_jobs Device-facing: signed job offer (long poll) and job report.
GET /agent_update Device-facing: hosted agent update download.
GET, POST /agent_transfer Device-facing (RivetCore rc.11, file transfer switch): raw chunks of at most 1 MiB with the one-time X-Transfer-Token header.
POST /agent_logs Device-facing (RivetCore rc.11, log collection switch): batches of at most 200 events and 256 KiB.
GET, PUT /endpoint_devices/remote/mesh RivetCore rc.12, rmm.admin: the optional MeshCentral agent install settings (group id, certificate pin, overwrite switch, tables); probe_pin proposes a pin and saves nothing. The device detail gains mesh_agent once the device has reported one. See Core's docs/rmm/openapi-device.yaml.
POST /endpoint_devices/{id}/mesh/install, /endpoint_devices/{id}/mesh/uninstall, /endpoint_devices/mesh/install RivetCore rc.16, rmm.remote.manage and the remote-tools switch: push the MeshCentral agent to an enrolled device (the caller sends only force; address, device group and pin come from the saved Mesh settings), remove it (confirm), or install it on a target (device, tag, group, client, site, policy, all; confirm; capped by bulk_run_max, refused above approval_bulk_threshold). 409 unsupported for an agent older than rc.16. The device detail gains mesh_install while the install is available. agent_installer and the administrator's download take format = exe (default) or msi. See Core's docs/rmm/openapi-device.yaml.
GET, POST /endpoint_devices/starter/catalog, /starter/plan, /starter/install, /starter/uninstall RivetCore rc.13, rmm.admin: the starter pack (73 scripts, 3 check sets, 3 policy drafts). plan writes nothing; an empty selection means the whole pack.
GET /endpoint_devices, /endpoint_devices/{id}, /endpoint_devices/{id}/jobs User token only (the legacy X-Api-Key is refused). Role module_rmm; devices outside the caller's clients are a 404.
POST /endpoint_devices/{id}/jobs, /endpoint_devices/{id}/jobs/{job_id}/cancel, /endpoint_devices/{id}/remote Needs module_rmm_scripts / module_rmm_remote_connect; a reboot needs "confirm": true.

The wire protocol of the device endpoints is frozen and documented in rivet-core (docs/rmm/PROTOCOL.md).

Notifications#

Method Path Description
GET /notifications List undismissed notifications — paged.
POST /notifications/{id}/read Mark a single notification read/dismissed.
POST /notifications/read-all Mark all notifications read/dismissed.
GET /notifications/stream Server-Sent Events stream of new notifications (text/event-stream).

Alerts#

Combined view of RMM and backup alerts, with a shared acknowledge/resolve action.

Method Path Description
GET /alerts List combined RMM and backup alerts. Filterable by status, severity, source (all/rmm/backup), client_id.
POST /alerts Acknowledge or resolve an alert. Requires source (rmm/backup), id, action (acknowledge/resolve).

Diagnostics#

Method Path Description
POST /crash-reports Report a mobile app crash (logged to App Logs under category mobile_crash). Requires stack_trace. Public — a bearer token is honored for correlation when present but never required, since the crash worth capturing is often the one that happens before/around a failed login. Its own tighter rate limit applies: 20 requests / 5 minutes per IP.

Public#

Method Path Description
GET /csat Aggregate CSAT rating summary for public embedding (e.g. a website trust badge). Fully public — no credential accepted or required. Returns only the aggregate rating, distribution, and anonymized 4-5 star comment snippets — never client/contact names or ticket subjects. Response is cached 5 minutes (Cache-Control: public, max-age=300).

Meta#

Method Path Description
GET /validate_api_key Validate the presented bearer token or API key (legacy compatibility probe).
GET /openapi This OpenAPI 3.0 spec, as YAML. Public.
GET /docs The human-readable HTML API reference, self-contained. Public.

Notes for common integration scenarios#

  • Mobile app / anything acting as a specific technician: use bearer tokens from POST /auth. Register a push token and (optionally) a biometric public key via PUT /me once logged in, so you can support push notifications and the biometric step-up flow for credential secrets.
  • RMM scripts / server-to-server jobs with no specific user: use a legacy X-Api-Key. Scope it to a single client if the integration only ever needs one client's data, and set its Permission to read unless the integration genuinely needs to create/update records — a leaked read-only key is a much smaller incident.
  • Public-facing widgets (e.g. a "customer satisfaction" badge on a marketing site): GET /csat needs no credential at all and is safe to call directly from client-side JavaScript.
  • Polling vs. streaming: ticket chat and notifications both support either a plain polling GET (with since_id on chat for incremental fetches) or an SSE stream (?stream=1 on chat, /notifications/stream for notifications) — pick streaming for a live UI, polling for anything simpler or running somewhere SSE is awkward (e.g. some serverless environments).

Public company branding#

GET /api/v1/branding returns { "name": "Example MSP", "logo_path": "/uploads/settings/example.png" } without authentication. These are the same public identity fields shown on the login screen. logo_path is null when no company logo is configured. Uploaded company artwork takes precedence over RivetMSP artwork; resolve the path against the selected server origin. Clients should cache branding per server for offline use and refresh it on resume. No secrets or broader company settings are exposed. The endpoint accepts GET only and is rate limited to 60 requests per minute per IP.

This page is rendered from docs/API.md in the RivetMSP repository. View or edit on GitHub