openapi: 3.0.3 info: title: RivetMSP API v1 version: 1.0.0 description: > Companion REST API for RivetMSP, consumed by the RivetMSP mobile app and integrations (ITPanel Pro, RMM scripts). This spec documents the *live* endpoints served by /api/v1/index.php and its per-resource handlers. Authentication: send a bearer token issued by POST /auth (`Authorization: Bearer `) OR a legacy instance API key (`X-Api-Key: `). The legacy key resolves to the first active admin and is intentionally denied on `/credentials` and `/me`. The `/auth`, `/branding`, `/openapi` and `/docs` endpoints are public (no token required). Response conventions: * Paged list endpoints return `{ "data": [ ... ], "total": }` (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 RivetMSP install host tags: - name: Auth - name: Dashboard - name: Tickets - name: Ticket Meta - name: Clients - name: Contacts - name: Assets - name: Relationships - name: Credentials - name: Quotes - name: Invoices - name: Expenses - name: Worksheets - name: Outtakes - name: Products - name: Search - name: Reports - name: Knowledge Base - name: Profile - name: Appointments - name: Notifications - name: Alerts - name: Diagnostics - name: Public - name: Meta - name: Endpoint agent security: - bearerAuth: [] - ApiKeyAuth: [] 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 use the RivetMSP fallback content: application/json: schema: type: object required: [name, logo_path] properties: name: type: string logo_path: type: string nullable: true example: /uploads/settings/company-logo.png '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 or API key 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 several (comma list, e.g. high,medium). OR inside a filter, AND between filters.', schema: {type: string, example: 'high,medium'}} - {name: onsite, in: query, description: 'Comma list of 0 and/or 1 (both = no filter).', schema: {type: string, example: '1'}} - {name: category_id, in: query, description: 'One or several category ids (comma list).', schema: {type: string, example: '3,4'}} - {name: board_id, in: query, description: 'One or several board (top-level category) ids; includes their sub-categories.', schema: {type: string}} - {name: assigned, in: query, description: 'Comma list of me, unassigned and agent ids (mine=1 is the same as me).', schema: {type: string, example: 'me,7,unassigned'}} - {name: status_id, in: query, description: 'Specific status ids (comma list); overrides status.', schema: {type: string}} - {name: tag_id, in: query, description: 'Tickets carrying any of these tag ids (comma list).', 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 client 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 client unless one is kept in no client (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 clients, 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'} /credentials: get: tags: [Credentials] summary: List credentials (names/URIs only, no secrets; paged). Requires a user token — legacy API key is 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'} /quotes: get: tags: [Quotes] summary: List quotes (paged) 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 quote list content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/QuoteListItem'}} total: {type: integer} '403': {$ref: '#/components/responses/Forbidden'} /quotes/{id}: get: tags: [Quotes] summary: Quote detail with line items parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Quote detail content: application/json: schema: {$ref: '#/components/schemas/QuoteDetail'} '404': {$ref: '#/components/responses/NotFound'} /invoices: get: tags: [Invoices] summary: List invoices (paged) parameters: - {$ref: '#/components/parameters/PageParam'} - {$ref: '#/components/parameters/LimitParam'} - {name: client_id, in: query, schema: {type: integer}} - {name: status, in: query, schema: {type: string}} responses: '200': description: Paged invoice list content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/InvoiceListItem'}} total: {type: integer} '403': {$ref: '#/components/responses/Forbidden'} /invoices/{id}: get: tags: [Invoices] summary: Invoice detail with line items parameters: - {$ref: '#/components/parameters/IdPath'} responses: '200': description: Invoice detail content: application/json: schema: {$ref: '#/components/schemas/InvoiceDetail'} '404': {$ref: '#/components/responses/NotFound'} /expenses: get: tags: [Expenses] summary: List expenses (paged) parameters: - {$ref: '#/components/parameters/PageParam'} - {$ref: '#/components/parameters/LimitParam'} responses: '200': description: Paged expense list content: application/json: schema: type: object properties: data: {type: array, items: {$ref: '#/components/schemas/Expense'}} total: {type: integer} post: tags: [Expenses] summary: Create an expense (multipart, optional receipt upload) requestBody: required: true content: multipart/form-data: schema: type: object required: [description, amount] properties: description: {type: string} amount: {type: number} date: {type: string, format: date} currency: {type: string, default: USD} reference: {type: string} payment_method: {type: string} client_id: {type: integer} receipt: {type: string, format: binary} responses: '201': description: Expense created content: application/json: schema: type: object properties: {id: {type: integer}} '400': {$ref: '#/components/responses/BadRequest'} '403': {$ref: '#/components/responses/Forbidden'} /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'} /products: get: tags: [Products] summary: List products/services for charge selection (bare array) parameters: - {$ref: '#/components/parameters/SearchParam'} - {name: type, in: query, schema: {type: string}} responses: '200': description: Products content: application/json: schema: {type: array, items: {$ref: '#/components/schemas/Product'}} /search: get: tags: [Search] summary: Global search across tickets, clients, assets, software, networks, services 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/mrr: get: tags: [Reports] summary: Monthly recurring revenue report 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/clients-with-balance: get: tags: [Reports] summary: Clients carrying an outstanding balance responses: '200': {$ref: '#/components/responses/ReportObject'} /reports/income-summary: get: tags: [Reports] summary: Income summary for a year parameters: - {$ref: '#/components/parameters/YearParam'} responses: '200': {$ref: '#/components/responses/ReportObject'} /reports/expense-summary: get: tags: [Reports] summary: Expense summary for a year parameters: - {$ref: '#/components/parameters/YearParam'} responses: '200': {$ref: '#/components/responses/ReportObject'} /reports/profit-loss: get: tags: [Reports] summary: Monthly profit and loss for a year 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 — legacy API key is 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} /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 token/key (legacy compatibility 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-client, 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-client 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 client'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_transfer: get: tags: [Endpoint agent] summary: Read a range of a file the server holds for this device (device credential + one-time transfer token; file transfer switch) description: > Used by the agent while it runs a signed file_put job (RivetCore 1.0.0-rc.11). Needs the device credential AND the transfer's one-time token in the X-Transfer-Token header (never in the URL), only for a transfer that belongs to this device and is unexpired. length is at most 1 MiB. The answer is the raw bytes with X-Transfer-Size and X-Transfer-Sha256. While the file transfer sub-switch is off the answer is 503 feature_disabled; while the module is off 503 module_disabled. security: [{deviceAuth: []}] parameters: - {name: transfer_id, in: query, required: true, schema: {type: string, format: uuid}} - {name: offset, in: query, required: true, schema: {type: integer, minimum: 0}} - {name: length, in: query, required: true, schema: {type: integer, minimum: 1, maximum: 1048576}} - {name: X-Transfer-Token, in: header, required: true, schema: {type: string, pattern: '^[0-9a-f]{64}$'}} responses: '200': {description: The bytes, 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: "Unknown transfer, another device's transfer, a wrong token or the wrong direction (all the same not_found)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '416': {description: "The range is outside the file", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Rate limited (600 per 60 s per device)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '503': {description: "module_disabled or feature_disabled", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} post: tags: [Endpoint agent] summary: Send one chunk of a file to the server (device credential + one-time transfer token; file transfer switch) description: > Used by the agent while it runs a signed file_get job. Raw body of at most 1 MiB at offset; the final chunk carries X-Transfer-Last 1 and X-Transfer-Sha256 of the whole file, which the server compares with the SHA-256 of what it stored before it keeps the file (mismatch: 422 checksum_mismatch and the bytes are deleted). An offset gap is 409 conflict with received. The running total must stay within the transfer's size cap (413). security: [{deviceAuth: []}] parameters: - {name: transfer_id, in: query, required: true, schema: {type: string, format: uuid}} - {name: offset, in: query, required: true, schema: {type: integer, minimum: 0}} - {name: X-Transfer-Token, in: header, required: true, schema: {type: string, pattern: '^[0-9a-f]{64}$'}} - {name: X-Transfer-Last, in: header, required: false, schema: {type: string, enum: ['1']}} - {name: X-Transfer-Sha256, in: header, required: false, schema: {type: string, pattern: '^[0-9a-f]{64}$'}} requestBody: required: true content: {application/octet-stream: {schema: {type: string, format: binary}}} responses: '200': {description: Stored, content: {application/json: {schema: {type: object, properties: {ok: {type: boolean}, received: {type: integer}, complete: {type: boolean}}}}}} '401': {description: "Credential invalid_token, revoked or expired", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '404': {description: "Unknown transfer, another device's transfer, a wrong token or the wrong direction", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '409': {description: "conflict (the body carries received)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '413': {description: "Over the transfer's size cap", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '422': {description: "checksum_mismatch or invalid", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Rate limited (600 per 60 s per device)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '503': {description: "module_disabled or feature_disabled", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /agent_logs: post: tags: [Endpoint agent] summary: Ship a batch of collected log entries (device credential; log collection switch) description: > Sent only after a check-in response offered logs:collect (the agent announced that capability). At most 200 events and 262144 bytes per request; the server drops what it cannot understand or what exceeds the device's per-minute budget, the device's row cap or the fleet cap and says so in dropped. An event stored before is counted in duplicates, never stored twice, so resending a batch whose answer was lost is safe. Under load shedding (level 1 and up) the answer is 503 unavailable with a jittered Retry-After. At most 30 per 60 s per device. security: [{deviceAuth: []}] requestBody: required: true content: application/json: schema: type: object required: [events] properties: events: type: array maxItems: 200 items: type: object required: [ts, level, message] properties: ts: {type: string, format: date-time} level: {type: string, enum: [critical, error, warning, info, debug, verbose]} source: {type: string, maxLength: 100} event_id: {type: [integer, 'null']} message: {type: string, description: "Truncated to 1024 characters; credential-shaped text is redacted before it is stored"} dropped: {type: integer, minimum: 0} config_version: {type: string} responses: '200': {description: Processed, 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: "Over 256 KiB", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '422': {description: "invalid", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '429': {description: "Rate limited", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} '503': {description: "module_disabled, feature_disabled or unavailable (load shedding)", content: {application/json: {schema: {$ref: '#/components/schemas/AgentError'}}}} /endpoint_devices: get: tags: [Endpoint agent] summary: List endpoint agent devices in the caller's clients description: Needs a user token and RMM (module_rmm) view access. Module-only logins and the legacy shared key 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 clients 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 client. 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 client, 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'}}}} components: securitySchemes: bearerAuth: type: http scheme: bearer description: Token issued by POST /api/v1/auth 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. ApiKeyAuth: type: apiKey in: header name: X-Api-Key description: Legacy instance-wide API key (denied on /credentials and /me) parameters: 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'} schemas: 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} 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, additionalProperties: {type: string}, description: 'Ready-to-use GET /tickets params; a filter with several values is a comma list.'} is_default: {type: boolean, description: 'True for the view the agent opens by default (their personal default, else the shared 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} 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} LineItem: type: object properties: description: {type: string} quantity: {type: number} unit_price: {type: number} total: {type: number} taxable: {type: boolean} QuoteListItem: type: object properties: id: {type: integer} number: {type: string} subject: {type: string} status: {type: string} date: {type: string} total: {type: number} client: {type: string, nullable: true} guest_url: {type: string, nullable: true} QuoteDetail: allOf: - $ref: '#/components/schemas/QuoteListItem' - type: object properties: subtotal: {type: number} tax: {type: number} notes: {type: string} items: {type: array, items: {$ref: '#/components/schemas/LineItem'}} InvoiceListItem: type: object properties: id: {type: integer} number: {type: string} date: {type: string} due_date: {type: string, nullable: true} status: {type: string} total: {type: number} client: {type: string, nullable: true} guest_url: {type: string, nullable: true} InvoiceDetail: allOf: - $ref: '#/components/schemas/InvoiceListItem' - type: object properties: subtotal: {type: number} tax: {type: number} notes: {type: string} items: {type: array, items: {$ref: '#/components/schemas/LineItem'}} Expense: type: object properties: id: {type: integer} description: {type: string} amount: {type: number} currency: {type: string} date: {type: string} reference: {type: string, nullable: true} payment_method: {type: string, nullable: true} has_receipt: {type: boolean} 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)"} Product: type: object properties: id: {type: integer} name: {type: string} type: {type: string, nullable: true} description: {type: string, nullable: true} price: {type: number} currency: {type: string, nullable: true} code: {type: string, nullable: true} 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"'} 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} KbArticleDetail: allOf: - $ref: '#/components/schemas/KbArticleListItem' - type: object properties: content: {type: string} attachments: {type: array, items: {$ref: '#/components/schemas/Attachment'}} 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} 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} Notification: type: object properties: id: {type: integer} type: {type: string} message: {type: string} action: {type: string, nullable: true} timestamp: {type: string} 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]} 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} 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'} 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} 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"} 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}