openapi: 3.0.3 info: title: RivetIT API v1 version: 1.0.0 description: > 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 as `Authorization: Bearer `. A token reaches a route only if it holds that route's scope (`api::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": }` (some also add `page`/`limit`). * Some list endpoints return a bare JSON array (noted per-endpoint). * Creates return `{ "id": }` (sometimes with extra fields). * Simple mutations return `{ "ok": true }`. * Errors return `{ "error": "" }` with the matching HTTP status. servers: - url: /api/v1 description: Relative to the RivetIT install host tags: - name: Auth - name: Endpoint agent - name: RivetPanel - name: Mobile - name: Employee portal - name: Dashboard - name: Tickets - name: Ticket Meta - name: Clients - name: Contacts - name: Assets - name: Relationships - name: Projects - name: Contracts - name: Credentials - name: Worksheets - name: Outtakes - name: Search - name: Reports - name: Knowledge Base - name: Profile - name: Appointments - name: Notifications - name: Automation - name: Alerts - name: Diagnostics - name: Integration - name: Public - name: Meta security: - integrationClient: [] - bearerAuth: [] paths: /branding: get: tags: [Auth] summary: Public company identity for mobile sign-in and app branding description: Returns the same company name and uploaded logo shown on the public login page. An uploaded logo replaces product artwork. No credentials or settings are returned. security: [] responses: '200': description: Company identity; null logo_path means the server has no uploaded logo content: application/json: schema: type: object required: [name, logo_path] properties: name: type: string logo_path: type: string nullable: true '429': description: Rate limit exceeded /auth: post: tags: [Auth] summary: Password login — returns a bearer token, or requires_2fa security: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LoginRequest' responses: '200': description: Token issued, or 2FA required, or (for passkey completion) token issued content: application/json: schema: oneOf: - $ref: '#/components/schemas/LoginResponse' - type: object properties: requires_2fa: {type: boolean, example: true} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} '429': {$ref: '#/components/responses/RateLimited'} get: tags: [Auth] summary: Begin a WebAuthn/passkey assertion — returns a challenge security: [] responses: '200': description: Passkey assertion options content: application/json: schema: $ref: '#/components/schemas/PasskeyBeginResponse' '429': {$ref: '#/components/responses/RateLimited'} delete: tags: [Auth] summary: Logout — revoke the current bearer token responses: '200': {$ref: '#/components/responses/Ok'} /crash-reports: post: tags: [Diagnostics] summary: Report a mobile app crash (logged to App Logs, category "mobile_crash") description: > Semi-public: reachable without a valid bearer token, because the crash most worth seeing is exactly the one that happens before login succeeds or while a token is invalid/expired. A token is honored for caller correlation when present, but never required. security: [] requestBody: required: true content: application/json: schema: type: object required: [stack_trace] properties: platform: {type: string, example: android} app_version_name: {type: string, example: "1.13.0"} app_version_code: {type: integer, example: 19} device_model: {type: string, example: "Pixel 8"} os_version: {type: string, example: "15"} sdk_int: {type: integer, example: 35} thread_name: {type: string, example: main} is_fatal: {type: boolean, default: true} occurred_at: {type: string, format: date-time} stack_trace: {type: string} responses: '201': description: Logged content: application/json: schema: type: object properties: {logged: {type: boolean, example: true}} '400': {$ref: '#/components/responses/BadRequest'} '429': {$ref: '#/components/responses/RateLimited'} /csat: get: tags: [Public] summary: Aggregate CSAT rating summary for public embedding (e.g. a website trust badge) description: > Fully public: no bearer token accepted or required. Returns only the aggregate rating and anonymous 4-5 star comment snippets - never client names, contact names, or ticket subjects - so the response is safe to embed directly on a public marketing site with no further filtering by the caller. Cached for 5 minutes (Cache-Control: public, max-age=300). security: [] responses: '200': description: CSAT summary content: application/json: schema: type: object properties: average_rating: {type: number, format: float, nullable: true, example: 4.8} total_ratings: {type: integer, example: 132} rating_breakdown: type: object properties: "1": {type: integer} "2": {type: integer} "3": {type: integer} "4": {type: integer} "5": {type: integer} testimonials: type: array items: type: object properties: rating: {type: integer, example: 5} comment: {type: string, example: "Great information on the specs. Thank you for putting this together."} date: {type: string, format: date, example: "2026-07-31"} '405': {$ref: '#/components/responses/BadRequest'} '429': {$ref: '#/components/responses/RateLimited'} /dashboard: get: tags: [Dashboard] summary: Agent dashboard counters and personal ticket queue responses: '200': description: Dashboard summary content: application/json: schema: $ref: '#/components/schemas/DashboardResponse' '401': {$ref: '#/components/responses/Unauthorized'} /tickets: get: tags: [Tickets] summary: List tickets (paged, filterable) parameters: - {name: status, in: query, schema: {type: string, enum: [open, closed, all], default: open}} - {name: mine, in: query, schema: {type: integer, enum: [0, 1]}} - {$ref: '#/components/parameters/SearchParam'} - {$ref: '#/components/parameters/PageParam'} - {$ref: '#/components/parameters/LimitParam'} - {name: priority, in: query, description: 'One or more of low, medium, high (comma-separated or repeated: high,medium)', schema: {type: string}} - {name: assigned, in: query, description: 'Comma-separated: me, unassigned, and/or agent ids (me,7)', schema: {type: string}} - {name: board, in: query, description: 'Board (top-level category) ids, comma-separated', schema: {type: string}} - {name: onsite, in: query, description: '1 on-site, 0 remote, or both (0,1 = no filter)', schema: {type: string}} - {name: category_id, in: query, description: 'Category ids, comma-separated', schema: {type: string}} - {name: client_id, in: query, schema: {type: integer}} - {name: contact_id, in: query, schema: {type: integer}} - {name: overdue, in: query, schema: {type: integer}} - {name: due_today, in: query, schema: {type: integer}} responses: '200': description: Paged ticket list content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/TicketListItem'}} total: {type: integer} page: {type: integer} limit: {type: integer} '401': {$ref: '#/components/responses/Unauthorized'} post: tags: [Tickets] summary: Create a ticket (JSON or multipart with files) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTicketRequest' multipart/form-data: schema: $ref: '#/components/schemas/CreateTicketRequest' responses: '201': description: Ticket created content: application/json: schema: type: object properties: id: {type: integer} number: {type: integer} attachments: {type: array, items: {$ref: '#/components/schemas/Attachment'}} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} /tickets/{id}: get: tags: [Tickets] summary: Ticket detail with replies and attachments parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Ticket detail content: application/json: schema: $ref: '#/components/schemas/TicketDetail' '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /tickets/{id}/reply: post: tags: [Tickets] summary: Add a reply or internal note (JSON or multipart with files) parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddReplyRequest' multipart/form-data: schema: $ref: '#/components/schemas/AddReplyRequest' responses: '201': description: Reply created content: application/json: schema: type: object properties: id: {type: integer} type: {type: string} ticket_status: {type: object, properties: {id: {type: integer}, name: {type: string}}} attachments: {type: array, items: {$ref: '#/components/schemas/Attachment'}} '400': {$ref: '#/components/responses/BadRequest'} '404': {$ref: '#/components/responses/NotFound'} /tickets/{id}/reply/{replyId}: delete: tags: [Tickets] summary: Delete a reply (and its attachments) parameters: - {$ref: '#/components/parameters/IdPath'} - {name: replyId, in: path, required: true, schema: {type: integer}} responses: '200': {$ref: '#/components/responses/Ok'} '400': {$ref: '#/components/responses/BadRequest'} '404': {$ref: '#/components/responses/NotFound'} /tickets/{id}/time: post: tags: [Tickets] summary: Log time against a ticket (creates an internal reply) parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: type: object required: [time_worked] properties: time_worked: {type: string, example: "01:30:00", description: HH:MM:SS} note: {type: string} responses: '201': {$ref: '#/components/responses/Ok'} '400': {$ref: '#/components/responses/BadRequest'} /tickets/{id}/status: post: tags: [Tickets] summary: Change ticket status (setting a Closed status resolves it) parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: type: object required: [status_id] properties: status_id: {type: integer} responses: '200': {$ref: '#/components/responses/Ok'} '400': {$ref: '#/components/responses/BadRequest'} /tickets/{id}/attachments: post: tags: [Tickets] summary: Upload one or more attachments to a ticket parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: multipart/form-data: schema: type: object properties: file: {type: string, format: binary} 'files[]': {type: array, items: {type: string, format: binary}} responses: '201': description: Attachment(s) saved content: application/json: schema: oneOf: - $ref: '#/components/schemas/Attachment' - type: object properties: attachments: {type: array, items: {$ref: '#/components/schemas/Attachment'}} '400': {$ref: '#/components/responses/BadRequest'} /tickets/{id}/chat: get: tags: [Tickets] summary: Live-chat messages for a ticket (add ?stream=1 for an SSE feed) parameters: - {$ref: '#/components/parameters/IdPath'} - {name: since_id, in: query, schema: {type: integer, default: 0}} - {name: stream, in: query, schema: {type: integer}, description: When present, responds with a text/event-stream SSE feed instead of JSON} responses: '200': description: Chat messages content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/ChatMessage'}} text/event-stream: schema: {type: string} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} post: tags: [Tickets] summary: Send a live-chat message parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: type: object required: [message] properties: message: {type: string} contact_id: {type: integer, description: Post on behalf of one of the ticket's client's contacts} responses: '201': description: Message stored content: application/json: schema: type: object properties: {id: {type: integer}} '400': {$ref: '#/components/responses/BadRequest'} '404': {$ref: '#/components/responses/NotFound'} /tickets/{id}/charges: get: tags: [Tickets] summary: List charges on a ticket parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Charges plus running total content: application/json: schema: type: object properties: charges: {type: array, items: {$ref: '#/components/schemas/Charge'}} total: {type: number} '403': {$ref: '#/components/responses/Forbidden'} post: tags: [Tickets] summary: Add a charge to a ticket parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: type: object required: [name] properties: name: {type: string} description: {type: string} quantity: {type: number, default: 1} unit_price: {type: number, default: 0} responses: '201': description: Charge created content: application/json: schema: type: object properties: {id: {type: integer}, total: {type: number}} '400': {$ref: '#/components/responses/BadRequest'} /tickets/{id}/worksheets: get: tags: [Worksheets] summary: List worksheets attached to a ticket parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Worksheet summaries content: application/json: schema: type: array items: {$ref: '#/components/schemas/WorksheetSummary'} '403': {$ref: '#/components/responses/Forbidden'} post: tags: [Worksheets] summary: Create a worksheet on a ticket from a template parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: type: object required: [template_id] properties: template_id: {type: integer} is_outtake: {type: integer, enum: [0, 1]} responses: '201': description: Worksheet created content: application/json: schema: type: object properties: {id: {type: integer}} '400': {$ref: '#/components/responses/BadRequest'} /tickets/{id}/outtakes: get: tags: [Outtakes] summary: List device-outtake (pickup) forms for a ticket parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Outtake summaries content: application/json: schema: type: array items: {$ref: '#/components/schemas/OuttakeSummary'} '403': {$ref: '#/components/responses/Forbidden'} /tickets/{id}/outtake: post: tags: [Outtakes] summary: Create a device-outtake form on a ticket parameters: - {$ref: '#/components/parameters/IdPath'} responses: '201': description: Outtake created content: application/json: schema: type: object properties: {id: {type: integer}} /statuses: get: tags: [Ticket Meta] summary: List active ticket statuses (bare array) responses: '200': description: Ticket statuses content: application/json: schema: type: array items: {$ref: '#/components/schemas/TicketStatus'} /ticket-categories: get: tags: [Ticket Meta] summary: List ticket categories (bare array) responses: '200': description: Ticket categories content: application/json: schema: type: array items: {$ref: '#/components/schemas/TicketCategory'} /ticket-views: get: tags: [Ticket Meta] summary: List saved ticket views translated to list query params (bare array) responses: '200': description: Saved views content: application/json: schema: type: array items: {$ref: '#/components/schemas/SavedTicketView'} /clients: get: tags: [Clients] summary: List clients (paged) parameters: - {$ref: '#/components/parameters/SearchParam'} - {$ref: '#/components/parameters/PageParam'} - {$ref: '#/components/parameters/LimitParam'} responses: '200': description: Paged client list content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/ClientListItem'}} total: {type: integer} '403': {$ref: '#/components/responses/Forbidden'} /clients/{id}: get: tags: [Clients] summary: Client detail with contacts and primary location parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Client detail content: application/json: schema: $ref: '#/components/schemas/ClientDetail' '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /clients/{id}/tickets: get: tags: [Clients] summary: Recent tickets for a client (bare array) parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Ticket summaries content: application/json: schema: {type: array, items: {$ref: '#/components/schemas/TicketListItem'}} '403': {$ref: '#/components/responses/Forbidden'} /clients/{id}/assets: get: tags: [Clients] summary: Assets for a client (bare array) parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Asset summaries content: application/json: schema: {type: array, items: {$ref: '#/components/schemas/AssetListItem'}} '403': {$ref: '#/components/responses/Forbidden'} /clients/{id}/locations: get: tags: [Clients] summary: Locations for a client (bare array) parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Locations content: application/json: schema: {type: array, items: {$ref: '#/components/schemas/ClientLocation'}} '403': {$ref: '#/components/responses/Forbidden'} /clients/{id}/credentials: get: tags: [Clients] summary: Credential names for a client (no secrets; bare array) parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Credential summaries content: application/json: schema: {type: array, items: {$ref: '#/components/schemas/CredentialListItem'}} '403': {$ref: '#/components/responses/Forbidden'} /clients/{id}/contracts: get: tags: [Clients] summary: Contracts for a client (bare array) parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Contracts content: application/json: schema: {type: array, items: {type: object}} '403': {$ref: '#/components/responses/Forbidden'} /clients/{id}/files: get: tags: [Clients] summary: Signed outtake forms for a client (bare array) parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Files content: application/json: schema: {type: array, items: {type: object}} '403': {$ref: '#/components/responses/Forbidden'} /clients/{id}/allowance: get: tags: [Clients] summary: Included support-hours allowance vs. usage for a calendar month, rolled up across the client's active contracts plus a per-contract breakdown parameters: - {$ref: '#/components/parameters/IdPath'} - {name: month, in: query, description: '1-12, defaults to current month', schema: {type: integer}} - {name: year, in: query, description: 'defaults to current year', schema: {type: integer}} responses: '200': description: Allowance usage content: application/json: schema: $ref: '#/components/schemas/AllowanceUsage' '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} /contacts: get: tags: [Contacts] summary: List contacts (paged, filterable by client) parameters: - {name: client_id, in: query, schema: {type: integer}} - {$ref: '#/components/parameters/SearchParam'} - {$ref: '#/components/parameters/PageParam'} - {$ref: '#/components/parameters/LimitParam'} responses: '200': description: Paged contact list content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/Contact'}} total: {type: integer} /assets: get: tags: [Assets] summary: List assets (paged, filterable) parameters: - {$ref: '#/components/parameters/SearchParam'} - {$ref: '#/components/parameters/PageParam'} - {$ref: '#/components/parameters/LimitParam'} - {name: type, in: query, schema: {type: string}} - {name: client_id, in: query, schema: {type: integer}} responses: '200': description: Paged asset list content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/AssetListItem'}} total: {type: integer} /assets/types: get: tags: [Assets] summary: Distinct asset types in use (bare string array) responses: '200': description: Asset type names content: application/json: schema: {type: array, items: {type: string}} /assets/{id}: get: tags: [Assets] summary: Asset detail parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Asset detail content: application/json: schema: {$ref: '#/components/schemas/AssetDetail'} '404': {$ref: '#/components/responses/NotFound'} /relationships: get: tags: [Relationships] summary: Links of one record (outgoing, referenced by, and what depends on it) description: > Returns the explicit links (entity_links) and read-only derived rows from the older link tables (asset documents, software licences, service assets, ...) for one record, plus a transitive "impact" list (what depends on it, up to three levels, cycle safe). Results are limited to records the caller's role and department access allow. parameters: - {name: type, in: query, required: true, schema: {type: string, enum: [asset, software, vendor, document, kb_article, service, network, domain, certificate, credential, contact, location, ticket]}} - {name: id, in: query, required: true, schema: {type: integer}} responses: '200': description: Relationships of the record content: application/json: schema: {$ref: '#/components/schemas/RelationshipView'} '400': {$ref: '#/components/responses/BadRequest'} '404': {$ref: '#/components/responses/NotFound'} post: tags: [Relationships] summary: Link two records description: Needs change access to the source record's module and view access to the target's. Both records must be in the same department unless one is kept in no department (a global vendor or KB article). requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/RelationshipCreate'} responses: '201': description: Created content: application/json: schema: type: object properties: link_id: {type: integer} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} '409': description: Already linked that way content: application/json: schema: {$ref: '#/components/schemas/Error'} '422': description: Different departments, or a record linked to itself content: application/json: schema: {$ref: '#/components/schemas/Error'} /relationships/{id}: delete: tags: [Relationships] summary: Remove a link (derived rows cannot be removed here) parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': {$ref: '#/components/responses/Ok'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /projects: get: tags: [Projects] summary: List projects (paged, filterable) parameters: - {$ref: '#/components/parameters/SearchParam'} - {$ref: '#/components/parameters/PageParam'} - {$ref: '#/components/parameters/LimitParam'} - {name: status, in: query, schema: {type: string, enum: [open, completed, all], default: open}} - {name: archived, in: query, schema: {type: integer, enum: [0, 1], default: 0}} - {name: client_id, in: query, schema: {type: integer}} - {name: mine, in: query, schema: {type: integer, enum: [0, 1]}, description: Only projects managed by the caller} responses: '200': description: Paged project list content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/ProjectListItem'}} total: {type: integer} page: {type: integer} limit: {type: integer} /projects/{id}: get: tags: [Projects] summary: Project detail with milestones, tasks and linked tickets parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Project detail content: application/json: schema: {$ref: '#/components/schemas/ProjectDetail'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /contracts: get: tags: [Contracts] summary: List contracts (paged, filterable). Billing-adjacent client data - requires module_client. parameters: - {$ref: '#/components/parameters/SearchParam'} - {$ref: '#/components/parameters/PageParam'} - {$ref: '#/components/parameters/LimitParam'} - {name: status, in: query, schema: {type: string}, description: 'Raw contract_status value (e.g. Active, Expired, Cancelled) - manually set, not auto-derived from dates'} - {name: client_id, in: query, schema: {type: integer}} - {name: expiring, in: query, schema: {type: integer, enum: [0, 1]}, description: 'Only contracts already past renewal_date or due within 45 days'} responses: '200': description: Paged contract list content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/ContractListItem'}} total: {type: integer} page: {type: integer} limit: {type: integer} /contracts/{id}: get: tags: [Contracts] summary: Contract detail with SLA, current-month hours-allowance usage, and documents parameters: - {$ref: '#/components/parameters/IdPath'} - {name: month, in: query, description: 'Allowance month, 1-12, defaults to current month', schema: {type: integer}} - {name: year, in: query, description: 'Allowance year, defaults to current year', schema: {type: integer}} responses: '200': description: Contract detail content: application/json: schema: {$ref: '#/components/schemas/ContractDetail'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /tasks: post: tags: [Projects] summary: Create a project task (scope api:tasks:write; project_id and name required) requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/ProjectTaskInput'} responses: '201': description: Created task content: application/json: schema: {$ref: '#/components/schemas/ProjectTask'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /tasks/{id}: get: tags: [Projects] summary: One task, with priority, description, colour and labels parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Task content: application/json: schema: {$ref: '#/components/schemas/ProjectTask'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} patch: tags: [Projects] summary: Change the fields sent (scope api:tasks:write); PUT behaves the same parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/ProjectTaskInput'} responses: '200': description: Updated task content: application/json: schema: {$ref: '#/components/schemas/ProjectTask'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} put: tags: [Projects] summary: Same as PATCH (only the fields sent change) parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/ProjectTaskInput'} responses: '200': description: Updated task content: application/json: schema: {$ref: '#/components/schemas/ProjectTask'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} delete: tags: [Projects] summary: Delete a task and its label links (scope api:tasks:delete; Service Desk level 3) parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Deleted content: application/json: schema: type: object properties: deleted: {type: boolean} id: {type: integer} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /tasks/{id}/checklist: get: tags: [Projects] summary: A task's checklist items (database 2.6.208) parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Items in order content: application/json: schema: type: object properties: items: type: array items: {$ref: '#/components/schemas/TaskChecklistItem'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} '409': {description: Update Database has not run yet} post: tags: [Projects] summary: Add a checklist item at the end (scope api:tasks:write) parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: type: object required: [text] properties: text: {type: string, maxLength: 255} responses: '201': description: The new item content: application/json: schema: {$ref: '#/components/schemas/TaskChecklistItem'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /tasks/{id}/checklist/{itemId}: patch: tags: [Projects] summary: Change an item's text and/or done flag (scope api:tasks:write) parameters: - {$ref: '#/components/parameters/IdPath'} - {name: itemId, in: path, required: true, schema: {type: integer}} requestBody: required: true content: application/json: schema: type: object properties: text: {type: string, maxLength: 255} done: {type: boolean} responses: '200': description: The item content: application/json: schema: {$ref: '#/components/schemas/TaskChecklistItem'} '400': {$ref: '#/components/responses/BadRequest'} '404': {$ref: '#/components/responses/NotFound'} delete: tags: [Projects] summary: Delete an item (scope api:tasks:delete) parameters: - {$ref: '#/components/parameters/IdPath'} - {name: itemId, in: path, required: true, schema: {type: integer}} responses: '200': {description: '{deleted: true, id}'} '404': {$ref: '#/components/responses/NotFound'} /tasks/{id}/subtasks: get: tags: [Projects] summary: A task's subtasks (database 2.6.208) parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Subtasks in order content: application/json: schema: type: object properties: subtasks: type: array items: type: object properties: id: {type: integer} name: {type: string} done: {type: boolean} '404': {$ref: '#/components/responses/NotFound'} post: tags: [Projects] summary: Create a subtask (scope api:tasks:write). A subtask cannot have subtasks. parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: type: object required: [name] properties: name: {type: string, maxLength: 255} responses: '201': description: The new task (its parent_id is this task) content: application/json: schema: {$ref: '#/components/schemas/ProjectTask'} '400': {$ref: '#/components/responses/BadRequest'} /tasks/{id}/comments: get: tags: [Projects] summary: A task's comments, oldest first (database 2.6.208) parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Comments content: application/json: schema: type: object properties: comments: type: array items: {$ref: '#/components/schemas/TaskComment'} '404': {$ref: '#/components/responses/NotFound'} post: tags: [Projects] summary: Add a comment as the caller (scope api:tasks:write) parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: type: object required: [body] properties: body: {type: string, maxLength: 20000, description: Plain text (tags are stripped)} responses: '201': {description: '{id}'} '400': {$ref: '#/components/responses/BadRequest'} /tasks/{id}/comments/{commentId}: patch: tags: [Projects] summary: Edit a comment (its author only; scope api:tasks:write) parameters: - {$ref: '#/components/parameters/IdPath'} - {name: commentId, in: path, required: true, schema: {type: integer}} requestBody: required: true content: application/json: schema: type: object required: [body] properties: body: {type: string} responses: '200': {description: '{id}'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} delete: tags: [Projects] summary: Delete a comment (its author, or an administrator; scope api:tasks:delete) parameters: - {$ref: '#/components/parameters/IdPath'} - {name: commentId, in: path, required: true, schema: {type: integer}} responses: '200': {description: '{deleted: true, id}'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /tasks/{id}/attachments: get: tags: [Projects] summary: Metadata of a task's files (database 2.6.209); never the stored name parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Files content: application/json: schema: type: object properties: attachments: type: array items: type: object properties: id: {type: integer} name: {type: string} size: {type: integer} mime: {type: string, nullable: true} uploaded_by: {type: string, nullable: true} created_at: {type: string} post: tags: [Projects] summary: Attach 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. parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: multipart/form-data: schema: type: object required: [file] properties: file: {type: string, format: binary} responses: '201': {description: '{id}'} '400': {$ref: '#/components/responses/BadRequest'} /tasks/{id}/attachments/{attachmentId}: get: tags: [Projects] summary: Download a file (always sent as an attachment, application/octet-stream, nosniff) parameters: - {$ref: '#/components/parameters/IdPath'} - {name: attachmentId, in: path, required: true, schema: {type: integer}} responses: '200': description: The file bytes content: application/octet-stream: schema: {type: string, format: binary} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} delete: tags: [Projects] summary: Delete a file (the uploader, or Service Desk level 3 / an administrator; scope api:tasks:delete) parameters: - {$ref: '#/components/parameters/IdPath'} - {name: attachmentId, in: path, required: true, schema: {type: integer}} responses: '200': {description: '{deleted: true, id}'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /tasks/{id}/toggle: post: tags: [Projects] summary: Toggle a task's completed state (works for both project-only tasks and ticket-linked tasks) parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Updated task content: application/json: schema: {$ref: '#/components/schemas/ProjectTask'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /milestones/{id}/toggle: post: tags: [Projects] summary: Toggle a project milestone's completed state parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Updated milestone content: application/json: schema: {$ref: '#/components/schemas/ProjectMilestone'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /credentials: get: tags: [Credentials] summary: List credentials (names/URIs only, no secrets; paged). Requires a user token (API keys are denied). parameters: - {$ref: '#/components/parameters/SearchParam'} - {$ref: '#/components/parameters/PageParam'} - {$ref: '#/components/parameters/LimitParam'} - {name: client_id, in: query, schema: {type: integer}} responses: '200': description: Paged credential list (no secrets) content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/CredentialListItem'}} total: {type: integer} '403': {$ref: '#/components/responses/Forbidden'} /credentials/{id}: get: tags: [Credentials] summary: Decrypted credential detail — requires a signed biometric step-up challenge parameters: - {$ref: '#/components/parameters/IdPath'} - {name: X-Biometric-Challenge-Token, in: header, required: true, schema: {type: string}, description: challengeToken from GET /auth} - {name: X-Biometric-Signature, in: header, required: true, schema: {type: string}, description: base64 signature of the challenge bytes} responses: '200': description: Credential with decrypted secrets content: application/json: schema: {$ref: '#/components/schemas/CredentialDetail'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /worksheets/{id}: get: tags: [Worksheets] summary: Worksheet detail with fields and current responses parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Worksheet detail content: application/json: schema: {$ref: '#/components/schemas/WorksheetDetail'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} delete: tags: [Worksheets] summary: Delete a worksheet parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': {$ref: '#/components/responses/Ok'} /worksheets/{id}/sign: post: tags: [Worksheets] summary: Sign a worksheet parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/SignRequest'} responses: '200': {$ref: '#/components/responses/Ok'} '400': {$ref: '#/components/responses/BadRequest'} /worksheets/{id}/complete: post: tags: [Worksheets] summary: Mark a worksheet complete or incomplete without signing parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: type: object properties: {completed: {type: boolean}} responses: '200': {$ref: '#/components/responses/Ok'} '400': {$ref: '#/components/responses/BadRequest'} '404': {$ref: '#/components/responses/NotFound'} /worksheets/{id}/responses: post: tags: [Worksheets] summary: Save worksheet field responses (marks complete) parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: type: object properties: responses: type: array items: type: object properties: field_id: {type: integer} value: {type: string} responses: '200': {$ref: '#/components/responses/Ok'} /worksheet-templates: get: tags: [Worksheets] summary: List worksheet templates (bare array) responses: '200': description: Templates content: application/json: schema: {type: array, items: {$ref: '#/components/schemas/WorksheetTemplate'}} /outtakes/{id}: get: tags: [Outtakes] summary: Outtake form detail parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Outtake detail content: application/json: schema: {$ref: '#/components/schemas/OuttakeDetail'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} delete: tags: [Outtakes] summary: Delete an outtake form parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': {$ref: '#/components/responses/Ok'} /outtakes/{id}/sign: post: tags: [Outtakes] summary: Sign an outtake form parameters: - {$ref: '#/components/parameters/IdPath'} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/SignRequest'} responses: '200': {$ref: '#/components/responses/Ok'} '400': {$ref: '#/components/responses/BadRequest'} /search: get: tags: [Search] summary: Global search across tickets, clients, assets, software, networks, services, contacts, credentials, KB articles and linked records parameters: - {name: q, in: query, required: true, schema: {type: string, minLength: 2}} responses: '200': description: Grouped search results content: application/json: schema: {$ref: '#/components/schemas/SearchResult'} '400': {$ref: '#/components/responses/BadRequest'} /reports/time: get: tags: [Reports] summary: Time logged grouped by client parameters: - {name: period, in: query, schema: {type: string, enum: [week, month, all], default: week}} - {name: mine, in: query, schema: {type: integer, enum: [0, 1]}} responses: '200': {$ref: '#/components/responses/ReportObject'} /reports/tickets: get: tags: [Reports] summary: Ticket volume by month for a year parameters: - {$ref: '#/components/parameters/YearParam'} responses: '200': {$ref: '#/components/responses/ReportObject'} /reports/tickets-by-client: get: tags: [Reports] summary: Ticket counts by client parameters: - {$ref: '#/components/parameters/YearParam'} - {name: month, in: query, schema: {type: integer}} responses: '200': {$ref: '#/components/responses/ReportObject'} /reports/time-by-tech: get: tags: [Reports] summary: Time logged grouped by technician parameters: - {$ref: '#/components/parameters/YearParam'} responses: '200': {$ref: '#/components/responses/ReportObject'} /reports/tech-performance: get: tags: [Reports] summary: Technician performance summary parameters: - {$ref: '#/components/parameters/YearParam'} responses: '200': {$ref: '#/components/responses/ReportObject'} /reports/technician-performance: get: tags: [Reports] summary: Detailed technician performance report parameters: - {$ref: '#/components/parameters/YearParam'} responses: '200': {$ref: '#/components/responses/ReportObject'} /reports/service-desk: get: tags: [Reports] summary: Service-desk report parameters: - {$ref: '#/components/parameters/YearParam'} responses: '200': {$ref: '#/components/responses/ReportObject'} /reports/csat: get: tags: [Reports] summary: Customer satisfaction (CSAT) report - 1-5 star ratings, distribution, trend, per-technician/per-client breakdowns, raw feedback feed parameters: - {$ref: '#/components/parameters/YearParam'} responses: '200': {$ref: '#/components/responses/ReportObject'} /reports/rmm-health: get: tags: [Reports] summary: RMM fleet health report responses: '200': {$ref: '#/components/responses/ReportObject'} /reports/unbilled-tickets: get: tags: [Reports] summary: Clients with unbilled billable closed tickets parameters: - {$ref: '#/components/parameters/YearParam'} responses: '200': {$ref: '#/components/responses/ReportObject'} /reports/expiring: get: tags: [Reports] summary: Domains or certificates expiring within N days parameters: - {name: type, in: query, schema: {type: string, enum: [domains, certificates], default: domains}} - {name: days, in: query, schema: {type: integer, default: 30}} responses: '200': {$ref: '#/components/responses/ReportObject'} '400': {$ref: '#/components/responses/BadRequest'} /reports/overview: get: tags: [Reports] summary: Open-ticket breakdown by priority/status/category plus avg resolution parameters: - {$ref: '#/components/parameters/YearParam'} responses: '200': {$ref: '#/components/responses/ReportObject'} /kb/categories: get: tags: [Knowledge Base] summary: List KB categories (bare array) responses: '200': description: Categories content: application/json: schema: {type: array, items: {$ref: '#/components/schemas/KbCategory'}} /kb/articles: get: tags: [Knowledge Base] summary: List KB articles (paged, filterable) parameters: - {name: category_id, in: query, schema: {type: integer}} - {name: client_id, in: query, schema: {type: integer}} - {$ref: '#/components/parameters/SearchParam'} - {$ref: '#/components/parameters/PageParam'} - {$ref: '#/components/parameters/LimitParam'} responses: '200': description: Paged article list content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/KbArticleListItem'}} total: {type: integer} /kb/articles/{id}: get: tags: [Knowledge Base] summary: KB article detail (content + attachments) parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Article detail content: application/json: schema: {$ref: '#/components/schemas/KbArticleDetail'} '404': {$ref: '#/components/responses/NotFound'} /me: get: tags: [Profile] summary: Current user profile. Requires a user token (API keys are denied). responses: '200': description: Profile content: application/json: schema: {$ref: '#/components/schemas/UserProfile'} put: tags: [Profile] summary: Update profile / password, or register FCM push or biometric key requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/UpdateProfileRequest'} responses: '200': {$ref: '#/components/responses/Ok'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} post: tags: [Profile] summary: Update profile / password (alias of PUT - FCM push and biometric key registration require PUT) requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/UpdateProfileRequest'} responses: '200': {$ref: '#/components/responses/Ok'} '400': {$ref: '#/components/responses/BadRequest'} '401': {$ref: '#/components/responses/Unauthorized'} /appointments: get: tags: [Appointments] summary: List ticket appointments (bare array) parameters: - {name: when, in: query, schema: {type: string, enum: [past, today, future], default: future}} - {name: mine, in: query, schema: {type: integer, enum: [0, 1]}} - {name: client_id, in: query, schema: {type: integer}} responses: '200': description: Appointments content: application/json: schema: {type: array, items: {$ref: '#/components/schemas/Appointment'}} post: tags: [Appointments] summary: Create a ticket appointment (schedule entry) requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/CreateAppointmentRequest'} responses: '201': description: Appointment created content: application/json: schema: type: object properties: {id: {type: integer}} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /notifications: get: tags: [Notifications] summary: List undismissed notifications (paged) parameters: - {$ref: '#/components/parameters/PageParam'} - {$ref: '#/components/parameters/LimitParam'} responses: '200': description: Paged notification list content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/Notification'}} total: {type: integer} /notifications/{id}/read: post: tags: [Notifications] summary: Mark a single notification read/dismissed parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': {$ref: '#/components/responses/Ok'} /notifications/read-all: post: tags: [Notifications] summary: Mark all notifications read/dismissed responses: '200': {$ref: '#/components/responses/Ok'} /notifications/stream: get: tags: [Notifications] summary: Server-Sent Events stream of new notifications responses: '200': description: SSE stream content: text/event-stream: schema: {type: string} /approvals: get: tags: [Mobile] summary: Approvals the caller may decide right now (service catalog requests + workflow approval tasks) description: > Needs a user token (API keys denied) and Tickets (catalog) and/or Departments (workflow) access. Same rules as agent/service_catalog_approvals.php and the workflow run page; administrators also see every other pending catalog request (decided as an override). Module-only (limited) logins get 403. responses: '200': description: Pending approvals, oldest first content: application/json: schema: {$ref: '#/components/schemas/ApprovalList'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} post: tags: [Mobile] summary: Approve or reject one approval description: > Goes through ServiceCatalogService::decide / WorkflowService::approveTask|rejectTask, so state machine, notifications, audit and ticket hold/release behave as on the web. An id that does not exist, is already decided, or is not addressed to the caller returns the same 404. requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/ApprovalDecision'} responses: '200': description: Decision recorded content: application/json: schema: type: object properties: ok: {type: boolean} status: {type: string, description: "approved, rejected, or pending_approval (a further catalog step is now waiting)"} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} '409': description: Lost a race - the approval was decided in the meantime '422': description: Validation error (bad kind/id/decision, or a reject without a comment) /automation_rules: get: tags: [Automation] summary: List event rules description: > Administrators only, user token only (an integration client gets 403). The webhook signing secret is never returned (action_config.has_secret says whether one is set). parameters: - {name: q, in: query, schema: {type: string}, description: Matches name or trigger event} - {name: trigger_event, in: query, schema: {type: string}} - {name: action_type, in: query, schema: {type: string}} - {name: enabled, in: query, schema: {type: string, enum: ['0', '1']}} - {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 200, default: 50}} - {name: offset, in: query, schema: {type: integer, minimum: 0, default: 0}} responses: '200': description: Rules, ordered by event then priority content: application/json: schema: type: object properties: rules: {type: array, items: {$ref: '#/components/schemas/AutomationRule'}} total: {type: integer} limit: {type: integer} offset: {type: integer} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} post: tags: [Automation] summary: Create an event rule description: > The same validation as the Event rules editor. action_config is the action's input (see docs/AUTOMATION.md, "Rules over the API"): e.g. send_mail {to_type, subject, body, address|user_id}, notify_chat {destination, message}, run_script {script_id, run_as_user_id, params, timeout_s}. Risky actions (run_script, create_odoo_user, entra_*) can be saved but do nothing until their switch / integration is set up. requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/AutomationRuleInput'} responses: '201': description: Created content: application/json: schema: {type: object, properties: {rule: {$ref: '#/components/schemas/AutomationRule'}}} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} '422': {description: Validation error (the message names the problem)} /automation_rules/{id}: parameters: - {name: id, in: path, required: true, schema: {type: integer}} get: tags: [Automation] summary: One event rule, with its last run and run counts responses: '200': description: The rule content: application/json: schema: {type: object, properties: {rule: {$ref: '#/components/schemas/AutomationRule'}}} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} put: tags: [Automation] summary: Replace an event rule (name, trigger_event, action_type and action_config are required) requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/AutomationRuleInput'} responses: '200': description: Saved content: application/json: schema: {type: object, properties: {rule: {$ref: '#/components/schemas/AutomationRule'}}} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} '422': {description: Validation error} patch: tags: [Automation] summary: Change some fields of an event rule (omitted fields, including action_config, are kept) requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/AutomationRuleInput'} responses: '200': description: Saved content: application/json: schema: {type: object, properties: {rule: {$ref: '#/components/schemas/AutomationRule'}}} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} '422': {description: Validation error} delete: tags: [Automation] summary: Delete an event rule (its run log rows stay) responses: '200': description: Deleted content: application/json: schema: {type: object, properties: {deleted: {type: boolean}, rule_id: {type: integer}}} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /automation_rules/runs: get: tags: [Automation] summary: The rule run log parameters: - {name: rule_id, in: query, schema: {type: integer}} - {name: status, in: query, schema: {type: string, enum: [ok, failed, throttled, loop_blocked, skipped]}} - {name: event, in: query, schema: {type: string}} - {name: failed, in: query, schema: {type: string, enum: ['1']}, description: Failed runs only} - {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 200, default: 50}} - {name: offset, in: query, schema: {type: integer, minimum: 0, default: 0}} responses: '200': description: Runs, newest first content: application/json: schema: type: object properties: runs: {type: array, items: {$ref: '#/components/schemas/AutomationRun'}} total: {type: integer} counts: {type: object, additionalProperties: {type: integer}} '403': {$ref: '#/components/responses/Forbidden'} /automation_rules/runs/{id}: parameters: - {name: id, in: path, required: true, schema: {type: integer}, description: Run id} get: tags: [Automation] summary: One run responses: '200': description: The run content: application/json: schema: {type: object, properties: {run: {$ref: '#/components/schemas/AutomationRun'}}} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /automation_rules/retry/{id}: parameters: - {name: id, in: path, required: true, schema: {type: integer}, description: Id of the FAILED run to repeat} post: tags: [Automation] summary: Run a failed run again by hand description: > Uses the event the failed run kept and creates a new run (source "manual", retry_of_run_id = this run). Refused with 409 when the run did not fail, kept no event, its rule is gone or off, or a retry of it already succeeded. responses: '200': description: The new run's result (status may still be failed) content: application/json: schema: type: object properties: status: {type: string} ok: {type: boolean} message: {type: string} run_id: {type: integer} retry_of_run_id: {type: integer} '403': {$ref: '#/components/responses/Forbidden'} '409': {description: Cannot be run again (the message says why)} /automation_rules/meta: get: tags: [Automation] summary: Events, actions, condition operators and enrichment fields the editor offers responses: '200': description: Metadata content: application/json: schema: {type: object} '403': {$ref: '#/components/responses/Forbidden'} /service_catalog: get: tags: [Mobile] summary: Active service catalog items with their request forms description: Needs a user token and Tickets access. categories = the tile groups; popular = top 5 items of the last 30 days; recent = the caller's last 5 distinct items. responses: '200': description: Catalog content: application/json: schema: {$ref: '#/components/schemas/CatalogList'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} post: tags: [Mobile] summary: Raise a ticket from a catalog item description: > Validated exactly like the web form (required, type, select choices, table rows and cells, 500/5000 length caps); answers whose key is not a defined field are ignored. The caller is the requester. Needs Tickets edit access and access to client_id's department. The request's risk score is computed from the answers and routes it to the matching approval chain. This endpoint is a thin wrapper over ServiceCatalogService::createRequest(), which is the entry point chat integrations (Slack / Teams) are meant to call. requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/CatalogRequest'} responses: '201': description: Ticket created (held when the item needs approval) content: application/json: schema: type: object properties: ok: {type: boolean} ticket_id: {type: integer} status: {type: string, enum: [created, pending_approval]} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} '422': description: Validation error; error holds the messages joined, errors the list /workflow_tasks: get: tags: [Mobile] summary: Open onboarding/offboarding checklist tasks description: > scope=mine (default): assigned to the caller plus unassigned tasks of runs the caller may access (Departments view + department access). scope=all: every open task of accessible runs, needs Departments edit access. status can also be running or rejected besides the listed values. parameters: - {name: scope, in: query, schema: {type: string, enum: [mine, all], default: mine}} responses: '200': description: Tasks, soonest due first content: application/json: schema: {$ref: '#/components/schemas/WorkflowTaskList'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} '422': description: Unknown scope post: tags: [Mobile] summary: Complete or skip a checklist task description: > Same rules as the web handlers (WorkflowService): blocked tasks and approval tasks cannot be completed by hand, skipping needs a reason, only administrators may skip an approval. Unknown and inaccessible tasks return the same 404. requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/WorkflowTaskAction'} responses: '200': description: Done; status is the task's new status content: application/json: schema: type: object properties: ok: {type: boolean} status: {type: string} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} '422': description: Validation error or a workflow rule (blocked, needs approval, reason required, admin only) /hr_requests: get: tags: [Mobile] summary: HR requests from the employee portal description: > Onboarding, offboarding and role-change requests that managers and department administrators made in the portal (Administration > Settings > Employee portal > HR requests). Nothing has started until a request is approved. Needs Departments edit access; only requests of departments the caller may access are listed. A user token is required. parameters: - {name: status, in: query, schema: {type: string, enum: [pending, approved, rejected, cancelled], default: pending}} responses: '200': description: Requests, newest first (at most 100); templates lists the workflow templates that can be started for a pending request content: application/json: schema: {$ref: '#/components/schemas/HrRequestList'} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} '422': description: Unknown status post: tags: [Mobile] summary: Approve or reject an HR request description: > approve needs template_id (an active template of the request's type) and starts that workflow through WorkflowService; reject needs a comment and starts nothing. A request outside the caller's departments and an unknown id return the same 404; a request that was already decided returns 409. requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/HrRequestDecision'} responses: '200': description: Decided; run_id is the started workflow run (approve only) content: application/json: schema: type: object properties: ok: {type: boolean} status: {type: string, enum: [approved, rejected]} run_id: {type: integer, nullable: true} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} '409': description: Already decided '422': description: Validation error (no template, wrong template type, reject without a comment, the person has left) /ticket_attachments: get: tags: [Mobile] summary: List a ticket's attachments, or download one description: > ticket_id=N lists. id=A&download=1 streams the file (Content-Disposition: attachment, nosniff, Cache-Control: no-store); id=A without download returns that one item's metadata. 403 for a ticket outside the caller's departments and for an unknown id (indistinguishable). Needs Tickets access. parameters: - {name: ticket_id, in: query, schema: {type: integer}} - {name: id, in: query, schema: {type: integer}} - {name: download, in: query, schema: {type: integer, enum: [1]}} responses: '200': description: Attachment list, or the file bytes when download=1 content: application/json: schema: {$ref: '#/components/schemas/TicketAttachmentList'} application/octet-stream: schema: {type: string, format: binary} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} '404': description: The file behind a known attachment is missing post: tags: [Mobile] summary: Upload one attachment (multipart) description: > Fields ticket_id, optional reply_id (must belong to the ticket) and file. Same extension allow-list as the web upload, plus content sniffing (an image extension must hold an image; script/markup content is refused), a check of every extension segment (shell.php.png is refused), a random stored name and the PHP/post size limits. requestBody: required: true content: multipart/form-data: schema: type: object required: [ticket_id, file] properties: ticket_id: {type: integer} reply_id: {type: integer} file: {type: string, format: binary} responses: '201': description: Stored content: application/json: schema: type: object properties: ok: {type: boolean} id: {type: integer} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} '413': description: File too large '422': description: Missing field, disallowed type or content /alerts: get: tags: [Alerts] summary: List combined RMM and backup alerts parameters: - {name: status, in: query, schema: {type: string, default: new}} - {name: severity, in: query, schema: {type: string, enum: [critical, error, warning, info]}} - {name: source, in: query, schema: {type: string, enum: [all, rmm, backup]}} - {name: client_id, in: query, schema: {type: integer}} responses: '200': description: Alert list content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/Alert'}} total: {type: integer} '403': {$ref: '#/components/responses/Forbidden'} post: tags: [Alerts] summary: Acknowledge or resolve an alert requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/AlertActionRequest'} responses: '200': {$ref: '#/components/responses/Ok'} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /validate_api_key: get: tags: [Meta] summary: Validate the presented access token (probe) responses: '200': description: Key is valid content: application/json: schema: type: object properties: success: {type: string, example: "True"} message: {type: string} '401': {$ref: '#/components/responses/Unauthorized'} /openapi: get: tags: [Meta] summary: This OpenAPI 3.0 spec as YAML (public) security: [] responses: '200': description: OpenAPI document content: application/yaml: schema: {type: string} /docs: get: tags: [Meta] summary: Human-readable HTML API reference (public, self-contained) security: [] responses: '200': description: HTML docs page content: text/html: schema: {type: string} /agent_enroll: post: tags: [Endpoint agent] summary: Enroll a Windows endpoint agent (device-facing, no Bearer) description: > Exchanges a short-lived enrollment token (carried in the body) for a unique per-device credential, shown once; only its SHA-256 is stored. Same install_id again, or a reinstall of the same machine (machine_guid or serial), keeps the device id and rotates the credential. Two different machines are never merged: ambiguous, out-of-department, hostname-only or already-owned matches return status pending_approval or ambiguous and wait for an administrator. TLS required. Rate limited per address (429 + Retry-After). See docs/ENDPOINT_AGENT.md. security: [] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/AgentEnrollRequest'} responses: '201': description: Enrolled content: application/json: schema: {$ref: '#/components/schemas/AgentEnrollResponse'} '401': {description: "Error code invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '403': {description: "Service disabled, token exhausted, or the device was revoked/retired (code forbidden)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '409': {description: "install_id belongs to a different machine (code conflict)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '413': {description: "Body too large", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '422': {description: "Invalid body (code invalid)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Too many attempts (Retry-After header)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /agent_checkin: post: tags: [Endpoint agent] summary: "Device check-in: inventory, metrics, checks (device credential)" description: > Idempotent by (device_id, seq): a retried check-in is acknowledged but never double counted. A missing metric (null or absent) is never stored as zero. collected_at must not be in the future (5 minutes skew) or older than the retention window; invalid buffered samples are dropped, not fatal. Feeds the existing asset RMM link, device metrics and RMM alerts (debounced, deduplicated). Optional extra field update_result {version, state ok|failed|rolled_back, detail} reports the last agent update. security: [{deviceAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/AgentCheckinRequest'} responses: '200': description: Accepted content: application/json: schema: {$ref: '#/components/schemas/AgentCheckinResponse'} '401': {description: "Credential invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '403': {description: "Service disabled", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '413': {description: "Body over 1 MiB", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '422': {description: "Invalid payload", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Rate limited (Retry-After header)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /agent_jobs: get: tags: [Endpoint agent] summary: Fetch this device's signed jobs (device credential, optional long poll) description: > Returns only the calling device's queued jobs, each signed (Ed25519 over the canonical JSON of the job fields). wait=1..5 holds the request open up to that many seconds. A destructive job (reboot, or flagged) is offered at most once; a harmless job whose acknowledgement was lost is re-offered with attempt + 1. A revoked device gets 401 revoked immediately. security: [{deviceAuth: []}] parameters: - {name: wait, in: query, required: false, schema: {type: integer, minimum: 0, maximum: 5}} responses: '200': description: Jobs (possibly empty) content: application/json: schema: type: object properties: jobs: {type: array, items: {$ref: '#/components/schemas/AgentJob'}} '401': {description: "Credential invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Rate limited", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} post: tags: [Endpoint agent] summary: Report a job's state or result (device credential) description: > Idempotent for a repeated identical final state; a conflicting final state, a cancelled/expired job, or a state going back to running is 409. Output is credential-redacted and capped before storage. A late real result replaces a server-side result_lost. security: [{deviceAuth: []}] requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/AgentJobReport'} responses: '200': {description: "Recorded", content: {application/json: {schema: {$ref: '#/components/schemas/Ok'}}}} '401': {description: "Credential invalid", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '404': {description: "Unknown job for this device", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '409': {description: "Conflict", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '413': {description: "Body over 256 KiB", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '422': {description: "Invalid body", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /agent_installer: post: tags: [Endpoint agent] summary: Download the stamped per-department installer with an enrollment token (for RMM, Intune, GPO scripts) description: > Public, token-gated. The enrollment token goes in the JSON or form body (or an Authorization Bearer header), NEVER in the query string (a token in the URL is refused with 400 so it stays out of access logs). Returns the current agent executable for the architecture with the department's installer payload and a 52-byte footer appended (see docs/ENDPOINT_AGENT.md section 'Stamped installer format'), streamed with an exact Content-Length. Any token that is not usable now (unknown, wrong, revoked, expired, used up) gets the same generic 404. Rate limited per address and per token from the database (429 + Retry-After). Successes and rejections are audited. The download does not consume an enrollment use; enrolling does. security: [] requestBody: required: true content: application/json: schema: type: object required: [arch] properties: token: {type: string, description: "rvte1..; may instead be sent as Authorization Bearer"} arch: {type: string, enum: [amd64, arm64]} application/x-www-form-urlencoded: schema: type: object required: [arch] properties: token: {type: string} arch: {type: string, enum: [amd64, arm64]} responses: '200': description: The stamped installer (RivetIT-Agent-Setup--.exe) content: application/octet-stream: schema: {type: string, format: binary} '400': {description: "Token supplied in the query string (code token_in_url)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '403': {description: "Service disabled", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '404': {description: "Generic: the token is not usable", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '405': {description: "Use POST", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '409': {description: "No published binary for that architecture, or no https service URL (code unavailable)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '413': {description: "Body over 4 KiB", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '422': {description: "token or arch missing or invalid", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Too many requests (Retry-After header)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /agent_update: get: tags: [Endpoint agent] summary: Download the hosted agent release this device is currently offered (device credential) description: > Streams the UNSTAMPED agent executable of the server-hosted release named by the update manifest (its url points here). Only the release the manifest offers THIS device right now is served, only for its own architecture, and only while the stored file still matches the manifest SHA-256. Anything else is a generic 404. Content-Length exact, nosniff, no-store. security: [{deviceAuth: []}] parameters: - {name: arch, in: query, required: true, schema: {type: string, enum: [amd64, arm64]}} - {name: version, in: query, required: true, schema: {type: string, example: 1.2.0}} responses: '200': description: The agent executable content: application/octet-stream: schema: {type: string, format: binary} '401': {description: "Credential invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '404': {description: "Not offered to this device (or damaged)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '422': {description: "arch or version invalid", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Rate limited", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '503': {description: "The stored binary is missing or failed its integrity check", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /agent_changes: post: tags: [Endpoint agent] summary: "Change monitoring batch: registry values, files, local groups, scheduled tasks (device credential)" description: > Body is a JSON object {changes: [...]} up to 256 KiB. The device id comes from the credential, never from the request. Answers 503 feature_disabled while the change_monitor sub-switch is off (the default) and 503 unavailable when the server is under load. Handled by rivet/rivet-core (DeviceApi::changes). security: [{deviceAuth: []}] requestBody: required: true content: application/json: schema: type: object required: [changes] properties: changes: {type: array, items: {type: object, additionalProperties: true}} responses: '200': {description: "Accepted ({ok: true, ...})", content: {application/json: {schema: {$ref: '#/components/schemas/Ok'}}}} '401': {description: "Credential invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '413': {description: "Body over 256 KiB", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '422': {description: "Invalid payload", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Rate limited (Retry-After header)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '503': {description: "feature_disabled (sub-switch off) or unavailable (load shedding)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /agent_logs: post: tags: [Endpoint agent] summary: "Event-log and syslog batch (device credential)" description: > Body is {entries: [{ts, source, level, event_id, message, ...}]} with at most 200 entries and 256 KiB. Entries over the limit or invalid are counted as dropped, repeats as duplicates. Answers 503 feature_disabled while the logs sub-switch is off and 503 unavailable under load (the first optional work given up). The device id comes from the credential. Handled by rivet/rivet-core (DeviceApi::logs). security: [{deviceAuth: []}] requestBody: required: true content: application/json: schema: type: object required: [entries] properties: entries: type: array maxItems: 200 items: type: object properties: ts: {type: string, format: date-time} source: {type: string} level: {type: string} event_id: {type: integer} message: {type: string} additionalProperties: true responses: '200': description: Accepted content: application/json: schema: type: object properties: ok: {type: boolean} accepted: {type: integer} dropped: {type: integer} duplicates: {type: integer} '401': {description: "Credential invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '413': {description: "Body over 256 KiB", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '422': {description: "Invalid payload", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Rate limited (Retry-After header)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '503': {description: "feature_disabled (sub-switch off) or unavailable (load shedding)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /agent_transfer: get: tags: [Endpoint agent] summary: "Download a file queued FOR the device, one range at a time (device credential + transfer token)" description: > The device may only move transfers of its own device id (taken from the credential). The one-time transfer token (only its SHA-256 is stored) goes in the X-Transfer-Token header. The response carries X-Transfer-Size and X-Transfer-Sha256 headers. 503 feature_disabled while the filetransfer sub-switch is off. Handled by rivet/rivet-core (DeviceApi::transfer). security: [{deviceAuth: []}] parameters: - {name: transfer_id, in: query, required: true, schema: {type: string}} - {name: offset, in: query, required: true, schema: {type: integer, minimum: 0}} - {name: length, in: query, required: true, schema: {type: integer, minimum: 1}} - {name: X-Transfer-Token, in: header, required: true, schema: {type: string}} responses: '200': description: The requested bytes headers: X-Transfer-Size: {schema: {type: integer}} X-Transfer-Sha256: {schema: {type: string}} content: application/octet-stream: schema: {type: string, format: binary} '401': {description: "Credential or transfer token invalid", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '404': {description: "Unknown transfer for this device", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Rate limited", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '503': {description: "feature_disabled or unavailable", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} post: tags: [Endpoint agent] summary: "Upload the next chunk of a file the device sends (device credential + transfer token)" description: > Raw body of at most 1 MiB. The final chunk carries X-Transfer-Last: 1 and X-Transfer-Sha256 of the whole file. Handled by rivet/rivet-core (DeviceApi::transfer). security: [{deviceAuth: []}] parameters: - {name: transfer_id, in: query, required: true, schema: {type: string}} - {name: offset, in: query, required: true, schema: {type: integer, minimum: 0}} - {name: X-Transfer-Token, in: header, required: true, schema: {type: string}} - {name: X-Transfer-Last, in: header, required: false, schema: {type: string, enum: ['1']}} - {name: X-Transfer-Sha256, in: header, required: false, schema: {type: string}, description: "Required on the final chunk"} requestBody: required: true content: application/octet-stream: schema: {type: string, format: binary} responses: '200': {description: "Chunk stored ({ok: true, ...})", content: {application/json: {schema: {$ref: '#/components/schemas/Ok'}}}} '401': {description: "Credential or transfer token invalid", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '404': {description: "Unknown transfer for this device", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '409': {description: "Offset does not match what the server holds", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '413': {description: "Chunk over 1 MiB", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Rate limited", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '503': {description: "feature_disabled or unavailable", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /agent_software/{job_id}/{secret}: get: tags: [Endpoint agent] summary: "Download the hosted installer of a queued or running software_install job (path secret is the credential)" description: > No bearer: the job id plus the per-job secret in the path IS the credential, valid for at most 24 hours while the job is queued or running. Every refusal (no such job, wrong secret, expired, finished, file gone or damaged, module or software_deploy off) is the same 404 not_found. Not part of the frozen device protocol. Handled by rivet/rivet-core (HostedFileApi). security: [] parameters: - {name: job_id, in: path, required: true, schema: {type: string}} - {name: secret, in: path, required: true, schema: {type: string}} responses: '200': description: The installer file content: application/octet-stream: schema: {type: string, format: binary} '404': {description: "not_found for every refusal", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /agent_linux_file: get: tags: [Endpoint agent] summary: "Download a Linux agent file this server hosts (install key)" description: > Also answers HEAD. The install key (rvdl1...) is sent in X-Install-Key or as an Authorization Bearer, never the enrollment token and never in the URL. It is derived from a still-valid enrollment token for ONE file at ONE version and does not use up an enrollment. A missing, malformed, wrong, expired or revoked key gets one answer, 401 invalid_key (the audit log records the reason). Failed attempts are rate limited per address. The file is checked against its recorded size and SHA-256 before it is served. security: [] parameters: - {name: name, in: query, required: true, schema: {type: string}, description: "install-linux.sh, rivetit-agent-linux-amd64, rivetit-agent-linux-arm64 or rivetit-agent-linux-.tar.gz"} - {name: version, in: query, required: true, schema: {type: string, example: 1.2.0}} - {name: X-Install-Key, in: header, required: false, schema: {type: string}} responses: '200': description: The file, with Content-Length, X-Content-SHA256 and ETag headers headers: X-Content-SHA256: {schema: {type: string}} content: application/octet-stream: schema: {type: string, format: binary} '401': {description: "invalid_key (one answer for every credential failure and for a malformed request)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '404': {description: "Credential fine, file not hosted (not_found)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '405': {description: "GET and HEAD only (code method)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Rate limited (Retry-After header)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '500': {description: "The hosted file no longer matches its recorded size or SHA-256 (code damaged)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '503': {description: "module_disabled or unavailable", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /build_host/{action}: post: tags: [Endpoint agent] summary: "Local agent build host protocol: poll, status, upload, complete (build host token)" description: > Authenticated ONLY by a build host token (Authorization Bearer rbh__) created under Administration > Endpoint agent > Agent updates > Local build; an API key never works here. JSON in, JSON out, pull model (the host only makes outbound requests). poll returns {job: null} or the next build job; status reports building, uploading or failed with optional progress fields (stage, pct, detail, elapsed_s); upload sends one chunk of at most 1 MiB raw as base64 with its SHA-256; complete sends the manifest, after which the server recomputes every hash, runs the existing PE, ELF and MSI validators and only then publishes. Rate limited per address and per host. Full protocol: rivet-core docs/rmm/BUILD_HOST_PROTOCOL.md. security: [{buildHostAuth: []}] parameters: - {name: action, in: path, required: true, schema: {type: string, enum: [poll, status, upload, complete]}} requestBody: required: true content: application/json: schema: type: object description: "poll {host_version, capabilities}; status {job_id, state, note, stage?, pct?, detail?, elapsed_s?}; upload {job_id, name, index, total, sha256_chunk, data_b64}; complete {job_id, manifest}" additionalProperties: true responses: '200': description: Result for the action (shape depends on the action) content: application/json: schema: {type: object, additionalProperties: true} '400': {description: "Body is not a JSON object, or a field is out of range (code invalid)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '401': {description: "Invalid or revoked token (code invalid_token)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '404': {description: "Unknown action (code not_found)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '405': {description: "POST only (code method)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '413': {description: "Request too large (code too_large)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Rate limited (Retry-After header)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '503': {description: "Local build not available (code unavailable)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /panel_enroll: post: tags: [RivetPanel] summary: Exchange a panel enrollment token for a per-device credential (no bearer) description: > The enrollment token (rvtp1..) was minted by an administrator for a client and optionally a contact; it travels in the body. The same install_id enrolling again keeps the device and rotates the credential. An RMM token (rvte1.) is not accepted. Failures are limited per address (429 + Retry-After). The server derives the client and contact from the credential and ignores any client_id or contact_id a caller sends. TLS required. Every JSON answer carries server_time. Full contract: rivet-core docs/panel/PANEL_API.md and openapi-panel.yaml. security: [] requestBody: required: true content: application/json: schema: type: object required: [enrollment_token, device] properties: enrollment_token: {type: string, example: "rvtp1.0123456789ab.0123456789abcdef0123456789abcdef01234567"} device: type: object required: [install_id, hostname, os] properties: install_id: {type: string, format: uuid} hostname: {type: string, maxLength: 200} os: {type: string, enum: [windows, linux, macos]} os_version: {type: string, maxLength: 200} app_version: {type: string, maxLength: 40} responses: '201': description: Enrolled. device_token (rvpd_ plus 64 hex) is shown once. content: application/json: schema: {$ref: '#/components/schemas/PanelEnrollResponse'} '401': {description: "invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '403': {description: "Token used up or device revoked (forbidden), or the contact is gone (contact_invalid)", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '405': {description: "Wrong method (method_not_allowed)", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '409': {description: "install_id belongs to an RMM agent or another client (conflict)", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '413': {description: "too_large", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '422': {description: "invalid", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '426': {description: "Plain HTTP (tls_required)", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '429': {description: "rate_limited (Retry-After header)", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '503': {description: "Panel service off (module_disabled)", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} /panel_me: get: tags: [RivetPanel] summary: Who this panel device is and what it may do security: [{panelAuth: []}] responses: '200': description: The device's client, contact (or null), capabilities and limits content: application/json: schema: {$ref: '#/components/schemas/PanelMe'} '401': {description: "invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '403': {description: "contact_invalid or client_invalid", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '426': {description: "tls_required", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '429': {description: "rate_limited", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '503': {description: "module_disabled", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} /panel_categories: get: tags: [RivetPanel] summary: The ticket categories of the device's client description: Available to every panel device, including a client-level device whose client has not allowed tickets. At most 120 per 60 s per device. security: [{panelAuth: []}] responses: '200': description: Categories content: application/json: schema: type: object properties: categories: type: array items: type: object properties: category_id: {type: integer} name: {type: string} server_time: {type: string, format: date-time} '401': {description: "invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '403': {description: "contact_invalid or client_invalid", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '429': {description: "rate_limited", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '503': {description: "module_disabled", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} /panel_tickets: get: tags: [RivetPanel] summary: List this panel device's tickets description: > A device with a contact lists that contact's tickets plus the ones its own device created; a client-level device lists only the ones it created, always inside its own client. 403 client_level_disabled for a client-level device while the client's setting is off. At most 120 per 60 s per device. security: [{panelAuth: []}] parameters: - {name: limit, in: query, required: false, schema: {type: integer, minimum: 1, maximum: 50, default: 20}} - {name: offset, in: query, required: false, schema: {type: integer, minimum: 0, default: 0}} responses: '200': description: A page of tickets, newest activity first content: application/json: schema: type: object properties: tickets: type: array items: type: object properties: ticket_id: {type: integer} subject: {type: string} status: {type: string} closed: {type: boolean} category_id: {type: integer, nullable: true} created_at: {type: string, format: date-time} updated_at: {type: string, format: date-time} mine: {type: boolean, description: "Created by this device"} limit: {type: integer} offset: {type: integer} has_more: {type: boolean} server_time: {type: string, format: date-time} '401': {description: "invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '403': {description: "client_level_disabled, contact_invalid or client_invalid", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '422': {description: "invalid", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '429': {description: "rate_limited", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '503': {description: "module_disabled", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} post: tags: [RivetPanel] summary: Create a ticket from the panel description: > Filed under the client and contact of the credential; client_id, contact_id and unknown fields are ignored. A client-level device may create only while the client's setting is on. client_request_id makes a retry safe: a replay of a finished request returns the first ticket (200, replayed true); while the first is still running it is 409 request_in_progress (Retry-After 2). At most 10 per 60 s and 50 per day per device. security: [{panelAuth: []}] requestBody: required: true content: application/json: schema: type: object required: [subject, body] properties: subject: {type: string, minLength: 1, maxLength: 200} body: {type: string, minLength: 1, maxLength: 20000} category_id: {type: integer, nullable: true} display_name: {type: string, maxLength: 100, description: "OS user name shown as 'reported as'; never an identity"} client_request_id: {type: string, format: uuid} attachments: {type: array, maxItems: 3, items: {$ref: '#/components/schemas/PanelAttachment'}} responses: '201': description: Created content: application/json: schema: {$ref: '#/components/schemas/PanelTicketCreated'} '200': description: Replay of an earlier request with the same client_request_id content: application/json: schema: {$ref: '#/components/schemas/PanelTicketCreated'} '401': {description: "invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '403': {description: "client_level_disabled, contact_invalid or client_invalid", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '409': {description: "request_in_progress (Retry-After header)", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '413': {description: "too_large", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '422': {description: "invalid, or attachment_rejected", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '429': {description: "rate_limited", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '503': {description: "module_disabled", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} /panel_ticket_chat: get: tags: [RivetPanel] summary: Read the conversation of one of this device's tickets description: > Only tickets this device created or, for a device with a contact, tickets of that contact. Any other ticket, and one that does not exist, is the same 404 not_found. Internal notes are never returned. Poll with after set to the previous next_after. security: [{panelAuth: []}] parameters: - {name: ticket_id, in: query, required: true, schema: {type: integer, minimum: 1}} - {name: after, in: query, required: false, schema: {type: integer, minimum: 0, default: 0}} - {name: limit, in: query, required: false, schema: {type: integer, minimum: 1, maximum: 100, default: 50}} responses: '200': description: Messages after the cursor, oldest first content: application/json: schema: type: object properties: ticket: type: object properties: ticket_id: {type: integer} subject: {type: string} status: {type: string} closed: {type: boolean} messages: type: array items: type: object properties: message_id: {type: integer} from: {type: string, enum: [you, staff]} author: {type: string} body: {type: string} created_at: {type: string, format: date-time} attachments: type: array items: type: object properties: filename: {type: string} content_type: {type: string} size: {type: integer} next_after: {type: integer} server_time: {type: string, format: date-time} '401': {description: "invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '403': {description: "client_level_disabled, contact_invalid or client_invalid", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '404': {description: "not_found (missing and out of scope are indistinguishable)", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '422': {description: "invalid", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '429': {description: "rate_limited", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '503': {description: "module_disabled", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} post: tags: [RivetPanel] summary: Post a message on one of this device's tickets description: Same access rule as reading. A closed ticket answers 409 ticket_closed. At most 20 per 60 s per device. security: [{panelAuth: []}] parameters: - {name: ticket_id, in: query, required: true, schema: {type: integer, minimum: 1}} requestBody: required: true content: application/json: schema: type: object required: [body] properties: body: {type: string, minLength: 1, maxLength: 5000} display_name: {type: string, maxLength: 100} attachments: {type: array, maxItems: 3, items: {$ref: '#/components/schemas/PanelAttachment'}} responses: '201': description: Posted content: application/json: schema: type: object properties: ticket_id: {type: integer} message_id: {type: integer} server_time: {type: string, format: date-time} '401': {description: "invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '403': {description: "client_level_disabled, contact_invalid or client_invalid", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '404': {description: "not_found", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '409': {description: "ticket_closed", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '413': {description: "too_large", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '422': {description: "invalid, or attachment_rejected", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '429': {description: "rate_limited", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} '503': {description: "module_disabled", content: {application/json: {schema: {$ref: '#/components/schemas/PanelError'}}}} /endpoint_devices: get: tags: [Endpoint agent] summary: List endpoint agent devices in the caller's departments description: Needs a user token and RMM (module_rmm) view access. Module-only logins and API keys get 403. parameters: - {name: limit, in: query, schema: {type: integer, maximum: 200}} - {name: offset, in: query, schema: {type: integer}} - {name: status, in: query, schema: {type: string}} responses: '200': description: Devices content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/EndpointDevice'}} total: {type: integer} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} /endpoint_devices/{id}: get: tags: [Endpoint agent] summary: Device detail with inventory, checks and recent jobs description: A device outside the caller's departments is a 404 (indistinguishable from a missing one). Job output needs module_rmm_scripts level 2. parameters: - {name: id, in: path, required: true, schema: {type: integer}} responses: '200': {description: "Device", content: {application/json: {schema: {$ref: '#/components/schemas/EndpointDevice'}}}} '401': {$ref: '#/components/responses/Unauthorized'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} /endpoint_devices/{id}/jobs: get: tags: [Endpoint agent] summary: Job history for a device parameters: - {name: id, in: path, required: true, schema: {type: integer}} responses: '200': {description: "Jobs", content: {application/json: {schema: {type: object, properties: {data: {type: array, items: {type: object}}}}}}} '404': {$ref: '#/components/responses/NotFound'} post: tags: [Endpoint agent] summary: Queue a maintenance job (PowerShell, saved script, collect, reboot) description: > Authorization is decided server-side per call: free-form PowerShell needs module_rmm_scripts level 3, a saved script, reboot or collect level 2, always with module_rmm view access and the device's department. Module-only logins are refused. A reboot or any destructive job needs "confirm": true and is never retried automatically. parameters: - {name: id, in: path, required: true, schema: {type: integer}} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/EndpointJobRequest'} responses: '201': {description: "Queued", content: {application/json: {schema: {type: object, properties: {job_id: {type: string}, state: {type: string}}}}}} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} '422': {description: "Invalid or confirmation_required", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /endpoint_devices/{id}/jobs/{job_id}/cancel: post: tags: [Endpoint agent] summary: Cancel a queued job parameters: - {name: id, in: path, required: true, schema: {type: integer}} - {name: job_id, in: path, required: true, schema: {type: string}} responses: '200': {$ref: '#/components/responses/Ok'} '403': {$ref: '#/components/responses/Forbidden'} '404': {$ref: '#/components/responses/NotFound'} '409': {description: "Only a queued job can be cancelled", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /endpoint_devices/{id}/remote: post: tags: [Endpoint agent] summary: Launch a MeshCentral remote session for a device description: > Needs module_rmm_remote_connect, module_rmm view, the device's department, and a device mapped to a MeshCentral node. Returns a one-time login URL minted for this request (never stored or logged) and a safe session id. Unmapped is 404, offline/not configured/retired 409 (set force to launch an offline-looking device anyway), MeshCentral unreachable 503. parameters: - {name: id, in: path, required: true, schema: {type: integer}} requestBody: required: false content: application/json: schema: {type: object, properties: {force: {type: boolean}}} responses: '200': {description: "Launch URL", content: {application/json: {schema: {type: object, properties: {url: {type: string}, session_id: {type: string}}}}}} '403': {$ref: '#/components/responses/Forbidden'} '404': {description: "Not found, or code unmapped", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '409': {description: "device_offline, not_configured or device_retired", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '503': {description: "MeshCentral unavailable", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /oauth/token: post: tags: [Integration] summary: OAuth2 client-credentials token for an integration client description: > Public (no Bearer). `application/x-www-form-urlencoded` with `grant_type=client_credentials`, `client_id` and `client_secret` (or HTTP Basic). Optional `scope` (space separated; must be a subset of the client's scopes, default all of them). Returns a signed access token valid for 10 minutes that is accepted ONLY on `/lms/*`, `/employees/*` and `/departments/*`. Every authentication failure is the same 401 `invalid_client`; repeated failures per IP and per client are throttled (429). Clients are managed in Administration > API Keys. security: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: [grant_type, client_id, client_secret] properties: grant_type: {type: string, enum: [client_credentials]} client_id: {type: string, example: ic_0123456789abcdef0123} client_secret: {type: string, format: password} scope: {type: string, example: "lms:read lms:completions:read"} responses: '200': description: Access token content: application/json: schema: {$ref: '#/components/schemas/IntegrationToken'} '400': {description: "invalid_request, unsupported_grant_type or invalid_scope", content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationError'}}}} '401': {description: "invalid_client", content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationError'}}}} '429': {description: "rate_limited (Retry-After)", content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationError'}}}} /lms/courses: get: tags: [Integration] summary: Published course catalog description: Scope `lms:read`. Published, non-archived courses only; each is its latest published revision. Limited to the client's department scope (all departments, or only courses linked to its departments by a live rule, a rule naming one of its people, or an assignment or completion of one of its people); `departments` and `requirements` list only what touches the allowed departments. Cursor paging, incremental sync with `updated_since`. security: [{integrationAuth: []}] parameters: - {$ref: '#/components/parameters/IntLimit'} - {$ref: '#/components/parameters/IntCursor'} - {$ref: '#/components/parameters/IntUpdatedSince'} responses: '200': {description: Courses, content: {application/json: {schema: {$ref: '#/components/schemas/LmsCoursePage'}}}} '400': {$ref: '#/components/responses/IntegrationBadRequest'} '401': {$ref: '#/components/responses/IntegrationUnauthorized'} '403': {$ref: '#/components/responses/IntegrationForbidden'} /lms/courses/{id}: get: tags: [Integration] summary: One published course description: Scope `lms:read`. `id` is the course id from the list (12 characters). Unpublished, archived, unknown and out-of-department-scope ids are all the same 404. security: [{integrationAuth: []}] parameters: - {name: id, in: path, required: true, schema: {type: string}} responses: '200': {description: Course, content: {application/json: {schema: {type: object, properties: {data: {$ref: '#/components/schemas/LmsCourse'}}}}}} '401': {$ref: '#/components/responses/IntegrationUnauthorized'} '403': {$ref: '#/components/responses/IntegrationForbidden'} '404': {$ref: '#/components/responses/IntegrationNotFound'} /lms/assignments: get: tags: [Integration] summary: List assignments description: Scope `lms:read`. Only assignments of people in the client's department scope. Filters `employee` (RivetIT id), `odoo_employee_id`, `course`, `status` (open, completed, waived, cancelled), `external_system`, `external_ref`, `updated_since`. security: [{integrationAuth: []}] parameters: - {$ref: '#/components/parameters/IntLimit'} - {$ref: '#/components/parameters/IntCursor'} - {$ref: '#/components/parameters/IntUpdatedSince'} - {name: employee, in: query, schema: {type: string}} - {name: odoo_employee_id, in: query, schema: {type: string}} - {name: course, in: query, schema: {type: string}} - {name: status, in: query, schema: {type: string, enum: [open, completed, waived, cancelled]}} - {name: external_system, in: query, schema: {type: string}} - {name: external_ref, in: query, schema: {type: string}} responses: '200': {description: Assignments, content: {application/json: {schema: {$ref: '#/components/schemas/LmsAssignmentPage'}}}} '400': {$ref: '#/components/responses/IntegrationBadRequest'} '401': {$ref: '#/components/responses/IntegrationUnauthorized'} '403': {$ref: '#/components/responses/IntegrationForbidden'} post: tags: [Integration] summary: Create (or reuse) an assignment description: > Scope `lms:assign`. `Idempotency-Key` is required: the same key with the same body replays the stored response (header `Idempotent-Replay: true`), the same key with a different body is 422 `idempotency_key_reuse`; keys are kept 24 hours and only successful results are stored. The employee is identified by `odoo_employee_id` or `rivetit_id` (never by name). The course must have a published revision. Created through the assignment engine, so the training ledger stays valid. 201 when a new assignment was created, 200 when an open assignment for the employee and course (or the same external reference) already existed. The employee and the course must be inside the client's department scope; outside it the answer is exactly the one for an unknown employee or course (422 `employee_not_found` / `course_not_found`), and an external_ref held outside the scope is the same 409 `external_ref_conflict`. security: [{integrationAuth: []}] parameters: - {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 8, maxLength: 128}} requestBody: required: true content: application/json: schema: {$ref: '#/components/schemas/LmsAssignmentCreate'} responses: '200': {description: Existing assignment reused (or idempotent replay of a 200), content: {application/json: {schema: {$ref: '#/components/schemas/LmsAssignmentResult'}}}} '201': {description: Assignment created, content: {application/json: {schema: {$ref: '#/components/schemas/LmsAssignmentResult'}}}} '400': {$ref: '#/components/responses/IntegrationBadRequest'} '401': {$ref: '#/components/responses/IntegrationUnauthorized'} '403': {$ref: '#/components/responses/IntegrationForbidden'} '409': {description: "external_ref_conflict, assignment_waived, already_current or idempotency_in_progress", content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationError'}}}} '422': {description: "Validation: invalid_employee, employee_not_found, employee_ambiguous, employee_mismatch, employee_not_eligible, course_not_found, course_not_published, invalid_due_on, due_on_in_past, idempotency_key_reuse, ...", content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationError'}}}} /lms/assignments/{id}: get: tags: [Integration] summary: One assignment description: Scope `lms:read`. `id` looks like `asg_123`. An assignment of a person outside the client's department scope is the same 404 as an unknown id. security: [{integrationAuth: []}] parameters: - {name: id, in: path, required: true, schema: {type: string, example: asg_123}} responses: '200': {description: Assignment, content: {application/json: {schema: {type: object, properties: {data: {$ref: '#/components/schemas/LmsAssignment'}}}}}} '401': {$ref: '#/components/responses/IntegrationUnauthorized'} '403': {$ref: '#/components/responses/IntegrationForbidden'} '404': {$ref: '#/components/responses/IntegrationNotFound'} /lms/completions: get: tags: [Integration] summary: List completions description: > Scope `lms:completions:read`. Completion records are never deleted; a corrected record is `voided` or `superseded` and stays listed. Filters `employee`, `odoo_employee_id`, `course`, `assignment`, `status` (completed, voided, superseded), `updated_since`. security: [{integrationAuth: []}] parameters: - {$ref: '#/components/parameters/IntLimit'} - {$ref: '#/components/parameters/IntCursor'} - {$ref: '#/components/parameters/IntUpdatedSince'} - {name: employee, in: query, schema: {type: string}} - {name: odoo_employee_id, in: query, schema: {type: string}} - {name: course, in: query, schema: {type: string}} - {name: assignment, in: query, schema: {type: string, example: asg_123}} - {name: status, in: query, schema: {type: string, enum: [completed, voided, superseded]}} responses: '200': {description: Completions, content: {application/json: {schema: {$ref: '#/components/schemas/LmsCompletionPage'}}}} '400': {$ref: '#/components/responses/IntegrationBadRequest'} '401': {$ref: '#/components/responses/IntegrationUnauthorized'} '403': {$ref: '#/components/responses/IntegrationForbidden'} /lms/completions/{id}: get: tags: [Integration] summary: One completion description: Scope `lms:completions:read`. `id` looks like `cmp_123`. A completion of a person outside the client's department scope is the same 404 as an unknown id. security: [{integrationAuth: []}] parameters: - {name: id, in: path, required: true, schema: {type: string, example: cmp_123}} responses: '200': {description: Completion, content: {application/json: {schema: {type: object, properties: {data: {$ref: '#/components/schemas/LmsCompletion'}}}}}} '401': {$ref: '#/components/responses/IntegrationUnauthorized'} '403': {$ref: '#/components/responses/IntegrationForbidden'} '404': {$ref: '#/components/responses/IntegrationNotFound'} /lms/completions/{id}/evidence: get: tags: [Integration] summary: The completion's evidence file description: Scope `lms:evidence:read`. Streamed through the API after the same visibility check the web endpoint applies (the file must be referenced by the completion). 404 when there is no file or it may not be served. security: [{integrationAuth: []}] parameters: - {name: id, in: path, required: true, schema: {type: string, example: cmp_123}} responses: '200': description: The file (PDF, JPEG or PNG), as an attachment content: application/pdf: {schema: {type: string, format: binary}} image/jpeg: {schema: {type: string, format: binary}} image/png: {schema: {type: string, format: binary}} '401': {$ref: '#/components/responses/IntegrationUnauthorized'} '403': {$ref: '#/components/responses/IntegrationForbidden'} '404': {$ref: '#/components/responses/IntegrationNotFound'} /employees: get: tags: [Integration] summary: Employee directory description: | Scope `directory:read` only (no `lms:*` scope grants it). Employees are RivetIT contacts; the identity key for the QMS is `odoo_employee_id` (from the Odoo directory link; null when the person is not linked). Deactivated people stay in the feed with `active: false` (terminated or archived) so the QMS can deprovision them. Limited to the client's department scope: a restricted client sees only the employees of its departments; `manager_id` is null when the manager is outside that scope. Ascending id, cursor paging, incremental sync with `updated_since`. Only name, work email and job title are exposed - no phone, PIN, address or notes. security: [{integrationAuth: []}] parameters: - {$ref: '#/components/parameters/IntLimit'} - {$ref: '#/components/parameters/IntCursor'} - {$ref: '#/components/parameters/IntUpdatedSince'} - {name: department_id, in: query, schema: {type: string}, description: "Only the employees of this department (RivetIT id)"} - {name: odoo_employee_id, in: query, schema: {type: string}} responses: '200': {description: Employees, content: {application/json: {schema: {$ref: '#/components/schemas/DirectoryEmployeePage'}}}} '400': {$ref: '#/components/responses/IntegrationBadRequest'} '401': {$ref: '#/components/responses/IntegrationUnauthorized'} '403': {$ref: '#/components/responses/IntegrationForbidden'} /employees/{id}: get: tags: [Integration] summary: One employee description: Scope `directory:read`. `id` is the RivetIT id from the list. Unknown, malformed and out-of-department-scope ids are all the same 404. A deactivated employee is returned with active set to false. security: [{integrationAuth: []}] parameters: - {name: id, in: path, required: true, schema: {type: string, example: "123"}} responses: '200': {description: Employee, content: {application/json: {schema: {type: object, properties: {data: {$ref: '#/components/schemas/DirectoryEmployee'}}}}}} '401': {$ref: '#/components/responses/IntegrationUnauthorized'} '403': {$ref: '#/components/responses/IntegrationForbidden'} '404': {$ref: '#/components/responses/IntegrationNotFound'} /departments: get: tags: [Integration] summary: Department directory description: | Scope `directory:read` only. Departments are RivetIT clients (CRM leads are not departments). Archived and inactive departments stay in the feed (`active: false`). Limited to the client's department scope; `parent_id` and `head_employee_id` are null when they point outside it. Ascending id, cursor paging, incremental sync with `updated_since`. security: [{integrationAuth: []}] parameters: - {$ref: '#/components/parameters/IntLimit'} - {$ref: '#/components/parameters/IntCursor'} - {$ref: '#/components/parameters/IntUpdatedSince'} responses: '200': {description: Departments, content: {application/json: {schema: {$ref: '#/components/schemas/DirectoryDepartmentPage'}}}} '400': {$ref: '#/components/responses/IntegrationBadRequest'} '401': {$ref: '#/components/responses/IntegrationUnauthorized'} '403': {$ref: '#/components/responses/IntegrationForbidden'} /departments/{id}: get: tags: [Integration] summary: One department description: Scope `directory:read`. Unknown, malformed and out-of-department-scope ids are all the same 404. security: [{integrationAuth: []}] parameters: - {name: id, in: path, required: true, schema: {type: string, example: "7"}} responses: '200': {description: Department, content: {application/json: {schema: {type: object, properties: {data: {$ref: '#/components/schemas/DirectoryDepartment'}}}}}} '401': {$ref: '#/components/responses/IntegrationUnauthorized'} '403': {$ref: '#/components/responses/IntegrationForbidden'} '404': {$ref: '#/components/responses/IntegrationNotFound'} /integrations/qms/events: post: tags: [Integration] summary: Signed event from the QMS description: | Scope `quality:events`. Served only while the Quality module and "Accept events from the QMS" are on (otherwise `503 module_disabled`). The request must ALSO carry `X-Rivet-Signature-V2: t=,v1=." with the inbound signing secret>`; the timestamp must be within 5 minutes (and not more than 1 minute ahead). The body is a JSON object of at most 64 KiB with `id` (8 to 64 characters, unique per event), `type`, `schema_version` (1), `occurred_at` and `data`. A repeat of an event id with the same body is acknowledged as `duplicate` and not processed again; the same id with a different body is `409 event_id_reuse`. Types: `qms.employee.mapped` (`qms_id` plus `rivetit_id` or `odoo_employee_id`; never matched by name), `qms.department.mapped` (`qms_id`, `rivetit_id`), `qms.sync.requested` (`streams`), `qms.requirement.changed` (`external_ref`); an unknown type is recorded as `ignored`. security: [{integrationAuth: []}] requestBody: required: true content: application/json: schema: type: object required: [id, type, schema_version, occurred_at, data] properties: id: {type: string, example: "0f8a3c52-6b1e-4d27-9a64-3d1f0c9e7b21"} type: {type: string, example: qms.employee.mapped} schema_version: {type: integer, example: 1} occurred_at: {type: string, example: "2026-11-01T14:03:22Z"} data: {type: object, example: {qms_id: "p-2291", odoo_employee_id: "1842"}} parameters: - {name: X-Rivet-Signature-V2, in: header, required: true, schema: {type: string, example: "t=1793500000,v1=eb6c6837bb9f51d8a510764647b54f5b154e6457a0876faad02f7dec3bc7dabe"}} responses: '200': {description: Accepted, content: {application/json: {schema: {type: object, properties: {status: {type: string, enum: [processed, ignored, duplicate]}, id: {type: string}}}}}} '400': {$ref: '#/components/responses/IntegrationBadRequest'} '401': {$ref: '#/components/responses/IntegrationUnauthorized'} '403': {$ref: '#/components/responses/IntegrationForbidden'} '409': {description: The event id was already used with a different body} '413': {description: Body larger than 64 KiB} '415': {description: Send application/json} '422': {description: Unsupported schema_version, or the event could not be applied (unknown or ambiguous person or department)} '503': {description: The Quality module (or inbound events) is switched off} /portal_auth: post: tags: [Employee portal] summary: Employee sign-in (department portal login) description: > Signs in a department-portal login (local password, same rules as the web portal sign-in: active, not archived, contact and department not archived, portal switched on, 2FA honoured). Returns a token for the /portal_* endpoints only; it is not a staff token and staff tokens do not work there. Five failures lock the login for five minutes. Single sign-on accounts cannot use this. A login that needs 2FA answers `{requires_2fa: true}` until `totp_code` is sent; an account that must enrol in 2FA gets 403 (set it up in the web portal). security: [] requestBody: required: true content: application/json: schema: type: object required: [username, password] properties: username: {type: string, description: The portal login email} password: {type: string} totp_code: {type: string} device_name: {type: string} responses: '200': description: Signed in (token) or 2FA needed content: application/json: schema: type: object properties: token: {type: string} requires_2fa: {type: boolean} contact: {type: object, properties: {id: {type: integer}, name: {type: string}, department_id: {type: integer}}} '400': {description: username and password required} '401': {description: Invalid credentials or 2FA code} '403': {description: 2FA enrolment required} '429': {description: Too many attempts} delete: tags: [Employee portal] summary: Sign this device out (revokes the employee token) security: [{portalBearer: []}] responses: '200': {description: Signed out} /portal_home: get: tags: [Employee portal] summary: The employee home in one call description: Announcements, open requests, devices, approvals waiting (count), checklist, popular and recent help articles and the unread notification count. Scoped to the token's contact and department. security: [{portalBearer: []}] responses: '200': {description: Employee home, content: {application/json: {schema: {$ref: '#/components/schemas/PortalHome'}}}} '401': {$ref: '#/components/responses/Unauthorized'} /portal_devices: get: tags: [Employee portal] summary: My devices description: Devices assigned to the employee with OS, status, warranty (date, days left, state), last seen (agent check-in or RMM link) and restart pending. No credentials, IPs or notes. security: [{portalBearer: []}] responses: '200': {description: Devices, content: {application/json: {schema: {type: object, properties: {devices: {type: array, items: {$ref: '#/components/schemas/PortalDevice'}}}}}}} '401': {$ref: '#/components/responses/Unauthorized'} /portal_devices/{id}: get: tags: [Employee portal] summary: One of my devices security: [{portalBearer: []}] parameters: - {name: id, in: path, required: true, schema: {type: integer}} responses: '200': {description: Device, content: {application/json: {schema: {type: object, properties: {device: {$ref: '#/components/schemas/PortalDevice'}}}}}} '401': {$ref: '#/components/responses/Unauthorized'} '404': {description: Not assigned to the caller (or no such asset)} /portal_checklist: get: tags: [Employee portal] summary: My onboarding / offboarding checklist description: Read-only; no instructions, automation settings or errors, and automated (action) tasks are left out. `checklist` is null when the employee has none. security: [{portalBearer: []}] responses: '200': description: Checklist content: application/json: schema: type: object properties: checklist: nullable: true type: object properties: type: {type: string, enum: [onboarding, offboarding]} status: {type: string} template: {type: string} done: {type: integer} total: {type: integer} tasks: type: array items: type: object properties: id: {type: integer} title: {type: string} owner: {type: string} state: {type: string, enum: [todo, not_started, awaiting_approval, done]} required: {type: boolean} due_at: {type: string, nullable: true} '401': {$ref: '#/components/responses/Unauthorized'} /portal_announcements: get: tags: [Employee portal] summary: Announcements for the employee description: Published, not expired, for all departments or the caller's own department. Plain text body. security: [{portalBearer: []}] responses: '200': {description: Announcements, content: {application/json: {schema: {type: object, properties: {announcements: {type: array, items: {$ref: '#/components/schemas/PortalAnnouncement'}}}}}}} '401': {$ref: '#/components/responses/Unauthorized'} /portal_notifications: get: tags: [Employee portal] summary: My notification feed description: Announcements, replies and closures on the employee's requests, approvals waiting, due checklist tasks and device warranties running out. Built from existing data; nothing is sent. security: [{portalBearer: []}] responses: '200': description: Feed content: application/json: schema: type: object properties: unread: {type: integer} items: type: array items: type: object properties: key: {type: string} type: {type: string, enum: [announcement, reply, closed, approval, task, warranty]} title: {type: string} detail: {type: string} link: {type: string} at: {type: string} sticky: {type: boolean} unread: {type: boolean} severity: {type: string, enum: [info, important, urgent]} '401': {$ref: '#/components/responses/Unauthorized'} post: tags: [Employee portal] summary: Mark the feed as read description: Sticky items (an approval waiting, a due task, a warranty ending) stay unread until dealt with. security: [{portalBearer: []}] requestBody: required: true content: application/json: schema: {type: object, required: [action], properties: {action: {type: string, enum: [mark_read]}}} responses: '200': {description: Marked, content: {application/json: {schema: {type: object, properties: {ok: {type: boolean}, unread: {type: integer}}}}}} '422': {description: Unknown action} components: securitySchemes: portalBearer: type: http scheme: bearer description: Employee token from POST /portal_auth (a department-portal login). Works only on the /portal_* endpoints. integrationClient: type: oauth2 description: > 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 `scope` parameter). Deny by default, no wildcard; the client's department scope applies. flows: clientCredentials: tokenUrl: /api/v1/oauth/token scopes: lms:read: Read the published course catalog and assignments lms:assign: Create (or reuse) training assignments lms:completions:read: Read training completions lms:evidence:read: Download completion evidence files directory:read: Read the employee and department directory quality:events: Send signed Quality events from the QMS (POST /integrations/qms/events) api:alerts:read: Read alerts api:alerts:write: Write alerts api:alerts:delete: Delete alerts api:appointments:read: Read appointments api:appointments:write: Write appointments api:appointments:delete: Delete appointments api:assets:read: Read assets api:assets:write: Write assets api:assets:delete: Delete assets api:clients:read: Read clients api:clients:write: Write clients api:clients:delete: Delete clients api:contacts:read: Read contacts api:contacts:write: Write contacts api:contacts:delete: Delete contacts api:contracts:read: Read contracts api:contracts:write: Write contracts api:contracts:delete: Delete contracts api:dashboard:read: Read dashboard api:dashboard:write: Write dashboard api:dashboard:delete: Delete dashboard api:kb:read: Read kb api:kb:write: Write kb api:kb:delete: Delete kb api:milestones:read: Read milestones api:milestones:write: Write milestones api:milestones:delete: Delete milestones api:outtakes:read: Read outtakes api:outtakes:write: Write outtakes api:outtakes:delete: Delete outtakes api:projects:read: Read projects api:projects:write: Write projects api:projects:delete: Delete projects api:relationships:read: Read relationships api:relationships:write: Write relationships api:relationships:delete: Delete relationships api:reports:read: Read reports api:reports:write: Write reports api:reports:delete: Delete reports api:search:read: Read search api:search:write: Write search api:search:delete: Delete search api:tasks:read: Read tasks api:tasks:write: Write tasks api:tasks:delete: Delete tasks api:ticket_attachments:read: Read ticket attachments api:ticket_attachments:write: Write ticket attachments api:ticket_attachments:delete: Delete ticket attachments api:ticket_categories:read: Read ticket categories api:ticket_categories:write: Write ticket categories api:ticket_categories:delete: Delete ticket categories api:ticket_views:read: Read ticket views api:ticket_views:write: Write ticket views api:ticket_views:delete: Delete ticket views api:tickets:read: Read tickets api:tickets:write: Write tickets api:tickets:delete: Delete tickets api:worksheets:read: Read worksheets api:worksheets:write: Write worksheets api:worksheets:delete: Delete worksheets integrationAuth: type: http scheme: bearer bearerFormat: JWT description: 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::read|write|delete); a route with no scope answers 403. bearerAuth: type: http scheme: bearer description: User session token issued by POST /api/v1/auth (a signed-in person, e.g. the mobile app). Not an integration credential. deviceAuth: type: http scheme: bearer description: Per-device credential issued by POST /agent_enroll (256-bit, only its SHA-256 stored, rotatable and revocable). Not a user token. panelAuth: type: http scheme: bearer description: Per-device RivetPanel credential issued by POST /panel_enroll (rvpd_ plus 64 hex, only its SHA-256 stored, revocable and rotatable). Not an RMM agent credential and not a user token. buildHostAuth: type: http scheme: bearer description: Build host token (rbh__) created under Administration > Endpoint agent > Agent updates > Local build. Grants access to /build_host/* only. parameters: IntLimit: name: limit in: query schema: {type: integer, default: 50, minimum: 1, maximum: 200} IntCursor: name: cursor in: query description: Opaque `next_cursor` from the previous page schema: {type: string} IntUpdatedSince: name: updated_since in: query description: RFC 3339 timestamp; only records changed at or after it schema: {type: string, format: date-time} IdPath: name: id in: path required: true schema: {type: integer} PageParam: name: page in: query schema: {type: integer, default: 1, minimum: 1} LimitParam: name: limit in: query schema: {type: integer, default: 20} SearchParam: name: search in: query schema: {type: string} YearParam: name: year in: query schema: {type: integer} responses: Ok: description: Success content: application/json: schema: {$ref: '#/components/schemas/Ok'} ReportObject: description: Report payload (shape varies by report; always a JSON object) content: application/json: schema: {type: object} BadRequest: description: Bad request content: application/json: schema: {$ref: '#/components/schemas/Error'} Unauthorized: description: Missing or invalid credentials content: application/json: schema: {$ref: '#/components/schemas/Error'} Forbidden: description: Authenticated but not permitted content: application/json: schema: {$ref: '#/components/schemas/Error'} NotFound: description: Resource not found content: application/json: schema: {$ref: '#/components/schemas/Error'} MethodNotAllowed: description: HTTP method not allowed for this resource content: application/json: schema: {$ref: '#/components/schemas/Error'} RateLimited: description: Rate limit exceeded (see Retry-After header) content: application/json: schema: {$ref: '#/components/schemas/Error'} IntegrationBadRequest: description: invalid_limit, invalid_cursor, invalid_updated_since, invalid_department_id, invalid_odoo_employee_id, invalid_status, invalid_json, idempotency_key_required or idempotency_key_invalid content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationError'}}} IntegrationUnauthorized: description: invalid_token (missing, expired, revoked, wrong audience, bad signature) or unauthorized content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationError'}}} IntegrationForbidden: description: insufficient_scope (the token does not carry the scope the route needs) content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationError'}}} IntegrationNotFound: description: not_found (unknown, unpublished or not servable; the two are not distinguished) content: {application/json: {schema: {$ref: '#/components/schemas/IntegrationError'}}} schemas: PanelError: type: object required: [error, code] properties: error: {type: string} code: {type: string, description: "invalid_token, revoked, expired, forbidden, contact_invalid, client_invalid, client_level_disabled, not_found, invalid, attachment_rejected, too_large, rate_limited, method_not_allowed, tls_required, conflict, ticket_closed, request_in_progress, module_disabled, internal"} server_time: {type: string, format: date-time} PanelAttachment: type: object required: [filename, content_type, data_base64] properties: filename: {type: string, description: "Reduced to a safe basename; needs an allowed extension"} content_type: {type: string, description: "Must be the type the extension maps to"} data_base64: {type: string} PanelTicketCreated: type: object properties: ticket_id: {type: integer} replayed: {type: boolean} server_time: {type: string, format: date-time} PanelLimits: type: object properties: subject_max: {type: integer} ticket_body_max: {type: integer} chat_body_max: {type: integer} attachments_max: {type: integer} attachment_bytes_max: {type: integer} attachments_total_max: {type: integer} attachment_extensions: {type: array, items: {type: string}} PanelMe: type: object properties: device_id: {type: integer} client: {type: object, properties: {client_id: {type: integer}, name: {type: string}}} contact: {type: object, nullable: true, properties: {contact_id: {type: integer}, name: {type: string}}} can_create_tickets: {type: boolean} can_view_tickets: {type: boolean} limits: {$ref: '#/components/schemas/PanelLimits'} server_time: {type: string, format: date-time} PanelEnrollResponse: type: object properties: device_id: {type: integer} device_token: {type: string, description: "rvpd_ plus 64 hex characters, shown once"} client: {type: object, properties: {client_id: {type: integer}, name: {type: string}}} contact: {type: object, nullable: true, properties: {contact_id: {type: integer}, name: {type: string}}} can_create_tickets: {type: boolean} limits: {$ref: '#/components/schemas/PanelLimits'} server_time: {type: string, format: date-time} PortalAnnouncement: type: object properties: id: {type: integer} title: {type: string} body: {type: string, description: Plain text} severity: {type: string, enum: [info, important, urgent]} pinned: {type: boolean} all_departments: {type: boolean} published_at: {type: string} expires_at: {type: string, nullable: true} PortalDevice: type: object properties: id: {type: integer} name: {type: string} description: {type: string} type: {type: string} make: {type: string} model: {type: string} serial: {type: string} os: {type: string, nullable: true} status: {type: string} purchase_date: {type: string, nullable: true} install_date: {type: string, nullable: true} warranty_expires: {type: string, nullable: true} warranty_days_left: {type: integer, nullable: true} warranty_state: {type: string, enum: [ok, expiring, expired, unknown]} last_seen: {type: string, nullable: true} seen_state: {type: string, enum: [online, recent, stale, unknown]} seen_age_s: {type: integer, nullable: true} reboot_pending: {type: boolean, nullable: true} PortalHome: type: object properties: contact: {type: object, properties: {id: {type: integer}, name: {type: string}, department_id: {type: integer}}} announcements: {type: array, items: {$ref: '#/components/schemas/PortalAnnouncement'}} open_requests: {type: array, items: {type: object, properties: {id: {type: integer}, number: {type: string}, subject: {type: string}, status: {type: string}, updated_at: {type: string, nullable: true}}}} devices: {type: array, items: {$ref: '#/components/schemas/PortalDevice'}} approvals_waiting: {type: integer} checklist: {type: object, nullable: true} kb: {type: object, properties: {popular: {type: array, items: {type: object}}, recent: {type: array, items: {type: object}}}} unread_notifications: {type: integer} AutomationRule: type: object properties: rule_id: {type: integer} name: {type: string} trigger_event: {type: string, example: ticket.created} conditions: {type: object, nullable: true, description: '{mode: all|any, conditions: [{field, op, value} | {mode, conditions: [...]}]}'} conditions_valid: {type: boolean} action_type: {type: string, enum: [create_ticket, send_webhook, notify_user, start_workflow, set_ticket_field, add_ticket_note, assign_ticket, send_mail, create_task, run_script, create_odoo_user, notify_chat, entra_disable_account, entra_add_to_groups]} action_config: {type: object} is_enabled: {type: boolean} priority: {type: integer} stop_on_match: {type: boolean} rate_limit_per_min: {type: integer} created_at: {type: string} imported_from_legacy_rule_id: {type: integer, nullable: true} summary: {type: string} AutomationRuleInput: type: object properties: name: {type: string, maxLength: 200} trigger_event: {type: string, example: certificate.expiring} conditions: {type: object, nullable: true} action_type: {type: string} action_config: {type: object} is_enabled: {type: boolean} priority: {type: integer, minimum: 1, maximum: 9999} stop_on_match: {type: boolean} rate_limit_per_min: {type: integer, minimum: 1, maximum: 1000} AutomationRun: type: object properties: run_id: {type: integer} rule_id: {type: integer} event_type: {type: string} status: {type: string, enum: [ok, failed, throttled, loop_blocked, skipped]} message: {type: string} duration_ms: {type: integer} chain_depth: {type: integer} created_at: {type: string} attempt: {type: integer, description: Which try of the job queue this was (1-3)} max_attempts: {type: integer} source: {type: string, enum: [event, retry, manual]} retry_of_run_id: {type: integer, nullable: true} retried_by_run_id: {type: integer, nullable: true} can_rerun: {type: boolean} IntegrationError: type: object properties: error: type: object properties: code: {type: string, example: not_found} message: {type: string} correlation_id: {type: string, description: "Echo of X-Correlation-Id, or generated"} IntegrationToken: type: object properties: access_token: {type: string} token_type: {type: string, example: Bearer} expires_in: {type: integer, example: 600} scope: {type: string, example: "lms:read lms:assign"} LmsEmployeeRef: type: object properties: rivetit_id: {type: string} odoo_employee_id: {type: string, nullable: true} LmsCourse: type: object properties: id: {type: string, description: "Stable course id (12 characters)"} kind: {type: string, enum: [training, document]} code: {type: string, nullable: true} external_code: {type: string, nullable: true, description: "The code the QMS knows the course by"} title: {type: string} description: {type: string, nullable: true} status: {type: string, enum: [published]} revision: {type: integer, description: "Published revision number"} revision_id: {type: integer} departments: {type: array, items: {type: string}, description: "Departments targeted by the course's active requirement rules"} est_minutes: {type: integer, nullable: true} validity_months: {type: integer, nullable: true} category: {type: string, nullable: true} requirements: type: array items: type: object properties: name: {type: string} required: {type: boolean} one_time: {type: boolean} all_people: {type: boolean} updated_at: {type: string, format: date-time} DirectoryEmployee: type: object properties: id: {type: string, description: "RivetIT contact id"} odoo_employee_id: {type: string, nullable: true, description: "Identity key: the Odoo employee id from the directory link"} name: {type: string} work_email: {type: string, nullable: true} job_title: {type: string, nullable: true} department_id: {type: string, nullable: true, description: "RivetIT department id (null = no department)"} odoo_department_id: {type: string, nullable: true} manager_id: {type: string, nullable: true, description: "Null when there is no manager or the manager is outside the client's department scope"} employment_status: {type: string, description: "pre-hire, active, leave, suspended, transfer_pending, termination_pending, terminated or archived"} active: {type: boolean, description: "false for terminated or archived people (tombstones): deprovision them"} updated_at: {type: string, format: date-time} DirectoryEmployeePage: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/DirectoryEmployee'}} next_cursor: {type: string, nullable: true} DirectoryDepartment: type: object properties: id: {type: string, description: "RivetIT department (client) id"} odoo_department_id: {type: string, nullable: true} name: {type: string} parent_id: {type: string, nullable: true, description: "Null when there is no parent or it is outside the client's department scope"} head_employee_id: {type: string, nullable: true, description: "Null when there is no head or the head is outside the client's department scope"} status: {type: string, description: "active, inactive, on_hold or archived"} active: {type: boolean, description: "false when archived or inactive (tombstone)"} updated_at: {type: string, format: date-time} DirectoryDepartmentPage: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/DirectoryDepartment'}} next_cursor: {type: string, nullable: true} LmsCoursePage: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/LmsCourse'}} next_cursor: {type: string, nullable: true} LmsAssignmentCreate: type: object required: [employee, course_id, due_on] properties: employee: type: object description: Exactly the identifiers odoo_employee_id and/or rivetit_id (if both, they must be the same person) properties: odoo_employee_id: {type: string} rivetit_id: {type: string} course_id: {type: string} due_on: {type: string, format: date, description: "Today or later"} source: {type: string, maxLength: 40, example: qms} external_system: {type: string, maxLength: 40, example: qms} external_ref: {type: string, maxLength: 120, example: NCR-0381, description: "Maps to exactly one assignment; send with external_system"} LmsAssignment: type: object properties: id: {type: string, example: asg_123} employee: {$ref: '#/components/schemas/LmsEmployeeRef'} course_id: {type: string} course_revision: {type: integer, nullable: true} status: {type: string, enum: [open, completed, waived, cancelled]} overdue: {type: boolean} required: {type: boolean} reason: {type: string} due_on: {type: string, format: date} original_due_on: {type: string, format: date} external_system: {type: string, nullable: true} external_ref: {type: string, nullable: true} completion_id: {type: string, nullable: true} created_at: {type: string, format: date-time} closed_at: {type: string, format: date-time, nullable: true} close_reason: {type: string, nullable: true} updated_at: {type: string, format: date-time} revision: {type: integer} LmsAssignmentResult: type: object properties: data: allOf: - {$ref: '#/components/schemas/LmsAssignment'} - type: object properties: reused: {type: boolean} source: {type: string, nullable: true, description: "Echo of the request's source"} LmsAssignmentPage: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/LmsAssignment'}} next_cursor: {type: string, nullable: true} LmsCompletion: type: object properties: id: {type: string, example: cmp_123} employee: {$ref: '#/components/schemas/LmsEmployeeRef'} course_id: {type: string} course_revision: {type: integer, nullable: true} course_revision_id: {type: integer, nullable: true} assignment_id: {type: string, nullable: true} assignment: type: object nullable: true properties: external_system: {type: string, nullable: true} external_ref: {type: string, nullable: true} completed_on: {type: string, format: date} result: {type: string, enum: [passed]} score_pct: {type: number, nullable: true} pass_mark_pct: {type: integer, nullable: true} method: {type: string} status: {type: string, enum: [completed, voided, superseded]} supersedes_id: {type: string, nullable: true} expires_on: {type: string, format: date, nullable: true, description: "Recertification date"} evidence_ref: type: object properties: certificate_number: {type: string, nullable: true} external_issuer: {type: string, nullable: true} external_ref: {type: string, nullable: true} evidence_available: {type: boolean} evidence_path: {type: string, nullable: true} recorded_at: {type: string, format: date-time} updated_at: {type: string, format: date-time} revision: {type: integer} LmsCompletionPage: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/LmsCompletion'}} next_cursor: {type: string, nullable: true} RelationshipCreate: type: object required: [src_type, src_id, dst_type, dst_id] properties: src_type: {type: string, enum: [asset, software, vendor, document, kb_article, service, network, domain, certificate, credential, contact, location, ticket]} src_id: {type: integer} dst_type: {type: string, enum: [asset, software, vendor, document, kb_article, service, network, domain, certificate, credential, contact, location, ticket]} dst_id: {type: integer} link_type: {type: string, enum: [depends_on, runs_on, supported_by, documented_by, related], default: related} note: {type: string, maxLength: 500} RelationshipRef: type: object properties: type: {type: string} id: {type: integer} name: {type: string} client_id: {type: integer} archived: {type: boolean} RelationshipLink: type: object properties: link_id: {type: integer, nullable: true, description: Null for derived rows} derived: {type: boolean} source: {type: string} link_type: {type: string} note: {type: string, nullable: true} created_at: {type: string, nullable: true} to: {$ref: '#/components/schemas/RelationshipRef'} from: {$ref: '#/components/schemas/RelationshipRef'} RelationshipView: type: object properties: record: {$ref: '#/components/schemas/RelationshipRef'} outgoing: {type: array, items: {$ref: '#/components/schemas/RelationshipLink'}} referenced_by: {type: array, items: {$ref: '#/components/schemas/RelationshipLink'}} impact: type: array items: type: object properties: type: {type: string} id: {type: integer} name: {type: string} client_id: {type: integer} depth: {type: integer, minimum: 1, maximum: 3} via: {type: string} Error: type: object properties: error: {type: string} Ok: type: object properties: ok: {type: boolean, example: true} Attachment: type: object properties: name: {type: string} filename: {type: string} url: {type: string} LoginRequest: type: object description: Password login, or passkey completion (send passkey_response + challenge_token) properties: username: {type: string} password: {type: string} totp_code: {type: string} device_name: {type: string} passkey_response: {type: object} challenge_token: {type: string} LoginResponse: type: object properties: token: {type: string} user: type: object properties: id: {type: integer} name: {type: string} email: {type: string} type: {type: integer} PasskeyBeginResponse: type: object properties: challenge: {type: string} timeout: {type: integer} rpId: {type: string} allowCredentials: {type: array, items: {type: object}} userVerification: {type: string} challengeToken: {type: string} AllowanceUsagePeriod: type: object description: Included vs. used hours for one delivery method (remote or onsite) over the requested month. When this allowance isn't configured (no active contract sets it), included/remaining/pct are null and used is 0 - treat null 'included' as "feature inactive" and don't render this period. properties: included: {type: number, nullable: true, description: 'Hours included, or null if this allowance is not configured'} used: {type: number, description: 'Hours used so far this month (flat per-ticket rate, not actual worked time); 0 when included is null'} remaining: {type: number, nullable: true, description: 'included - used; negative when over allowance; null when included is null'} pct: {type: number, nullable: true, description: 'used / included as a percentage, capped at 100; null when included is null'} AllowanceUsage: type: object properties: month: {type: integer, description: '1-12'} year: {type: integer} remote: {$ref: '#/components/schemas/AllowanceUsagePeriod'} onsite: {$ref: '#/components/schemas/AllowanceUsagePeriod'} contracts: type: array description: Per-contract breakdown across the client's active contracts that have an allowance configured items: type: object properties: id: {type: integer} name: {type: string} remote: {$ref: '#/components/schemas/AllowanceUsagePeriod'} onsite: {$ref: '#/components/schemas/AllowanceUsagePeriod'} DashboardResponse: type: object properties: my_open: {type: integer} all_open: {type: integer} unread: {type: integer} overdue: {type: integer} due_today: {type: integer} onsite_open: {type: integer} queue: {type: array, items: {$ref: '#/components/schemas/TicketListItem'}} CreateTicketRequest: type: object required: [subject] properties: subject: {type: string} details: {type: string} client_id: {type: integer} contact_id: {type: integer} assigned_to: {type: integer} category_id: {type: integer} priority: {type: string, enum: [low, medium, high, critical]} hostname: {type: string} AddReplyRequest: type: object required: [reply] properties: reply: {type: string} type: {type: string, description: "reply | note | client (customer/portal/website)"} time_worked: {type: string, description: HH:MM:SS} onsite: {type: integer, enum: [0, 1]} contact_id: {type: integer} TicketListItem: type: object properties: id: {type: integer} number: {type: integer} subject: {type: string} priority: {type: string} status: {type: string} status_color: {type: string} client: {type: string} assigned_to: {type: string} created_at: {type: string} due_at: {type: string, nullable: true} resolved_at: {type: string, nullable: true} updated_at: {type: string} TicketDetail: type: object properties: id: {type: integer} attachments_count: {type: integer, description: All attachments of the ticket including those on replies} number: {type: integer} subject: {type: string} details: {type: string} priority: {type: string} status: {type: string} status_color: {type: string} client: {type: string} assigned_to: {type: string} contact_name: {type: string} contact_email: {type: string} contact_phone: {type: string} billable: {type: boolean} created_at: {type: string} due_at: {type: string, nullable: true} resolved_at: {type: string, nullable: true} attachments: {type: array, items: {$ref: '#/components/schemas/Attachment'}} replies: {type: array, items: {$ref: '#/components/schemas/TicketReply'}} TicketReply: type: object properties: id: {type: integer} body: {type: string} type: {type: string} time_worked: {type: string, nullable: true} onsite: {type: boolean} by: {type: string} created_at: {type: string} attachments: {type: array, items: {$ref: '#/components/schemas/Attachment'}} ChatMessage: type: object properties: id: {type: integer} sender_type: {type: string, enum: [agent, contact]} sender_id: {type: integer} sender_name: {type: string} message: {type: string} created_at: {type: string} TicketStatus: type: object properties: id: {type: integer} name: {type: string} color: {type: string} TicketCategory: type: object properties: id: {type: integer} name: {type: string} color: {type: string} SavedTicketView: type: object properties: id: {type: integer} name: {type: string} icon: {type: string} params: type: object description: Query parameters for /tickets. Multi-value filters are comma-separated (priority "high,medium", assigned "me,unassigned,7", board/category_id "3,4"). additionalProperties: {type: string} shared: {type: boolean, description: True when the view is shared with all agents} is_default: {type: boolean, description: True when this is the view that opens by default for the calling user} default_scope: {type: string, nullable: true, enum: [personal, shared], description: Whose default it is (the caller's own, or the one for everyone), null when not the default} ClientListItem: type: object properties: id: {type: integer} name: {type: string} phone: {type: string, nullable: true} city: {type: string, nullable: true} state: {type: string, nullable: true} website: {type: string, nullable: true} ClientDetail: type: object properties: id: {type: integer} name: {type: string} phone: {type: string, nullable: true} address: {type: string, nullable: true} city: {type: string, nullable: true} state: {type: string, nullable: true} zip: {type: string, nullable: true} website: {type: string, nullable: true} notes: {type: string} open_tickets: {type: integer} contacts: {type: array, items: {$ref: '#/components/schemas/Contact'}} Contact: type: object properties: id: {type: integer} name: {type: string} title: {type: string, nullable: true} email: {type: string, nullable: true} phone: {type: string, nullable: true} extension: {type: string, nullable: true} client: {type: string, nullable: true} ClientLocation: type: object properties: id: {type: integer} name: {type: string} address: {type: string, nullable: true} city: {type: string, nullable: true} state: {type: string, nullable: true} zip: {type: string, nullable: true} phone: {type: string, nullable: true} primary: {type: boolean} AssetListItem: type: object properties: id: {type: integer} name: {type: string} type: {type: string, nullable: true} make: {type: string, nullable: true} model: {type: string, nullable: true} serial: {type: string, nullable: true} os: {type: string, nullable: true} status: {type: string, nullable: true} client: {type: string, nullable: true} AssetDetail: type: object properties: id: {type: integer} name: {type: string} type: {type: string, nullable: true} make: {type: string, nullable: true} model: {type: string, nullable: true} serial: {type: string, nullable: true} os: {type: string, nullable: true} status: {type: string, nullable: true} description: {type: string} physical_location: {type: string} location_name: {type: string} location_city: {type: string} location_state: {type: string} contact_name: {type: string} contact_phone: {type: string} client: {type: string, nullable: true} created_at: {type: string, nullable: true} purchase_date: {type: string} warranty_expire: {type: string} notes: {type: string} ProjectListItem: type: object properties: id: {type: integer} prefix: {type: string, nullable: true} number: {type: integer} name: {type: string} due_at: {type: string, nullable: true} created_at: {type: string, nullable: true} completed_at: {type: string, nullable: true} archived_at: {type: string, nullable: true} client: {type: string, nullable: true} manager: {type: string, nullable: true} ticket_count: {type: integer} ticket_closed_count: {type: integer} task_count: {type: integer} task_completed_count: {type: integer} ProjectMilestone: type: object properties: id: {type: integer} name: {type: string} description: {type: string, nullable: true} due_at: {type: string, nullable: true} order: {type: integer} status: {type: string} completed_at: {type: string, nullable: true} ProjectTask: type: object properties: id: {type: integer} name: {type: string} status: {type: string, nullable: true} progress: {type: integer} due_at: {type: string, nullable: true} start_at: {type: string, nullable: true} milestone_id: {type: integer, nullable: true} completed_at: {type: string, nullable: true} assigned_to: {type: string, nullable: true} ticket_number: {type: string, nullable: true} priority: {type: integer, minimum: 0, maximum: 4, description: '0 none, 1 low, 2 medium, 3 high, 4 urgent (database 2.6.207; 0 before the update)'} priority_name: {type: string, example: High} description: {type: string, nullable: true, description: 'Plain text, never HTML'} color: {type: string, nullable: true, example: '#206bc4', description: 'Card accent as #rrggbb'} labels: type: array items: type: object properties: id: {type: integer} name: {type: string} color: {type: string} parent_id: {type: integer, nullable: true, description: 'The parent task when this is a subtask (database 2.6.208; null before the update and for ordinary tasks)'} assignees: type: array description: Everyone on the task, the primary assignee first (database 2.6.209; before it, only the primary). `assigned_to` stays the primary's name. items: type: object properties: id: {type: integer} name: {type: string} primary: {type: boolean} checklist: type: object description: Checklist progress (database 2.6.208; zeros before it) properties: done: {type: integer} total: {type: integer} subtasks: type: object description: Subtask progress (database 2.6.208) properties: done: {type: integer} total: {type: integer} comment_count: {type: integer} attachment_count: {type: integer} reminder_at: {type: string, nullable: true, example: '2026-11-02 09:00:00', description: 'One-off reminder time (database 2.6.209)'} reminder_sent_at: {type: string, nullable: true} repeat: type: object nullable: true description: 'Repeat rule (database 2.6.209); null when the task does not repeat. Completing the task creates the next occurrence with the due date moved on.' properties: interval: {type: integer, minimum: 1, maximum: 999} unit: {type: string, enum: [day, week, month, year]} TaskChecklistItem: type: object properties: id: {type: integer} text: {type: string} done: {type: boolean} TaskComment: type: object properties: id: {type: integer} user_id: {type: integer, nullable: true} user: {type: string, description: 'Author name, or "Former user"'} body: {type: string} created_at: {type: string} updated_at: {type: string, nullable: true} ProjectTaskInput: type: object description: Every field is optional on PATCH/PUT; project_id and name are required on POST /tasks. properties: project_id: {type: integer, description: 'Create only'} name: {type: string, maxLength: 255} status: {type: string, enum: ['To Do', 'In Progress', 'Blocked', 'Done']} progress: {type: integer, minimum: 0, maximum: 100} start_at: {type: string, format: date, nullable: true} due_at: {type: string, format: date, nullable: true} milestone_id: {type: integer, description: "Must belong to the task's project; 0 clears"} assigned_user_id: {type: integer, description: 'An active user; 0 clears'} estimate_minutes: {type: integer, minimum: 0} priority: {type: integer, minimum: 0, maximum: 4} description: {type: string, nullable: true, maxLength: 20000} color: {type: string, nullable: true, example: '#206bc4'} labels: type: array description: Label names, or {name, color}; unknown names are created in the task's project; replaces the task's labels ([] clears). items: oneOf: - {type: string} - type: object properties: name: {type: string} color: {type: string} label_ids: type: array description: Existing labels that are global or belong to the task's project (others are ignored). items: {type: integer} parent_id: {type: integer, nullable: true, description: "Make the task a subtask of this task (same project, one level deep, no cycles); null or 0 detaches. On POST the parent is checked before anything is created."} assignee_ids: type: array description: 'Everyone on the task (active users). The current primary stays primary when it is in the list, otherwise the first one becomes it. assigned_user_id alone (older clients) swaps the primary and keeps the rest; 0 clears everyone.' items: {type: integer} reminder_at: {type: string, nullable: true, example: '2026-11-02 09:00', description: "YYYY-MM-DD HH:MM[:SS]; null clears. Changing the time re-arms a delivered reminder."} repeat: type: object nullable: true description: Repeat rule; null stops repeating. properties: interval: {type: integer, minimum: 1, maximum: 999} unit: {type: string, enum: [day, week, month, year]} ProjectTicket: type: object properties: id: {type: integer} number: {type: string} subject: {type: string} status: {type: string, nullable: true} status_color: {type: string, nullable: true} due_at: {type: string, nullable: true} closed_at: {type: string, nullable: true} assigned_to: {type: string, nullable: true} ProjectDetail: type: object properties: id: {type: integer} prefix: {type: string, nullable: true} number: {type: integer} name: {type: string} description: {type: string} due_at: {type: string, nullable: true} start_at: {type: string, nullable: true} created_at: {type: string, nullable: true} updated_at: {type: string, nullable: true} completed_at: {type: string, nullable: true} archived_at: {type: string, nullable: true} client: {type: string, nullable: true} manager: {type: string, nullable: true} estimated_hours: {type: number, nullable: true} budget_amount: {type: number, nullable: true} hourly_rate: {type: number, nullable: true} milestones: {type: array, items: {$ref: '#/components/schemas/ProjectMilestone'}} tasks: {type: array, items: {$ref: '#/components/schemas/ProjectTask'}} tickets: {type: array, items: {$ref: '#/components/schemas/ProjectTicket'}} ContractListItem: type: object properties: id: {type: integer} name: {type: string} type: {type: string, nullable: true} status: {type: string, nullable: true, description: 'Raw contract_status value - manually set, may disagree with renewal_date; see is_expired/is_due_soon'} client: {type: string, nullable: true} value: {type: number, nullable: true} renewal_frequency: {type: string, nullable: true} start_date: {type: string, nullable: true} end_date: {type: string, nullable: true} renewal_date: {type: string, nullable: true} is_expired: {type: boolean} is_due_soon: {type: boolean, description: 'renewal_date is today or within the next 45 days'} has_sla: {type: boolean} has_allowance: {type: boolean} ContractSlaTier: type: object properties: response_time: {type: integer, nullable: true, description: 'Hours; null when not configured'} resolution_time: {type: integer, nullable: true, description: 'Hours; null when not configured'} ContractDetail: type: object properties: id: {type: integer} name: {type: string} type: {type: string, nullable: true} status: {type: string, nullable: true} client: {type: string, nullable: true} value: {type: number, nullable: true} renewal_frequency: {type: string, nullable: true} start_date: {type: string, nullable: true} end_date: {type: string, nullable: true} renewal_date: {type: string, nullable: true} is_expired: {type: boolean} is_due_soon: {type: boolean} details: {type: string} sla: type: object properties: high: {$ref: '#/components/schemas/ContractSlaTier'} medium: {$ref: '#/components/schemas/ContractSlaTier'} low: {$ref: '#/components/schemas/ContractSlaTier'} allowance: type: object description: Same shape as the month/year/remote/onsite fields of AllowanceUsage, for this one contract properties: month: {type: integer} year: {type: integer} remote: {$ref: '#/components/schemas/AllowanceUsagePeriod'} onsite: {$ref: '#/components/schemas/AllowanceUsagePeriod'} documents: type: array items: type: object properties: id: {type: integer} name: {type: string} mime_type: {type: string, nullable: true} size: {type: integer} uploaded_at: {type: string, nullable: true} url: {type: string} created_at: {type: string, nullable: true} updated_at: {type: string, nullable: true} CredentialListItem: type: object properties: id: {type: integer} name: {type: string} username: {type: string, nullable: true} uri: {type: string, nullable: true} client: {type: string, nullable: true} CredentialDetail: type: object properties: id: {type: integer} name: {type: string} username: {type: string} password: {type: string} uri: {type: string, nullable: true} uri_2: {type: string} otp_secret: {type: string} note: {type: string} client: {type: string, nullable: true} Charge: type: object properties: id: {type: integer} name: {type: string} description: {type: string, nullable: true} quantity: {type: number} unit_price: {type: number} total: {type: number} invoiced: {type: boolean} created_by: {type: string, nullable: true} created_at: {type: string} WorksheetSummary: type: object properties: id: {type: integer} template_name: {type: string, nullable: true} created_by: {type: string, nullable: true} created_at: {type: string} completed_at: {type: string, nullable: true} signed_name: {type: string, nullable: true} signed_at: {type: string, nullable: true} is_outtake: {type: boolean} signed: {type: boolean} WorksheetDetail: type: object properties: id: {type: integer} template_name: {type: string, nullable: true} signed_name: {type: string, nullable: true} signed_at: {type: string, nullable: true} completed_at: {type: string, nullable: true} signed: {type: boolean} fields: type: array items: type: object properties: id: {type: integer} name: {type: string} type: {type: string} options: {type: string, nullable: true} required: {type: boolean} value: {type: string, nullable: true} WorksheetTemplate: type: object properties: id: {type: integer} name: {type: string} description: {type: string, nullable: true} OuttakeSummary: type: object properties: id: {type: integer} sign_token: {type: string, nullable: true} notes: {type: string, nullable: true} created_by: {type: string, nullable: true} created_at: {type: string} signed_name: {type: string, nullable: true} signed_at: {type: string, nullable: true} signed: {type: boolean} OuttakeDetail: allOf: - $ref: '#/components/schemas/OuttakeSummary' - type: object properties: ticket_subject: {type: string, nullable: true} client: {type: string, nullable: true} contact_name: {type: string, nullable: true} SignRequest: type: object required: [signed_name] properties: signed_name: {type: string} signature: {type: string, description: "data:image/png;base64,... (optional)"} SearchRecord: type: object properties: id: {type: integer} name: {type: string} detail: {type: string} client_id: {type: integer} client: {type: string} SearchResult: type: object properties: tickets: {type: array, items: {$ref: '#/components/schemas/TicketListItem'}} clients: {type: array, items: {$ref: '#/components/schemas/ClientListItem'}} assets: {type: array, items: {$ref: '#/components/schemas/AssetListItem'}} software: {type: array, items: {$ref: '#/components/schemas/SearchRecord'}} networks: {type: array, items: {$ref: '#/components/schemas/SearchRecord'}} services: {type: array, items: {$ref: '#/components/schemas/SearchRecord'}} linked: type: array description: Records linked to a record whose name matches (links and the older link tables), each with what it is linked to. items: type: object properties: type: {type: string} id: {type: integer} name: {type: string} client_id: {type: integer} linked_to: {type: string, description: 'e.g. "Asset srv-core"'} relation: {type: string, description: 'e.g. "documents"'} contacts: type: array description: Omitted (empty) if the caller lacks module_client permission. items: type: object properties: id: {type: integer} name: {type: string} title: {type: string, nullable: true} email: {type: string, nullable: true} phone: {type: string, nullable: true} extension: {type: string, nullable: true} client_id: {type: integer, nullable: true} client: {type: string, nullable: true} credentials: type: array description: > Name/URI only, never decrypted secrets. Omitted (empty) if the caller lacks module_credential permission. items: type: object properties: id: {type: integer} name: {type: string} uri: {type: string, nullable: true} client: {type: string, nullable: true} articles: type: array description: Knowledge base articles. Omitted (empty) if the caller lacks module_kb permission. items: type: object properties: id: {type: integer} title: {type: string} KbCategory: type: object properties: id: {type: integer} name: {type: string} parent_id: {type: integer} client_id: {type: integer} KbArticleListItem: type: object properties: id: {type: integer} title: {type: string} category_id: {type: integer} category_name: {type: string, nullable: true} client_id: {type: integer} client_name: {type: string, nullable: true} client_visible: {type: integer} updated_at: {type: string} KbAttachment: type: object description: > A KB article attachment. NOTE the shape differs from the shared `Attachment` schema used by tickets: this one carries `id` and has no `filename`. It always did - the spec previously pointed at `Attachment` and was simply wrong about it. properties: id: {type: integer, description: kb_article_attachments.kb_article_attachment_id} name: {type: string, description: The original filename as uploaded.} url: type: string description: > A SHORT-LIVED, SIGNED, ABSOLUTE URL. Fetch it with no credentials of any kind - the signature in the query string IS the credential, which is what lets an external browser or a WebView (neither of which can send `Authorization`) open it. Shape: `https:///agent/kb_media.php?att=&p=&e=&s=`. Valid for 24 hours, and bound to the CREDENTIAL that requested it - a URL minted for your token is not usable by anyone else, and it stops working the moment that token or key is revoked, expires, or its user is disabled, archived or loses `module_kb`. Permissions are re-derived from the database on every fetch, so the URL is proof of identity and never a grant. Do not cache it, store it, or share it; re-request the article to get a fresh one. Adding `&download=1` forces a download instead of an inline preview. That parameter is deliberately outside the signature, so the same URL serves both. PDFs and common image types preview inline; everything else downloads. FALLBACK, when this install cannot sign - it has no configured base URL, or the signing key does not exist because the database is still below version 2.6.78. The URL is then ROOT-RELATIVE, and which relative form you get says what to do with it: * `/uploads/kb//` - the pre-2.6.78 shape, emitted only while the database has not been migrated and the file is verified present on disk. Resolve it against your server URL and fetch it; it works with no credentials, exactly as this endpoint behaved before signing existed. It disappears the moment the database update runs. * `/agent/kb_media.php?att=` - the canonical authenticated form, emitted on a migrated install that still cannot sign (a broken configuration). It needs a browser session cookie and will NOT work from the API. Treat a redirect to the login page as "media unavailable", not as an error to retry. KbArticleDetail: allOf: - $ref: '#/components/schemas/KbArticleListItem' - type: object properties: content: type: string description: > Article body as HTML, run through HTMLPurifier. Every KB media reference the importers and the editor uploader produce - `/uploads/kb//` and flat `/uploads/kb/`, in `src`, `href` and CSS `url()` - is replaced with a signed absolute URL of the same form as `KbAttachment.url` (`?a=&f=&p=&e=&s=`), valid for 2 hours and fetchable with no headers. Render the string directly (e.g. Android's `WebView.loadDataWithBaseURL`) and the images load over the plain network stack. `alt` is empty rather than derived from the filename, so no part of the token is ever exposed as text. WHAT IS *NOT* REWRITTEN, stated exactly rather than promised away: a `/uploads/...` path that is not one of those two shapes is passed through untouched. That means a nested subdirectory (`/uploads/kb/13/sub/x.png`), a filename outside `[A-Za-z0-9_-]+.[A-Za-z0-9]+` (a space, which purification percent-encodes, or a second dot as in `archive.tar.gz`), and anything elsewhere under `/uploads/` such as a ticket screenshot pasted into an article. None of these can be produced by the DOCX importer, the PDF importer or the editor uploader - every name they generate is hex or base64url plus a single extension - and the media endpoint would refuse the first two anyway, so rewriting them would trade a working URL for a guaranteed 403. Treat them as ordinary relative URLs. When this install cannot sign, the whole body is emitted exactly as stored: pre-2.6.78 that is the legacy `/uploads/kb/...` form, which is fetchable and is what this endpoint returned before signing existed; from 2.6.78 it is the canonical `/agent/kb_media.php?...` form, which needs a session cookie. See `KbAttachment.url` for the same two cases. attachments: {type: array, items: {$ref: '#/components/schemas/KbAttachment'}} UserProfile: type: object properties: id: {type: integer} name: {type: string} email: {type: string} type: {type: integer} color: {type: string, nullable: true} avatar: {type: string, nullable: true} modules: type: object description: > Feature-module flags relevant to client UIs, such as gating ticket charges in RivetIT's mobile app. properties: accounting_enabled: {type: boolean} ticket_charges_enabled: {type: boolean} is_admin: {type: boolean, description: The login's role is an administrator role (every permission is 3).} limited: type: boolean description: > A module-only login (no Departments, Tickets/assets/docs or Assets, e.g. Training only). The API then allows only /me, /notifications and /kb, /reports, /alerts for modules the role holds; everything else answers 403. permissions: type: object description: > Every module (module_client, module_support, module_assets, module_training, ...) with this login's level - 0 none, 1 view, 2 edit, 3 full - so the app can hide screens it cannot open. Asset screens accept module_assets or module_support. additionalProperties: {type: integer, minimum: 0, maximum: 3} UpdateProfileRequest: type: object description: > One of several shapes. Profile update: name+email (+ current_password/new_password). Push registration: fcm_token. Biometric registration: device_public_key_pem. properties: name: {type: string} email: {type: string} current_password: {type: string} new_password: {type: string} fcm_token: {type: string} device_public_key_pem: {type: string} Appointment: type: object properties: id: {type: integer} ticket_id: {type: integer} number: {type: integer} subject: {type: string} schedule: {type: string, nullable: true} schedule_end: {type: string, nullable: true} onsite: {type: boolean} notes: {type: string, nullable: true} priority: {type: string, nullable: true} status: {type: string, nullable: true} status_color: {type: string, nullable: true} client: {type: string, nullable: true} assigned_to: {type: string, nullable: true} CreateAppointmentRequest: type: object required: [ticket_id, schedule_start] properties: ticket_id: {type: integer} schedule_start: {type: string, description: "Y-m-d H:i:s"} schedule_end: {type: string, nullable: true} onsite: {type: boolean} notes: {type: string} ApprovalList: type: object properties: items: type: array items: {$ref: '#/components/schemas/ApprovalItem'} counts: type: object properties: total: {type: integer} ApprovalItem: type: object properties: kind: {type: string, enum: [catalog_request, workflow_task]} id: {type: integer, description: "request_id (catalog_request) or run_task_id (workflow_task)"} title: {type: string} requester: {type: string} summary: {type: string} risk_score: {type: integer, nullable: true} step: {type: string, nullable: true} ticket_id: {type: integer, nullable: true} requested_at: {type: string, example: "2026-10-06 09:00:00"} due_at: {type: string, nullable: true} fields: type: array items: type: object properties: label: {type: string} value: {type: string} ApprovalDecision: type: object required: [kind, id, decision] properties: kind: {type: string, enum: [catalog_request, workflow_task]} id: {type: integer} decision: {type: string, enum: [approve, reject]} comment: {type: string, description: "Required for reject; up to 2000 characters"} CatalogList: type: object properties: categories: type: array description: Active catalog categories (the tile groups), in display order. An item whose category_id is null belongs to "Other". items: type: object properties: id: {type: integer} name: {type: string} description: {type: string} icon: {type: string} items: type: array items: type: object properties: id: {type: integer} name: {type: string} description: {type: string} icon: {type: string} category_id: {type: integer, nullable: true} requires_approval: {type: boolean} risk_score: {type: integer, description: "The item's base score. The score of a request is computed from this plus the item's risk rules and the answers; it decides auto-approval and which approval chain applies."} fields: type: array items: type: object properties: key: {type: string} label: {type: string} type: {type: string, enum: [text, textarea, select, checkbox, date, number, table]} options: {type: array, items: {type: string}} columns: type: array description: "Only for type table: the columns of the repeating table. Send the answer as a list of rows (max 25), each row a list of cell values in column order or an object keyed by the column label." items: type: object properties: label: {type: string} type: {type: string, enum: [text, number, date]} required: {type: boolean} placeholder: {type: string} show_if: {type: object, nullable: true, description: "Show this field only when earlier fields match: one rule {field, op: equals|in|not_empty, value}, or several {match: all|any, rules: [rule, ...]} (up to 3). A hidden field is never required and its answer is ignored. null = always visible."} popular: {type: array, items: {type: integer}} recent: {type: array, items: {type: integer}} CatalogRequest: type: object required: [catalog_item_id] properties: catalog_item_id: {type: integer} answers: {type: object, additionalProperties: true, description: "field key to value; booleans and numbers are accepted for checkbox/number fields; a table field takes a list of rows"} client_id: {type: integer, nullable: true} HrRequestList: type: object properties: items: type: array items: type: object properties: id: {type: integer} type: {type: string, enum: [onboarding, offboarding, role_change]} status: {type: string, enum: [pending, approved, rejected, cancelled]} client_id: {type: integer} department: {type: string} requested_by: {type: string} subject: {type: string} subject_contact_id: {type: integer, nullable: true} effective_date: {type: string, format: date, nullable: true} details: {type: object, additionalProperties: true} requested_at: {type: string} decided_at: {type: string, nullable: true} decision_comment: {type: string, nullable: true} run_id: {type: integer, nullable: true} templates: type: array items: type: object properties: id: {type: integer} name: {type: string} counts: type: object properties: total: {type: integer} HrRequestDecision: type: object required: [id, decision] properties: id: {type: integer} decision: {type: string, enum: [approve, reject]} template_id: {type: integer, description: "Required to approve"} comment: {type: string, maxLength: 500, description: "Required to reject; the requester sees it"} WorkflowTaskList: type: object properties: items: type: array items: type: object properties: id: {type: integer} run_id: {type: integer} run_title: {type: string} task_title: {type: string} instructions: {type: string} due_at: {type: string, nullable: true} status: {type: string, enum: [pending, blocked, running, action_failed, rejected]} type: {type: string, enum: [manual, approval, action]} blocked_by: {type: array, items: {type: string}} contact_name: {type: string} assignee: {type: string, nullable: true} counts: type: object properties: open: {type: integer} overdue: {type: integer} WorkflowTaskAction: type: object required: [id, action] properties: id: {type: integer} action: {type: string, enum: [complete, skip]} reason: {type: string, description: "Required for skip; up to 500 characters"} TicketAttachmentList: type: object properties: items: type: array items: type: object properties: id: {type: integer} name: {type: string} size: {type: integer} mime: {type: string} created_at: {type: string} uploaded_by: {type: string, nullable: true} Notification: type: object properties: id: {type: integer} type: {type: string, description: "'approval' for an approval request (route on it with kind + ref_id); otherwise the notification category, e.g. Ticket"} message: {type: string} action: {type: string, nullable: true} timestamp: {type: string} kind: {type: string, enum: [catalog_request, workflow_task], description: "Only when type is approval"} ref_id: {type: integer, description: "Only when type is approval: the approval id to pass to POST /approvals"} Alert: type: object properties: source: {type: string, enum: [rmm, backup]} id: {type: integer} severity: {type: string, enum: [critical, error, warning, info]} message: {type: string} subject: {type: string, nullable: true} client_id: {type: integer, nullable: true} client_name: {type: string, nullable: true} status: {type: string} created_at: {type: string} ticket_id: {type: integer, nullable: true} ticket_label: {type: string, nullable: true} AlertActionRequest: type: object required: [source, id, action] properties: source: {type: string, enum: [rmm, backup]} id: {type: integer} action: {type: string, enum: [acknowledge, resolve]} AgentError: type: object required: [error, code] properties: error: {type: string} code: {type: string, description: "invalid_token, revoked, expired, forbidden, conflict, invalid, rate_limited, too_large, not_found, tls_required, internal"} AgentEnrollRequest: type: object required: [enrollment_token, device] properties: enrollment_token: {type: string} device: type: object required: [install_id, hostname, os, os_version, arch, agent_version] properties: install_id: {type: string, format: uuid} machine_guid: {type: string, nullable: true} hostname: {type: string} os: {type: string, enum: [windows]} os_version: {type: string} arch: {type: string, enum: [amd64, arm64]} serial: {type: string, nullable: true} manufacturer: {type: string, nullable: true} model: {type: string, nullable: true} mac_addresses: {type: array, items: {type: string}} agent_version: {type: string} AgentEnrollResponse: type: object properties: device_id: {type: integer} device_token: {type: string, description: Shown once} check_in_interval_s: {type: integer} server_time: {type: string, format: date-time} status: {type: string, enum: [linked, pending_approval, ambiguous]} matched_asset_id: {type: integer, nullable: true} signing_public_key: {type: string, description: base64 Ed25519 public key} signing_key_id: {type: string} config: {$ref: '#/components/schemas/AgentConfig'} AgentConfig: type: object properties: checks: type: array items: type: object properties: key: {type: string} type: {type: string, enum: [service, disk, pending_reboot, script]} params: {type: object} interval_s: {type: integer} signature: {type: string, description: Ed25519 over the canonical JSON of the other fields} collect_interval_s: {type: integer} AgentCheckinRequest: type: object required: [seq, collected_at, agent_version] properties: seq: {type: integer, minimum: 0} collected_at: {type: string, format: date-time} agent_version: {type: string} inventory: {type: object, nullable: true} metrics: type: object nullable: true properties: cpu_pct: {type: number, nullable: true} mem_pct: {type: number, nullable: true} disk: {type: array, items: {type: object, properties: {mount: {type: string}, used_pct: {type: number, nullable: true}}}} net_rx_bps: {type: number, nullable: true} net_tx_bps: {type: number, nullable: true} checks: type: array maxItems: 100 items: type: object properties: key: {type: string} status: {type: string, enum: [ok, warn, fail, unknown]} detail: {type: string} buffered: type: array maxItems: 100 items: {type: object} update_result: {type: object, nullable: true} AgentCheckinResponse: type: object properties: ok: {type: boolean} next_check_in_s: {type: integer} jobs_pending: {type: integer} config: {$ref: '#/components/schemas/AgentConfig'} update: nullable: true type: object properties: version: {type: string} url: {type: string} sha256: {type: string} signature: {type: string, description: base64 Ed25519 over the lowercase hex sha256} min_version: {type: string} server_time: {type: string, format: date-time} signing_key_id: {type: string} AgentJob: type: object properties: job_id: {type: string, format: uuid} attempt: {type: integer} type: {type: string, enum: [powershell, reboot, collect]} script: {type: string, nullable: true} params: {type: object} timeout_s: {type: integer} max_output_bytes: {type: integer} issued_at: {type: string, format: date-time} expires_at: {type: string, format: date-time} signature: {type: string, description: base64 Ed25519 over the canonical JSON of all other fields} AgentJobReport: type: object required: [job_id, attempt, state] properties: job_id: {type: string, format: uuid} attempt: {type: integer} state: {type: string, enum: [running, succeeded, failed, timed_out, cancelled]} exit_code: {type: integer, nullable: true} output: {type: string} started_at: {type: string, format: date-time, nullable: true} finished_at: {type: string, format: date-time, nullable: true} EndpointDevice: type: object properties: device_id: {type: integer} hostname: {type: string} asset_id: {type: integer, nullable: true} client_id: {type: integer} link_state: {type: string, enum: [linked, pending_approval, rejected]} status: {type: string, enum: [online, offline, stale, never]} last_checkin_at: {type: string, format: date-time, nullable: true} offline_since: {type: string, format: date-time, nullable: true} agent_version: {type: string} ring: {type: string} inventory: {type: object, nullable: true} checks: {type: array, items: {type: object}} jobs: {type: array, items: {type: object}} EndpointJobRequest: type: object required: [type] properties: type: {type: string, enum: [powershell, reboot, collect]} script: {type: string} script_id: {type: integer, description: A saved PowerShell script from the RMM script library} params: {type: object, description: "Scalar values only (strings, whole numbers, booleans)"} timeout_s: {type: integer} destructive: {type: boolean} confirm: {type: boolean, description: Required for reboot and destructive jobs}