Skip to content

Docs / RivetIT / Reference

RivetIT REST API

The /api/v1 reference: authentication, resources and examples. Also used by the mobile app and RMM scripts.

This document describes the REST API served by RivetIT — the same companion API used by the mobile app, RMM scripts and other integrations. It's a plain JSON-over-HTTP API: no SDK is required, just an HTTP client and one of the two auth methods below.

  • Base path: /api/v1 (relative to your RivetIT install host, e.g. https://your-instance.example.com/api/v1)
  • Format: JSON request and response bodies, except where a specific endpoint documents multipart form uploads or Server-Sent Events (SSE).
  • Versioning: the API is versioned as a whole (v1 in the path). There is currently one version; breaking changes would ship as /api/v2.
  • Machine-readable spec: the full OpenAPI 3.0 document is served live at GET /api/v1/openapi.yaml and mirrors exactly what the running instance supports — import it into Swagger UI, Postman, or Insomnia to explore and try requests.
  • Human-readable in-app reference: GET /api/v1/docs uses a locally hosted Redoc viewer for the same spec (also embedded in Admin > API Docs). Use its navigation and search to browse endpoint parameters and schemas.

This document is a narrative companion to those two — it explains what each resource is for and how the pieces fit together. For the full request/response JSON Schema of any individual endpoint, use the OpenAPI spec or /docs rather than treating the tables below as exhaustive schemas.

A note on "clients" vs. "departments"#

RivetIT is built for internal IT departments running one organization with many internal departments. It started from ITFlow, whose data model was made for an MSP billing external clients, and the admin UI was renamed throughout — "Client" / "Clients" became "Department" / "Departments" everywhere a person sees it.

The API was deliberately excluded from that rename, to keep it a stable, documented contract for existing integrations. Every endpoint path, query parameter, and JSON field still says client / client_id — that is not a bug or leftover, it's intentional API stability.

This document uses "department" in prose, since that's what a department maps to conceptually for this edition's users — but every code block, path, and field name below is shown verbatim as the API actually expects it (/clients/{id}, client_id, etc.), so you can copy it directly into a request.

Billing modules are off by default#

Ticket charges are an optional billing feature, off by default in this edition and enabled at Settings > Modules. Quotes, invoices, expenses, products, and their financial report endpoints are no longer exposed through the RivetIT API. Their REST paths return 404, and their legacy PHP files have been removed.


Authentication#

Every endpoint other than a short public list (below) requires one of two kinds of credential, sent on every request. They are different things and are not interchangeable:

Credential Header Identifies Use it for
API key access token (primary for machines) Authorization: Bearer <access token> from POST /oauth/token A machine client (Client ID + secret), with scopes and department limits Scripts, RMM tooling, the QMS, any server-to-server integration
User session token Authorization: Bearer <token> from POST /auth A person signed in (the mobile app) The Android/iOS app and anything acting as one technician

There is one machine credential: an API key (a Client ID + secret; internally still called an integration client). The old X-Api-Key header is no longer accepted: BREAKING for anything that still sends it, which now gets 401 with a message pointing at POST /oauth/token. Keys of earlier versions were converted into API keys at the 2.6.204 update (same scopes, departments, IP list and expiry) but have no secret: an administrator opens the key on Administration > API Keys, presses Create secret, and the integration switches to the token endpoint.

User session tokens (api_tokens) are unrelated to this and are unchanged: they identify a signed-in person on a device, are issued by POST /auth, carry that person's role and permissions, and are what the mobile app uses. Nothing in the unification touches them.

This is the primary method for anything acting as a specific person — the mobile app, a browser-based integration, or any tool where "who did this" matters. Obtain a token by posting credentials to POST /auth:

curl -s -X POST https://your-instance.example.com/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "[email protected]", "password": "hunter2", "device_name": "iPhone 15"}'

The response is one of:

  • {"token": "...", "user": {...}} — login succeeded, use this token as Authorization: Bearer <token> on subsequent requests.
  • {"requires_2fa": true} — the account has TOTP enabled; resubmit the same request with a totp_code field.
  • 401 — bad credentials.

Passkeys/WebAuthn are also supported as a login method: GET /auth (no body, unauthenticated) returns a WebAuthn assertion challenge; complete it client-side and post the resulting passkey_response plus the challenge_token you were given back to POST /auth.

To log out and revoke the current token, call DELETE /auth.

A user bearer token is also required (not just accepted) for a small number of endpoints that API keys are explicitly denied on — see below.

The old X-Api-Key header (removed)#

X-Api-Key: <key> (and ?api_key= / an api_key field in the body) no longer authenticates anything. The response is 401 {"error": "The X-Api-Key header is no longer accepted. Authenticate with an API key (Client ID + secret): POST /api/v1/oauth/token ..."} with WWW-Authenticate: Bearer; the key itself is never read or logged (an audit line records the address that still sends it).

To migrate an integration: on Administration > API Keys open the converted key (it reads "No secret yet"), press Create secret (the secret is shown once, with a Copy button), and change the integration:

TOKEN=$(curl -s -X POST https://your-instance.example.com/api/v1/oauth/token \
  -d grant_type=client_credentials -d client_id=ic_0123456789abcdef0123 --data-urlencode client_secret="$SECRET" | jq -r .access_token)
curl -s https://your-instance.example.com/api/v1/tickets -H "Authorization: Bearer $TOKEN"

Machine clients act as a fixed, disabled, role-less service identity ("API integration service"), never as an administrator; their only authority is their scopes and departments (see Acting identity). Routes that act for a person answer 403 for them: /credentials, /me, /notifications, /approvals, /endpoint_devices, /service_catalog, /workflow_tasks, /hr_requests.

API keys (machine credentials for the whole API)#

Another system (the QMS) authenticates with an integration client, created in Administration > API Keys (client id ic_..., a secret shown once, scopes ticked per client, optional IP allow-list and expiry). It exchanges the client id and secret for a 10 minute access token:

curl -s -X POST https://rivetit.example.com/api/v1/oauth/token \
  -d grant_type=client_credentials -d client_id=ic_0123456789abcdef0123 --data-urlencode client_secret="$SECRET" \
  -d "scope=lms:read lms:completions:read"          # scope is optional; omitted = every scope the client holds
# {"access_token":"eyJ...","token_type":"Bearer","expires_in":600,"scope":"lms:read lms:completions:read"}
curl -s https://rivetit.example.com/api/v1/lms/courses -H "Authorization: Bearer $ACCESS_TOKEN"

Rules that matter to an integrator:

  • Department scope. On the general API the scope applies exactly as it did to the old API keys (all / one / several departments; a restricted client with none reaches nothing; list endpoints, by-id reads, search, KB, relationships and reports are filtered). Resources that hold no department data (for example ticket categories, company-wide KB articles) are reachable by any client holding their scope. A client is limited to the departments chosen when it is created (a department is a RivetIT client/department; a person belongs to the department on their record), or holds the explicit choice All departments. A client restricted to no department sees nothing. Records outside the scope are indistinguishable from records that do not exist: a by-id read is 404, lists are filtered, and a create for an employee or course outside it answers 422 employee_not_found / course_not_found. A course is in scope when it has a live requirement rule for an allowed department (or for everyone), a rule naming a person of an allowed department, or an assignment or completion of such a person; the departments and requirements of a course list only what touches the allowed departments.
  • A token reaches a route only if it holds that route's scope (deny by default, no wildcard, no implication between scopes); a route with no scope answers 403. It never acts as a user. A user token is not accepted on /lms, /employees or /departments (401).
  • Scopes: lms:read, lms:assign, lms:completions:read, lms:evidence:read, directory:read, quality:events (inbound QMS events only), and, for the general API, api:<resource>:read, api:<resource>:write, api:<resource>:delete per resource: alerts, appointments, assets, clients, contacts, contracts, dashboard, kb, milestones, outtakes, projects, relationships, reports, search, tasks, ticket_attachments, ticket_categories, ticket_views, tickets (also /statuses) and worksheets (also tickets/charges). Method decides the action: GET/HEAD need read; POST, PUT, PATCH need write; DELETE needs delete. write does not include read, delete does not include write. directory:read is the only scope that opens /employees and /departments, and it opens nothing else. A route needs its scope in the token; removing a scope from the client takes effect at the next request, and so does revoking the client or the secret that issued the token. A token for a client holding many scopes is large (about 2 KB); ask for fewer with the scope parameter if a proxy limits header size.
  • The service catalog (/service_catalog: categories, items with their request forms, raising a request) is described in openapi.yaml and docs/MOBILE_API.md; POST calls ServiceCatalogService::createRequest(), the same entry point a chat integration uses.
  • Person-bound routes are never available to a client, whatever it holds: /credentials, /me, /notifications, /approvals, /endpoint_devices, /service_catalog, /workflow_tasks, /hr_requests. A client may also hold the sso capability (OpenID Connect sign-in to the QMS, docs/integrations/qms-sso.md); it is not an API scope, is never issued in a token here, and an SSO token or ID token is refused on every /api/v1 route.
  • A client holds at most two active secrets, so rotate by adding the new secret (the old one keeps working for the overlap you choose) and switching over.
  • Token endpoint failures are one uniform 401 invalid_client and are throttled (429, Retry-After).
  • Errors on these routes are {"error":{"code","message","correlation_id"}}; send X-Correlation-Id (echoed) to trace a call.
  • Lists take limit (default 50, max 200), cursor (the opaque next_cursor) and updated_since (RFC 3339).
  • POST needs an Idempotency-Key header (8 to 128 characters). Same key and same body replays the original response (Idempotent-Replay: true); same key and a different body is 422 idempotency_key_reuse. Records are kept 24 hours; only successful results are stored, so a corrected retry with the same key is processed normally.

See integrations/qms-lms-sync.md for the assignment and completion flow and integrations/qms-directory-sync.md for the directory feed.

Acting identity of a machine client

The old keys ran as "the first active administrator", so every key carried a whole administrator's authority. API keys do not. On the general API a client acts as one fixed service identity ("API integration service"): a disabled, role-less user that cannot sign in, owns no user token, and is not an administrator. It is the user recorded in created_by-style columns and the audit trail for machine writes (the log text names the client, and the legacy-header audit lines carry the client id). Because it holds no role, every role/permission check inside an endpoint is decided by the client's scopes instead (api:<resource>:read|write|delete) and its department scope; there is no path from a client to more than it was granted. An administrator can see the identity under Administration > Users (disabled); do not enable it or give it a role.

Public endpoints (no credentials required)#

A short list of endpoints is intentionally reachable without any auth header:

  • POST /auth, GET /auth — you need these to get a token.
  • POST /oauth/token — the client-credentials token endpoint for integration clients (above).
  • POST /crash-reports — mobile crash reporting; must work even when login is failing or a token has expired. A token is honored for correlation when present but never required.
  • GET /csat — an aggregate, anonymized satisfaction-rating summary meant for embedding on a public page.
  • GET /openapi, GET /docs — the spec and human-readable reference themselves.

Everything else requires an API key's access token or a user bearer token.


Inbound chat endpoints (Slack and Teams)#

These are not part of /api/v1/ (no bearer token, no OpenAPI entry): they are called by Slack and by the Microsoft Bot Framework Service and authenticate every request themselves. All are off until switched on in Administration > Chat. Setup: docs/SLACK_TEAMS_SETUP.md.

Path Caller Authentication Purpose
POST /slack_interactive.php Slack X-Slack-Signature v0 HMAC, 5 min window, single use Buttons, selects, modals, shortcuts
POST /slack_events.php Slack same Events API: thread replies, DMs, mentions
POST /slack_commands.php Slack same /ticket slash command (ephemeral answer)
POST /teams_bot.php Bot Framework Authorization: Bearer JWT (RS256, issuer, audience, serviceurl) Teams bot activities

All answer 401 {} for anything unauthenticated, 405 for non-POST and 413 for oversized bodies. Services other code can call: ITFlow\Chat\ChatActions (ticket and approval actions as a chat user) and ITFlow\Chat\ChatNotifier (sendToUser, approvalRequested, ticket threads).

Conventions#

These shapes are consistent across the whole API; per-endpoint deviations (if any) are called out in the OpenAPI spec.

Paged lists return a JSON object:

{ "data": [ /* items */ ], "total": 137 }

Some paged endpoints additionally echo page and limit. Pagination is via ?page= (default 1) and ?limit= (default 20) query parameters where supported.

Bare-array lists. A number of list endpoints intentionally return a raw JSON array instead of the {data, total} envelope — typically small, unpaged reference/lookup lists (ticket statuses, ticket categories, saved views, worksheet templates, asset types) or one-off sub-resource lists (a client's tickets/assets/locations/credentials/contracts/files, a ticket's worksheets/outtakes). Each endpoint's description in the OpenAPI spec notes "(bare array)" where this applies — check there when in doubt.

Creates return the new record's id:

{ "id": 4521 }

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

Simple mutations (status change, sign, mark read, acknowledge, etc.) return:

{ "ok": true }

Errors are a JSON object with a single error string, alongside the matching HTTP status code:

{ "error": "Ticket not found" }

Common status codes: 400 bad request/validation, 401 missing or invalid credentials, 403 authenticated but not permitted (wrong scope, read-only key, wrong department), 404 not found, 429 rate limited.

Rate limiting. Each caller (per user token, or per API key, by its access tokens) is limited to 300 requests per 60 seconds. Exceeding it returns 429 with a Retry-After header telling you how many seconds to wait before retrying.

Search parameter. Where an endpoint accepts a search query parameter, it's a general substring filter over that resource's obvious fields (name, subject, etc.) — exact fields are resource-specific.


Endpoint reference#

Full request/response schemas for every endpoint below live in the OpenAPI spec (GET /api/v1/openapi.yaml) and the in-app reference (GET /api/v1/docs). The tables here give you the shape of each resource and a one-line description of every operation so you can find what you need quickly.

Auth#

Password and passkey login, and logout. See Authentication above for the full flow.

Method Path Description
POST /auth Password login (or passkey completion) — returns a bearer token, or requires_2fa
GET /auth Begin a WebAuthn/passkey assertion — returns a challenge
DELETE /auth Logout — revoke the current bearer token

Profile#

The signed-in user's own profile. GET /me and the profile-update operations require a bearer token — an API key is denied here, since there's no specific user for it to represent.

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

Dashboard#

A single rollup endpoint for the agent home screen / dashboard: open-ticket counters and a personal queue.

Method Path Description
GET /dashboard Agent dashboard counters (open/mine/overdue/due-today/onsite) plus the caller's ticket queue

Clients#

Departments — their profile, and the sub-resources scoped to one department: tickets, assets, locations, credentials (names only), contracts, files, and included-hours allowance. Remember: the path and field names stay client / client_id per the terminology note above.

Method Path Description
GET /clients List departments (paged, searchable)
GET /clients/{id} Department detail — profile, contacts, primary location
GET /clients/{id}/tickets Recent tickets for a department (bare array)
GET /clients/{id}/assets Assets for a department (bare array)
GET /clients/{id}/locations Locations for a department (bare array)
GET /clients/{id}/credentials Credential names/URIs for a department — no secrets (bare array)
GET /clients/{id}/contracts Contracts for a department (bare array)
GET /clients/{id}/files Signed outtake/pickup forms for a department (bare array)
GET /clients/{id}/allowance New. Included support-hours allowance vs. usage for a calendar month, rolled up across the department's active contracts plus a per-contract breakdown. Accepts optional month (1-12) and year query params, defaulting to the current month. Remote and onsite hours are tracked separately; a department with no allowance configured on any active contract gets included: null for that delivery method rather than a zero.

Contacts#

People at a department (as opposed to the department/organization record itself).

Method Path Description
GET /contacts List contacts (paged, searchable, filterable by client_id)

Tickets#

The core help-desk resource: listing/creating/reading tickets, replying (public reply, internal note, or portal/website), logging time, changing status, uploading attachments, an in-ticket live chat (including an SSE stream), and billable charges on a ticket (billing module only).

Method Path Description
GET /tickets List tickets — paged; filterable by status, mine, assigned, priority, board, onsite, category_id, client_id, contact_id, overdue, due_today, plus search; priority, assigned (me, unassigned, agent ids), board, category_id and onsite take a comma list (priority=high,medium): OR inside one filter, AND across filters
POST /tickets Create a ticket (JSON, or multipart to attach files at creation)
GET /tickets/{id} Ticket detail, including replies and attachments
POST /tickets/{id}/reply Add a reply, internal note, or portal/client reply (JSON or multipart with files)
DELETE /tickets/{id}/reply/{replyId} Delete a reply and its attachments
POST /tickets/{id}/time Log time against a ticket (recorded as an internal reply)
POST /tickets/{id}/status Change ticket status (moving to a Closed-type status resolves it)
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
POST /tickets/{id}/chat Send a live-chat message (optionally on behalf of a contact via contact_id)
GET /tickets/{id}/charges List billable charges on a ticket, with a running total (billing module)
POST /tickets/{id}/charges Add a charge to a ticket (billing module)

Ticket Meta#

Small reference/lookup lists used to populate ticket filters and forms — all bare arrays, all effectively static per instance.

Method Path Description
GET /statuses Active ticket statuses (bare array)
GET /ticket-categories Ticket categories (bare array)
GET /ticket-views Saved ticket views, pre-translated into list query params (bare array). Each item has id, name, icon, params (all strings; a view with several priorities, agents, boards or categories gives a comma list: priority high,medium, assigned me,unassigned,7, board 3,4, category_id 5,6; a view assigned to only the caller keeps the older mine = 1), shared (shared with all agents), is_default and default_scope (personal, shared or null): the view that opens by default for the caller

Worksheets#

Structured, fillable forms attached to a ticket (built from a template), with a signature step. Creating one and listing templates live under /tickets/{id}; everything else addresses the worksheet directly by its own id.

Method Path Description
GET /tickets/{id}/worksheets List worksheets attached to a ticket (bare array)
POST /tickets/{id}/worksheets Create a worksheet on a ticket from a template
GET /worksheets/{id} Worksheet detail — 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 available to build a worksheet from (bare array)

Outtakes#

Device pickup/outtake forms — the paper trail for handing a device to or from a department, with a signature step. Same shape as Worksheets: create/list under the ticket, everything else by the outtake's own id.

Method Path Description
GET /tickets/{id}/outtakes List device-outtake (pickup) forms for a ticket (bare array)
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

Appointments#

Scheduled entries against a ticket (site visits, scheduled calls, etc.).

Method Path Description
GET /appointments List appointments — filterable by when (past/today/future), mine, client_id (bare array)
POST /appointments Create an appointment (ticket schedule entry)

Project tasks#

Tasks of a project (and checklist items of a project's tickets). Scopes api:tasks:read / write / delete; roles need Service Desk level 1 / 2 / 3. GET /projects/{id} lists a project's tasks.

Method Path Description
GET /tasks/{id} One task
POST /tasks Create a project task (project_id and name required)
PATCH / PUT /tasks/{id} Change the fields you send; the rest stay as they are
DELETE /tasks/{id} Delete a task (and its label links); {"deleted": true, "id": n}
POST /tasks/{id}/toggle Toggle completed

A task has id, name, status (To Do, In Progress, Blocked, Done), progress (0-100), start_at, due_at (YYYY-MM-DD), milestone_id, completed_at, assigned_to (name), ticket_number, and, from database 2.6.207 (additive, existing clients are unaffected): priority (0 none, 1 low, 2 medium, 3 high, 4 urgent), priority_name, description (plain text, no HTML), color (#rrggbb or null) and labels ([{id, name, color}]). Before Update Database has run these read as 0, "None", null, null, [] and writes to them are ignored.

Writable on POST / PATCH: name, status, progress, start_at, due_at (null clears), milestone_id (must belong to the task's project), assigned_user_id (an active user, 0 clears), estimate_minutes, priority, description, color, labels (names, or {name, color}; unknown names are created in the task's project; replaces the set, [] clears) and label_ids (existing labels that are global or belong to the task's project; anything else is ignored). Invalid values answer 400. Department scope applies as for projects: a task of a department outside the client's scope is 403.

Checklists, subtasks, comments, assignees, files, reminders and repeats (databases 2.6.208 and 2.6.209; before Update Database the new task fields read as neutral values and the sub-resources answer 409). A task also has parent_id (the parent when it is a subtask), assignees ([{id, name, primary}], the primary first; assigned_to stays the primary's name), checklist and subtasks ({done, total}), comment_count, attachment_count, reminder_at, reminder_sent_at and repeat ({interval, unit} or null). Writable on POST / PATCH: parent_id (same project, one level deep, no cycles; null detaches), assignee_ids (active users; assigned_user_id alone still works and keeps the rest of the team), reminder_at (YYYY-MM-DD HH:MM, null clears) and repeat ({"interval": 1-999, "unit": "day|week|month|year"} or null). Completing a repeating project task (/toggle, status Done, the web app) creates the next occurrence once, with the due date moved on.

Method Path Description
GET / POST /tasks/{id}/checklist List / add an item ({"text": "..."})
PATCH / DELETE /tasks/{id}/checklist/{item} Change text / done; delete
GET / POST /tasks/{id}/subtasks List / create a subtask ({"name": "..."})
GET / POST /tasks/{id}/comments List / add a comment ({"body": "..."}, plain text)
PATCH / DELETE /tasks/{id}/comments/{comment} Edit (author only) / delete (author, or an administrator)
GET / POST /tasks/{id}/attachments List metadata / upload (multipart/form-data, field file)
GET / DELETE /tasks/{id}/attachments/{file} Download (always an attachment) / delete (uploader, level 3 or administrator)

The sub-resources use the task's scopes and department scope: api:tasks:read to read, write to add and change, delete to delete. Files: up to 25 MB, 50 per task; scripts, web pages (html, svg), installers and similar are refused with 400.

Assets#

Managed devices/equipment tracked per department.

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

Credentials#

Stored logins/secrets for a department. Listing only ever exposes names and URIs — the decrypted secret is a separate, deliberately harder call.

Method Path Description
GET /credentials List credentials — names/URIs only, no secrets; paged, filterable by client_id. Requires a user token — an API key is denied.
GET /credentials/{id} Decrypted credential detail. Requires a user token (API keys denied) and a signed biometric step-up challenge — see below.

Biometric step-up for /credentials/{id}. Beyond normal auth, this call requires two additional headers proving a fresh biometric/passkey unlock on the device:

  • X-Biometric-Challenge-Token — the challengeToken returned by GET /auth
  • X-Biometric-Signature — a base64 signature of the challenge bytes, produced by the device's registered biometric key

This is the one read endpoint in the API with an extra proof-of-presence step, because it's the one endpoint that returns plaintext secrets.

Knowledge Base#

Internal documentation, organized into categories.

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

One endpoint, fanning out across several resource types.

Method Path Description
GET /search Global search across tickets, departments, and assets. Requires q (min length 2).

Reports#

Operational reporting. Most accept a year query parameter, some also month; each returns a report-specific JSON object — see the OpenAPI spec or /docs for each report's exact shape.

Method Path Description
GET /reports/time Time logged, grouped by department (period=week|month|all, mine)
GET /reports/tickets Ticket volume by month for a year
GET /reports/tickets-by-client Ticket counts by department
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
GET /reports/csat CSAT report — rating distribution/trend, per-technician and per-department breakdowns, raw feedback
GET /reports/rmm-health RMM fleet health report
GET /reports/unbilled-tickets Departments with unbilled, billable closed tickets (billing module)
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

Alerts#

Combined feed of RMM and backup alerts, with an acknowledge/resolve action.

Method Path Description
GET /alerts List alerts — filterable by status (default new), severity, source (rmm/backup/all), client_id
POST /alerts Acknowledge or resolve an alert

Notifications#

In-app notifications, including an SSE stream for live delivery.

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

Automation (event rules)#

Administrators only, with a user API token (an integration client gets 403). The same rules, validation and run log as Administration > Event rules; details and the per-action action_config fields in AUTOMATION.md. The webhook signing secret is never returned.

Method Path Description
GET /automation_rules List rules (q, trigger_event, action_type, enabled=0|1, limit up to 200, offset)
POST /automation_rules Create a rule: {name, trigger_event, conditions?, action_type, action_config, is_enabled?, priority?, stop_on_match?, rate_limit_per_min?} (422 with the reason when invalid)
GET /automation_rules/{id} One rule, with its last run and run counts
PUT /automation_rules/{id} Replace a rule (name, trigger_event, action_type, action_config required)
PATCH /automation_rules/{id} Change some fields; omitted fields (including action_config) are kept
DELETE /automation_rules/{id} Delete a rule (its run log rows stay)
GET /automation_rules/runs The run log (rule_id, status, event, failed=1, limit, offset); each run has attempt (of max_attempts), source (event/retry/manual), retry_of_run_id, retried_by_run_id, can_rerun
GET /automation_rules/runs/{run_id} One run
POST /automation_rules/retry/{run_id} Run a failed run again with the event it kept (409 with the reason when it cannot)
GET /automation_rules/meta Events, actions (with risky / needs_ticket_event), condition operators, enrichment fields and the state of the risky-action switches

Integration (LMS)#

Integration-client token only (see API keys); not available to user tokens. Every endpoint below is filtered by the client's department scope; outside it, an id answers 404 exactly like an unknown id.

Method Path Scope Description
POST /oauth/token none Client-credentials grant; form-encoded grant_type, client_id, client_secret, optional scope. Returns a 10 minute access token.
GET /lms/courses lms:read Published, non-archived courses (latest published revision): id, kind, code, external_code, title, description, status, revision, departments, est_minutes, validity_months, category, requirements, updated_at.
GET /lms/courses/{id} lms:read One course. Unpublished, archived and unknown are all 404.
POST /lms/assignments lms:assign Body employee (odoo_employee_id and/or rivetit_id), course_id, due_on, optional source, external_system + external_ref. Needs Idempotency-Key. 201 new, 200 an open assignment (or the same external reference) already existed. Created through the assignment engine (ledger stays valid).
GET /lms/assignments lms:read Filters employee, odoo_employee_id, course, status, external_system, external_ref, updated_since.
GET /lms/assignments/{id} lms:read One assignment (asg_<n>).
GET /lms/completions lms:completions:read Filters employee, odoo_employee_id, course, assignment, status (completed, voided, superseded), updated_since. Records are never deleted.
GET /lms/completions/{id} lms:completions:read One completion (cmp_<n>): course and revision, assignment, completed_on, result, score_pct, expires_on (recertification date), evidence_ref (certificate number, file available), status, updated_at, revision.
GET /lms/completions/{id}/evidence lms:evidence:read The completion's evidence file (PDF/JPEG/PNG) as an attachment; 404 when none or not servable.

Integration (directory)#

Integration-client token with scope directory:read only; not available to user tokens or API keys, and no lms:* scope grants it. Filtered by the client's department scope like the LMS routes: an id outside it answers 404 exactly like an unknown id, and a list simply omits it. GET only. Same limit, cursor, updated_since, error format and 600 requests/minute limit as the LMS routes.

Method Path Scope Description
GET /employees directory:read Employees (contacts, vendors excluded), ascending id. Terminated and archived people stay in the feed with active: false. Fields: id, odoo_employee_id, name, work_email, job_title, department_id, odoo_department_id, manager_id, employment_status, active, updated_at. Filters department_id, odoo_employee_id, updated_since.
GET /employees/{id} directory:read One employee.
GET /departments directory:read Departments (clients; CRM leads excluded), ascending id. Archived and inactive departments stay with active: false. Fields: id, odoo_department_id, name, parent_id, head_employee_id, status, active, updated_at.
GET /departments/{id} directory:read One department.

Integration (Quality events)#

Integration-client token with scope quality:events only. Not available to user tokens or API keys without the scope; served only while the Quality module is on and Accept events from the QMS is on (otherwise 503 module_disabled). Full contract: QUALITY_CONTRACT.md.

Method Path Scope Description
POST /integrations/qms/events quality:events A signed event from the QMS. Body: JSON envelope {"id","type","schema_version":1,"occurred_at","data"} (at most 64 KiB). Header X-Rivet-Signature-V2: t=<unix>,v1=<hex hmac-sha256 of "<t>.<body>" with the inbound secret>; 5 minute window. Types qms.employee.mapped, qms.department.mapped, qms.sync.requested, qms.requirement.changed; unknown types are acknowledged as ignored. 200 {"status":"processed"|"ignored"|"duplicate"}; 401 invalid_signature; 403 insufficient_scope; 409 event_id_reuse; 413; 415; 422; 503 module_disabled. A repeated event id is acknowledged and not processed again.

Diagnostics#

Method Path Description
POST /crash-reports Report a mobile app crash (logged to App Logs under mobile_crash). Public — see Authentication.

Employee portal (mobile view of the department portal)#

Separate sign-in for department-portal logins (employees). The token comes from POST /portal_auth, is stored hashed in portal_api_tokens, and works only on the endpoints below; staff tokens do not work here and employee tokens do not work anywhere else. Every response is scoped to the token's own contact and department. All are read-only except marking the feed read. UNVERIFIED LIVE: covered by tests/employee_portal_i32.php on a scratch install only.

Method Path Description
POST /portal_auth {username, password, totp_code?, device_name?} returns {token, contact}, or {requires_2fa:true}. Local-password logins only; 5 failures lock for 5 minutes
DELETE /portal_auth Sign this device out
GET /portal_home Announcements, open requests, devices, approvals waiting, checklist, popular/recent help articles, unread count
GET /portal_devices, /portal_devices/{id} My devices (OS, warranty, last seen, restart pending); another person's device is 404
GET /portal_checklist My onboarding/offboarding checklist (null when none)
GET /portal_announcements Published announcements for all departments or mine
GET / POST /portal_notifications My feed; POST {"action":"mark_read"}

Public#

Method Path Description
GET /csat Aggregate CSAT rating summary for public embedding (e.g. a marketing-site trust badge) — average rating, breakdown, and anonymized 4-5 star testimonial snippets only, never department/contact/ticket identifiers. No auth. Cached 5 minutes.

Meta#

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

Not available yet (unreleased)#

api/v1/metrics_ingest.php (a device-metrics push endpoint, POST /api/v1/metrics-ingest) exists in the source tree but is unreleased: it has no route in index.php, no token table in the shipped schema and no administration screen, so the live API does not serve it and it is deliberately absent from the tables above and from the OpenAPI spec. See docs/FINDINGS-DECISIONS.md.


Example requests#

A handful of common flows, end to end. All examples assume https://your-instance.example.com as the host and a bearer token already obtained via /auth stored as $TOKEN.

Login#

curl -s -X POST https://your-instance.example.com/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
        "username": "[email protected]",
        "password": "hunter2",
        "device_name": "iPhone 15"
      }'
{ "token": "eyJ...", "user": { "id": 4, "name": "Alex Tech", "email": "[email protected]", "type": 3 } }

If the account has TOTP enabled, the first response is {"requires_2fa": true} — resend the same body with a totp_code field added.

List open tickets assigned to me#

curl -s "https://your-instance.example.com/api/v1/tickets?status=open&mine=1&limit=50" \
  -H "Authorization: Bearer $TOKEN"
{
  "data": [
    { "id": 512, "number": 1042, "subject": "VPN keeps dropping", "priority": "high", "status": "In Progress", "client": "Finance", "assigned_to": "Alex Tech", "created_at": "2026-08-30 14:02:11" }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

Note client here is the department name — the client_id filter and client field name are unchanged from upstream ITFlow, per the terminology note above.

Create a ticket#

curl -s -X POST https://your-instance.example.com/api/v1/tickets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "subject": "New laptop setup for onboarding",
        "details": "New hire starts Monday, needs a laptop imaged and ready.",
        "client_id": 7,
        "priority": "medium",
        "category_id": 3
      }'
{ "id": 891, "number": 1043, "attachments": [] }

To attach files at creation time, send the same fields as multipart/form-data instead of JSON, with one or more file parts alongside the form fields.

Reply to a ticket#

curl -s -X POST https://your-instance.example.com/api/v1/tickets/891/reply \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "reply": "Imaged and dropped off at the front desk, ready for Monday.",
        "type": "reply",
        "time_worked": "00:45:00"
      }'
{ "id": 2201, "type": "reply", "ticket_status": { "id": 2, "name": "Resolved" }, "attachments": [] }

type selects the reply kind: reply (visible to the department/portal), note (internal only), or client (posted as if from the portal/website). Include time_worked (HH:MM:SS) to log time in the same call, or use POST /tickets/{id}/time to log time without adding a visible reply.


See also#

  • Live OpenAPI spec: GET /api/v1/openapi.yaml
  • Interactive human-readable reference: GET /api/v1/docs (also linked from Admin > API Docs)
  • Machine credentials (former API keys included): Admin > API Keys (the former "Integration clients" page; /admin/integration_clients.php redirects there)
  • Module toggles (including billing): Settings > Modules
This page is rendered from docs/API.md in the RivetIT repository. View or edit on GitHub