{ "openapi": "3.1.0", "info": { "title": "ReportMate API", "description": "\n## ReportMate Device Management and Telemetry API\n\nReportMate provides a comprehensive REST API for managing device fleets and collecting telemetry data.\n\n### Features\n- **Device Management**: Query, archive, and delete devices\n- **Fleet Analytics**: Bulk endpoints for hardware, software, network, and security data\n- **Event Logging**: Real-time event ingestion and retrieval\n- **Module Data**: Access individual module data (system, hardware, network, etc.)\n\n### Authentication\nAll endpoints require authentication via one of:\n- `X-Client-Passphrase` header (Windows/macOS clients)\n- `X-Internal-Secret` header (container-to-container)\n- Azure Managed Identity (when Easy Auth is configured)\n\n### Rate Limiting\nAPI requests are subject to rate limiting. Contact support for increased limits.\n ", "contact": { "name": "ReportMate", "url": "https://reportmate.app/" }, "license": { "name": "AGPL-3.0", "url": "https://www.gnu.org/licenses/agpl-3.0.html" }, "version": "1.0.0" }, "paths": { "/api/v1/health": { "get": { "tags": [ "health", "health" ], "summary": "Health Check", "description": "Health check endpoint for monitoring and load balancers.\n\n**No authentication required.**\n\n**Response:**\n- status: \"healthy\" or \"unhealthy\"\n- database: Connection status\n- version: API version", "operationId": "health_check_api_v1_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/api/v1/health/live": { "get": { "tags": [ "health", "health" ], "summary": "Liveness", "description": "Liveness probe -- the process is up and serving.\n\n**No authentication required. No dependencies checked.** Use this as the\nload-balancer/orchestrator liveness target so a transient database outage\ndoes not cause healthy replicas to be killed.", "operationId": "liveness_api_v1_health_live_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/health/ready": { "get": { "tags": [ "health", "health" ], "summary": "Readiness", "description": "Readiness probe -- verifies the API can reach its database.\n\n**No authentication required.** Returns 503 when the database is\nunreachable so orchestrators stop routing traffic to this replica until it\nrecovers. No internal error detail is exposed.", "operationId": "readiness_api_v1_health_ready_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/negotiate": { "get": { "tags": [ "health", "health" ], "summary": "Signalr Negotiate", "description": "SignalR/WebPubSub negotiate endpoint.\n\nGenerates a client access token for Azure Web PubSub connection. The token\ngrants a live view of the fleet event stream, so callers must authenticate;\nthe dashboard reaches this through the BFF proxy, which supplies the\ninternal secret.", "operationId": "signalr_negotiate_api_v1_negotiate_get", "parameters": [ { "name": "device", "in": "query", "required": false, "schema": { "type": "string", "default": "dashboard", "title": "Device" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/devices": { "get": { "tags": [ "devices" ], "summary": "Get All Devices", "description": "List all devices with standardized identification and lightweight module payloads.\n\nBy default, archived devices are excluded from results.\nUse includeArchived=true to show archived devices.\n\n**Query Parameters:**\n- limit: Maximum devices to return (1-1000, default all)\n- offset: Pagination offset\n- includeArchived: Include archived devices (default false)\n\n**Response:**\n- devices: Array of device objects\n- total: Total device count\n- offset: Current pagination offset", "operationId": "get_all_devices_api_v1_devices_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 1000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum devices to return", "title": "Limit" }, "description": "Maximum devices to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of devices to skip for pagination", "default": 0, "title": "Offset" }, "description": "Number of devices to skip for pagination" }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include archived devices", "default": false, "title": "Includearchived" }, "description": "Include archived devices" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/device/{serial_number}": { "get": { "tags": [ "devices" ], "summary": "Get Device By Serial", "description": "Get individual device details with all modules.\n\nUses serialNumber consistently as primary identifier.\nReturns complete device data including all collected module data.\n\n**Path Parameters:**\n- serial_number: Device serial number (e.g., \"ABC123XYZ\")\n\n**Response includes:**\n- Device metadata (serial, UUID, last seen, client version)\n- All module data (inventory, hardware, network, security, etc.)\n- Archive status", "operationId": "get_device_by_serial_api_v1_device__serial_number__get", "parameters": [ { "name": "serial_number", "in": "path", "required": true, "schema": { "type": "string", "title": "Serial Number" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "admin", "devices" ], "summary": "Delete Device", "description": "Permanently delete a device and all its data.\n\n**WARNING: This is a DESTRUCTIVE operation!**\n\nDeletion removes:\n- Device record from devices table\n- Every module row for the device, deleted explicitly: the module tables\n are created by the ingestion path, not by a migration, and none of them\n declares a foreign key to devices, so nothing cascades\n- All events history\n- ALL historical data - cannot be recovered\n\nThis should only be used for:\n- Test devices that should not exist\n- Duplicate records\n- Data cleanup/GDPR compliance\n\n**RECOMMENDATION:** Use archive instead of delete to preserve historical data!\n\nQuery Parameters:\n- confirm: Must be set to true to confirm deletion (safety check)\n\n**Authentication Required:**\n- Windows clients: X-API-PASSPHRASE header\n- Azure resources: X-MS-CLIENT-PRINCIPAL-ID header (Managed Identity)", "operationId": "delete_device_api_v1_device__serial_number__delete", "parameters": [ { "name": "serial_number", "in": "path", "required": true, "schema": { "type": "string", "title": "Serial Number" } }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Confirm" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/device/{serial_number}/installs/log": { "get": { "tags": [ "devices" ], "summary": "Get Device Installs Log", "description": "Get the full run log for the installs module.\n\nThis data is lazy-loaded because it can be very large (MBs of text).", "operationId": "get_device_installs_log_api_v1_device__serial_number__installs_log_get", "parameters": [ { "name": "serial_number", "in": "path", "required": true, "schema": { "type": "string", "title": "Serial Number" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/device/{serial_number}/logs/{tool}": { "get": { "tags": [ "devices" ], "summary": "Get Device Log Root", "description": "Get one management tool's log root, tails included.\n\nThe device and module endpoints strip every root's tail because the tails\nare the bulk of the management module's logs section and only one is wanted at a time. This\nendpoint returns the single root for ``tool`` (installs, bootstrap,\nreports, state, encryption, users, utilities) with its tails intact.", "operationId": "get_device_log_root_api_v1_device__serial_number__logs__tool__get", "parameters": [ { "name": "serial_number", "in": "path", "required": true, "schema": { "type": "string", "title": "Serial Number" } }, { "name": "tool", "in": "path", "required": true, "schema": { "type": "string", "title": "Tool" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/device/{serial_number}/events": { "get": { "tags": [ "devices" ], "summary": "Get Device Events", "description": "Get events for a specific device.\n\nReturns event history for device activity logging and monitoring.\nUsed by EventsTab for displaying device events.\n\n**Query Parameters:**\n- limit: Maximum events to return (default 100)\n- type: Filter by event type - success, warning, error, info, system (optional)", "operationId": "get_device_events_api_v1_device__serial_number__events_get", "parameters": [ { "name": "serial_number", "in": "path", "required": true, "schema": { "type": "string", "title": "Serial Number" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by event type (success, warning, error, info, system)", "title": "Type" }, "description": "Filter by event type (success, warning, error, info, system)" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/device/{serial_number}/info": { "get": { "tags": [ "devices" ], "summary": "Get Device Info Fast", "description": "Fast endpoint returning only InfoTab data for progressive loading.\n\nReturns minimal data needed for immediate display:\n- inventory (device name, serial, etc.)\n- system basics (OS, uptime)\n- hardware summary (model, processor)\n- management status\n- security features\n- network hostname\n\nThis is ~10-20KB vs 100-200KB for full device data\nResponse time: <500ms vs 3-5s for full load", "operationId": "get_device_info_fast_api_v1_device__serial_number__info_get", "parameters": [ { "name": "serial_number", "in": "path", "required": true, "schema": { "type": "string", "title": "Serial Number" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/device/{serial_number}/modules/{module_name}": { "get": { "tags": [ "devices" ], "summary": "Get Device Module", "description": "Get individual module data for progressive/on-demand loading.\n\nSupported modules:\n- applications, hardware, identity, installs, inventory\n- management, network, peripherals, security, system\n\nNote: displays and printers are collected as part of peripherals.\nProfile data is collected as part of management/security.\n\nUsed for:\n1. Background progressive loading (after fast info load)\n2. On-demand loading when user clicks tabs", "operationId": "get_device_module_api_v1_device__serial_number__modules__module_name__get", "parameters": [ { "name": "serial_number", "in": "path", "required": true, "schema": { "type": "string", "title": "Serial Number" } }, { "name": "module_name", "in": "path", "required": true, "schema": { "type": "string", "title": "Module Name" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/device/{serial_number}/applications/usage/history": { "get": { "tags": [ "devices" ], "summary": "Get Device Usage History", "description": "Per-device daily application usage time-series.\nReturns day-by-day usage for a single device, suitable for device detail page charts.", "operationId": "get_device_usage_history_api_v1_device__serial_number__applications_usage_history_get", "parameters": [ { "name": "serial_number", "in": "path", "required": true, "schema": { "type": "string", "title": "Serial Number" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 548, "minimum": 1, "description": "Number of days to look back", "default": 90, "title": "Days" }, "description": "Number of days to look back" }, { "name": "appName", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by application name", "title": "Appname" }, "description": "Filter by application name" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/applications/filters": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Applications Filters", "description": "Lightweight endpoint for application filter options.\n\nReturns unique application names, publishers, categories, and inventory\nfilter values using SQL DISTINCT queries — without downloading all records.\nAlso returns a lightweight device list (serial, name, inventory fields)\nfor the \"missing\" report mode.\n\nThis replaces the pattern of calling /api/devices/applications?loadAll=true\nand processing 200K+ records client-side.", "operationId": "get_applications_filters_api_v1_applications_filters_get", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includearchived" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/applications/usage": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Fleet Applications Usage", "description": "Fleet-wide application usage aggregation from `usage_history`.\n\nAggregates per-app totals across all devices within the lookback window,\nwith optional inventory-based scoping (usages/catalogs/locations) and\nper-app filtering. Returns the shape consumed by the Generate Report ->\nUtilization view on /devices/applications.\n\nWhich number to quote, because two of them look interchangeable and are not:\n\n- **activeHours** is the faculty-facing figure: foreground *and* user input\n within the prior 300s. **totalHours** is summed process lifetime with no\n wall-clock ceiling and is diagnostic only.\n- **activeDeviceCount / activeUserCount** count only devices and users that\n contributed non-zero active time. **deviceCount / userCount** count every\n device and user that produced any usage row at all, including rows that\n are pure background process time.\n- **installedDeviceCount** is the number of in-scope devices whose\n applications inventory lists the app, folded with the same alias rules.\n It is the only install figure here; deviceCount is not one.\n\nFor a licence or seat question, use the active counts. The plain counts\ndescribe installation footprint, which for a background service is close to\nthe whole managed fleet -- Houdini reported 184 devices and 229 users\nagainst 0.5 active hours over 30 days, and Chrome 218 devices against 13\nusers. Both are returned because footprint is a legitimate question; it is\njust not the same question, and the names are the only thing distinguishing\nthem.\n\n`isSingleActiveUser` is the seat-relevant form of `isSingleUser`, which is\nretained unchanged for existing callers.", "operationId": "get_fleet_applications_usage_api_v1_applications_usage_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 548, "minimum": 1, "description": "Lookback window in days", "default": 30, "title": "Days" }, "description": "Lookback window in days" }, { "name": "applicationNames", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated app names to include", "title": "Applicationnames" }, "description": "Comma-separated app names to include" }, { "name": "usages", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory usages", "title": "Usages" }, "description": "Comma-separated inventory usages" }, { "name": "catalogs", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory catalogs", "title": "Catalogs" }, "description": "Comma-separated inventory catalogs" }, { "name": "locations", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory locations", "title": "Locations" }, "description": "Comma-separated inventory locations" }, { "name": "areas", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory areas (department)", "title": "Areas" }, "description": "Comma-separated inventory areas (department)" }, { "name": "fleets", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory fleets", "title": "Fleets" }, "description": "Comma-separated inventory fleets" }, { "name": "rooms", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory rooms", "title": "Rooms" }, "description": "Comma-separated inventory rooms" }, { "name": "platforms", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated platforms (windows/macos)", "title": "Platforms" }, "description": "Comma-separated platforms (windows/macos)" }, { "name": "minHours", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Minimum total hours to include an app", "title": "Minhours" }, "description": "Minimum total hours to include an app" }, { "name": "minLaunches", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "Minimum launch count to include an app", "title": "Minlaunches" }, "description": "Minimum launch count to include an app" }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includearchived" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/applications/usage/by-device": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Application Usage By Device", "description": "Per-device usage breakdown for one application (substring match on name).\n\nReturns one row per device that contributed usage of any app matching the\ngiven name pattern within the lookback window. Backs the drill-down view\nfrom the fleet usage report.", "operationId": "get_application_usage_by_device_api_v1_applications_usage_by_device_get", "parameters": [ { "name": "app", "in": "query", "required": true, "schema": { "type": "string", "description": "Application name pattern (substring, case-insensitive)", "title": "App" }, "description": "Application name pattern (substring, case-insensitive)" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 548, "minimum": 1, "description": "Lookback window in days", "default": 30, "title": "Days" }, "description": "Lookback window in days" }, { "name": "usages", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory usages", "title": "Usages" }, "description": "Comma-separated inventory usages" }, { "name": "catalogs", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory catalogs", "title": "Catalogs" }, "description": "Comma-separated inventory catalogs" }, { "name": "locations", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory locations", "title": "Locations" }, "description": "Comma-separated inventory locations" }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includearchived" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/applications/collection-health": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Applications Collection Health", "description": "Per-device application-usage collection health.\n\nInfers coverage from `usage_history` activity without requiring client\naudit-state telemetry. Each non-archived device is bucketed into:\n - healthy: usage_history row dated within freshDays\n - stale: usage_history row dated within staleDays but older than freshDays\n - dark: has usage_history rows but most recent is older than staleDays\n - never: no usage_history rows ever\n\nUse to spot devices that are silently not collecting (audit policy off\non Windows, watcher daemon missing on Mac, etc.) — they appear in the\n`dark` or `never` buckets.", "operationId": "get_applications_collection_health_api_v1_applications_collection_health_get", "parameters": [ { "name": "freshDays", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Days within which a device is considered healthy", "default": 7, "title": "Freshdays" }, "description": "Days within which a device is considered healthy" }, { "name": "staleDays", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 180, "minimum": 1, "description": "Days beyond which a device is considered dark", "default": 30, "title": "Staledays" }, "description": "Days beyond which a device is considered dark" }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includearchived" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/applications/distribution": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Applications Distribution", "description": "Server-side version distribution for selected applications.\n\nAggregates installed-app counts per (app bucket, version) directly in SQL\nso the response size is bounded by `distinct versions`, not fleet size.\nEach requested app name acts as a case-insensitive substring bucket,\nmirroring the matching used by the bulk applications endpoint, so chips\nselected in the filter UI map 1:1 to chart cards.\n\nA device is counted at most once per (bucket, version) — duplicate app\nentries on a single device (32/64-bit, MSI + Squirrel installers) collapse\ninto one tally so the chart matches \"devices with vX\" rather than\n\"installer rows for vX\".\n\nReturns:\n {\n \"\": {\n \"totalDevices\": , # devices with at least one matching install\n \"versions\": { \"\": , ... }\n },\n ...\n }", "operationId": "get_applications_distribution_api_v1_applications_distribution_get", "parameters": [ { "name": "applicationNames", "in": "query", "required": true, "schema": { "type": "string", "description": "Comma-separated app names to aggregate (required)", "title": "Applicationnames" }, "description": "Comma-separated app names to aggregate (required)" }, { "name": "usages", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory usages", "title": "Usages" }, "description": "Comma-separated inventory usages" }, { "name": "catalogs", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory catalogs", "title": "Catalogs" }, "description": "Comma-separated inventory catalogs" }, { "name": "areas", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory areas (department)", "title": "Areas" }, "description": "Comma-separated inventory areas (department)" }, { "name": "fleets", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory fleets", "title": "Fleets" }, "description": "Comma-separated inventory fleets" }, { "name": "rooms", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory rooms", "title": "Rooms" }, "description": "Comma-separated inventory rooms" }, { "name": "locations", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory locations", "title": "Locations" }, "description": "Comma-separated inventory locations" }, { "name": "platforms", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated platforms (windows/macos)", "title": "Platforms" }, "description": "Comma-separated platforms (windows/macos)" }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includearchived" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/applications": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Bulk Applications", "description": "Bulk applications endpoint with filtering support.\n\nReturns flattened list of applications across all devices with filtering.\nFrontend is responsible for search/filtering logic - this is just data retrieval.\n\nBy default, archived devices are excluded. Use includeArchived=true to include them.", "operationId": "get_bulk_applications_api_v1_applications_get", "parameters": [ { "name": "deviceNames", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Devicenames" } }, { "name": "applicationNames", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applicationnames" } }, { "name": "publishers", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Publishers" } }, { "name": "categories", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Categories" } }, { "name": "versions", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Versions" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } }, { "name": "installDateFrom", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Installdatefrom" } }, { "name": "installDateTo", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Installdateto" } }, { "name": "sizeMin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sizemin" } }, { "name": "sizeMax", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sizemax" } }, { "name": "usages", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory usages", "title": "Usages" }, "description": "Comma-separated inventory usages" }, { "name": "catalogs", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory catalogs", "title": "Catalogs" }, "description": "Comma-separated inventory catalogs" }, { "name": "areas", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory areas (department)", "title": "Areas" }, "description": "Comma-separated inventory areas (department)" }, { "name": "fleets", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory fleets", "title": "Fleets" }, "description": "Comma-separated inventory fleets" }, { "name": "rooms", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory rooms", "title": "Rooms" }, "description": "Comma-separated inventory rooms" }, { "name": "locations", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated inventory locations", "title": "Locations" }, "description": "Comma-separated inventory locations" }, { "name": "platforms", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated platforms (windows/macos)", "title": "Platforms" }, "description": "Comma-separated platforms (windows/macos)" }, { "name": "loadAll", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Loadall" } }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includearchived" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "minimum": 1, "description": "Maximum items to return (default 500, max 5000)", "default": 500, "title": "Limit" }, "description": "Maximum items to return (default 500, max 5000)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip", "default": 0, "title": "Offset" }, "description": "Number of items to skip" }, { "name": "deviceLimit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "minimum": 1, "description": "Maximum devices to scan (default 2000)", "default": 2000, "title": "Devicelimit" }, "description": "Maximum devices to scan (default 2000)" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/hardware": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Bulk Hardware", "description": "Bulk hardware endpoint.\n\nReturns flattened list of hardware details across all devices.\nBy default, archived devices are excluded. Use includeArchived=true to include them.\n\n**Response includes:**\n- Device identifiers (serial number, device ID, name)\n- Hardware specs (manufacturer, model, CPU, memory, storage, GPU)\n- OS information (name, version, architecture)\n- Attached displays, normalized across both clients, keyed for asset inventory\n- Network position: active IP, DNS servers, a physically-on-campus flag,\n and a campus-DNS flag (the two differ over VPN)\n\n**Pagination:** limit and offset are both applied in Python, over the full\nresult set. Pushing limit into the SQL instead -- which this endpoint used\nto do -- silently breaks offset: the query returns the first N rows and the\nslice then takes offset..offset+N *of those*, so any offset >= N answers an\nempty list. A caller paging with a fixed page size sees that empty second\npage, reads it as the end of the list, and stops with a partial result and\nno error. Measured against a live deployment: a page size of 500 returned\n500 records and every offset at or above 500 returned nothing.", "operationId": "get_bulk_hardware_api_v1_hardware_get", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include archived devices in results", "default": false, "title": "Includearchived" }, "description": "Include archived devices in results" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 5000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum items to return", "title": "Limit" }, "description": "Maximum items to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip", "default": 0, "title": "Offset" }, "description": "Number of items to skip" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/installs/filters": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Installs Filters", "description": "Lightweight endpoint for installs filter options.\n\nReturns unique managed install names, inventory filter values, config metadata,\nand a lightweight device list with pre-computed status counts.\n\nThis replaces downloading the full /api/devices/installs/full (52MB+) just\nto extract filter options client-side.", "operationId": "get_installs_filters_api_v1_installs_filters_get", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includearchived" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/installs": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Bulk Installs", "description": "Bulk installs endpoint for Cimian managed packages.\n\nReturns flattened list of managed installs across all devices.\nBy default, archived devices are excluded. Use includeArchived=true to include them.\n\n**Response includes:**\n- Device identifiers and inventory data\n- Cimian package status (item name, version, update status)\n- Install dates and last check timestamps", "operationId": "get_bulk_installs_api_v1_installs_get", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include archived devices in results", "default": false, "title": "Includearchived" }, "description": "Include archived devices in results" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 5000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum items to return", "title": "Limit" }, "description": "Maximum items to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip", "default": 0, "title": "Offset" }, "description": "Number of items to skip" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/installs/full": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Bulk Installs Full", "description": "Bulk installs endpoint returning FULL device records with nested structure.\n\nUnlike /api/devices/installs (flat items), this returns devices with complete\nmodules.installs structure including config, version, sessions etc.\nUsed by /devices/installs page for full UI rendering.\n\nBy default, archived devices are excluded. Use includeArchived=true to include them.", "operationId": "get_bulk_installs_full_api_v1_installs_full_get", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includearchived" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 5000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum items to return", "title": "Limit" }, "description": "Maximum items to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip", "default": 0, "title": "Offset" }, "description": "Number of items to skip" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/network": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Bulk Network", "description": "Bulk network endpoint for fleet-wide network overview.\n\nReturns devices with network configuration data (interfaces, IPs, MACs, DNS, etc.).\nUsed by /devices/network page for fleet-wide network visibility.\nBy default, archived devices are excluded. Use includeArchived=true to include them.\n\n**Response includes:**\n- Device identifiers and inventory\n- Network interfaces, IP addresses, MAC addresses\n- DNS configuration, gateways, and network type", "operationId": "get_bulk_network_api_v1_network_get", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include archived devices in results", "default": false, "title": "Includearchived" }, "description": "Include archived devices in results" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 5000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum items to return", "title": "Limit" }, "description": "Maximum items to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip", "default": 0, "title": "Offset" }, "description": "Number of items to skip" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/security": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Bulk Security", "description": "Bulk security endpoint for fleet-wide security overview.\n\nReturns devices with security configuration (TPM, BitLocker, EDR, AV, etc.).\nUsed by /devices/security page for fleet-wide security visibility.\nBy default, archived devices are excluded. Use includeArchived=true to include them.\n\n**Response includes:**\n- Device identifiers and inventory\n- TPM status, BitLocker encryption state\n- EDR/AV status and configuration\n- Firewall and security baseline compliance", "operationId": "get_bulk_security_api_v1_security_get", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include archived devices in results", "default": false, "title": "Includearchived" }, "description": "Include archived devices in results" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 5000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum items to return", "title": "Limit" }, "description": "Maximum items to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip", "default": 0, "title": "Offset" }, "description": "Number of items to skip" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/security/certificates": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Search Fleet Certificates", "description": "Fleet-wide certificate search endpoint.\n\nSearches across all device certificates for matching commonName, issuer, subject, or serialNumber.\nUseful for verifying certificate deployment across the fleet or finding expired certificates.\n\n**Parameters:**\n- search: Text to search for (case-insensitive, partial match)\n- status: Filter by cert status (all, valid, expired, expiring)\n- limit: Maximum results to return (default 1000, hard cap 10000)\n- includeArchived: Include archived devices", "operationId": "search_fleet_certificates_api_v1_security_certificates_get", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Search term to match against certificate commonName, issuer, subject, or serialNumber", "default": "", "title": "Search" }, "description": "Search term to match against certificate commonName, issuer, subject, or serialNumber" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by certificate status: all, valid, expired, expiring", "default": "all", "title": "Status" }, "description": "Filter by certificate status: all, valid, expired, expiring" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "description": "Maximum results to return (max 10000)", "default": 1000, "title": "Limit" }, "description": "Maximum results to return (max 10000)" }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include archived devices in results", "default": false, "title": "Includearchived" }, "description": "Include archived devices in results" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/management": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Bulk Management", "description": "Bulk management endpoint for fleet-wide MDM status.\n\nReturns devices with MDM enrollment status and management configuration.\nUsed by /devices/management page for fleet-wide MDM visibility.\nBy default, archived devices are excluded. Use includeArchived=true to include them.\n\n**Response includes:**\n- Device identifiers and inventory\n- MDM enrollment status (Enrolled/Not Enrolled)\n- Provider, enrollment type, Intune ID\n- Tenant information", "operationId": "get_bulk_management_api_v1_management_get", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include archived devices in results", "default": false, "title": "Includearchived" }, "description": "Include archived devices in results" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 5000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum items to return", "title": "Limit" }, "description": "Maximum items to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip", "default": 0, "title": "Offset" }, "description": "Number of items to skip" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/inventory": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Bulk Inventory", "description": "Bulk inventory endpoint for fleet-wide device inventory.\n\nReturns devices with inventory metadata (names, asset tags, locations, usage, etc.).\nUsed by /devices/inventory page for fleet-wide inventory management.\nBy default, archived devices are excluded. Use includeArchived=true to include them.\n\n**Response includes:**\n- Device identifiers (serial number, device ID)\n- Asset information (name, tag, location, department)\n- Usage classification and catalog assignment", "operationId": "get_bulk_inventory_api_v1_inventory_get", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include archived devices in results", "default": false, "title": "Includearchived" }, "description": "Include archived devices in results" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 5000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum items to return", "title": "Limit" }, "description": "Maximum items to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip", "default": 0, "title": "Offset" }, "description": "Number of items to skip" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/system": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Bulk System", "description": "Bulk system endpoint for fleet-wide OS and system information.\n\nReturns devices with OS details, uptime, updates, services, etc.\nUsed by /devices/system page for fleet-wide system visibility.\nBy default, archived devices are excluded. Use includeArchived=true to include them.\n\nlimit/offset page the response, matching /management and /installs/full. Omitting\nlimit returns every device; a fixed default would truncate the fleet silently once\nit grew past that number, which is the failure this endpoint already had.\n\n**Response includes:**\n- Device identifiers and inventory\n- Operating system name, version, build number\n- System uptime, boot time\n- Pending-update counts and normalized installed-update identities\n- Service and scheduled-task counts", "operationId": "get_bulk_system_api_v1_system_get", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include archived devices in results", "default": false, "title": "Includearchived" }, "description": "Include archived devices in results" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 5000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum items to return", "title": "Limit" }, "description": "Maximum items to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip", "default": 0, "title": "Offset" }, "description": "Number of items to skip" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/peripherals": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Bulk Peripherals", "description": "Bulk peripherals endpoint for fleet-wide peripheral devices.\n\nReturns devices with connected peripherals (USB, input devices, audio, Bluetooth, cameras, etc.).\nUsed by /devices/peripherals page for fleet-wide peripheral visibility.\nBy default, archived devices are excluded. Use includeArchived=true to include them.\n\n**Response includes:**\n- Device identifiers and inventory\n- USB devices (hubs, storage, peripherals)\n- Input devices (keyboards, mice, trackpads, graphics tablets)\n- Audio devices (speakers, microphones)\n- Bluetooth devices (paired and connected)\n- Cameras (built-in and external)\n- Thunderbolt devices (docks, displays, storage)\n- Printers (CUPS, network, direct-connect)\n- Scanners\n- External storage (USB drives, SD cards)", "operationId": "get_bulk_peripherals_api_v1_peripherals_get", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include archived devices in results", "default": false, "title": "Includearchived" }, "description": "Include archived devices in results" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 5000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum items to return", "title": "Limit" }, "description": "Maximum items to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip", "default": 0, "title": "Offset" }, "description": "Number of items to skip" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/identity": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Bulk Identity", "description": "Bulk identity endpoint for fleet-wide user account and identity data.\n\nReturns devices with user accounts, groups, sessions, BTMDB health, and directory services.\nUsed by /devices/identity page for fleet-wide identity visibility.\nBy default, archived devices are excluded. Use includeArchived=true to include them.\n\n**Response includes:**\n- Device identifiers and inventory\n- User accounts (local, domain, Apple ID linked)\n- User groups and memberships\n- Login sessions and history\n- BTMDB health (macOS background task management database)\n- Directory services (AD, Open Directory, LDAP)\n- Secure Token users\n- Platform SSO registration status", "operationId": "get_bulk_identity_api_v1_identity_get", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include archived devices in results", "default": false, "title": "Includearchived" }, "description": "Include archived devices in results" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 5000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum items to return", "title": "Limit" }, "description": "Maximum items to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip", "default": 0, "title": "Offset" }, "description": "Number of items to skip" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/profiles": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Bulk Profiles", "description": "Bulk profiles endpoint for fleet-wide MDM profile and configuration data.\n\nReturns devices with MDM profiles, configuration profiles, and management settings.\nUsed by /devices/profiles page for fleet-wide profile visibility.\nBy default, archived devices are excluded. Use includeArchived=true to include them.", "operationId": "get_bulk_profiles_api_v1_profiles_get", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include archived devices in results", "default": false, "title": "Includearchived" }, "description": "Include archived devices in results" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 5000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum items to return", "title": "Limit" }, "description": "Maximum items to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip", "default": 0, "title": "Offset" }, "description": "Number of items to skip" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/management/logs/{tool}": { "get": { "tags": [ "fleet", "fleet" ], "summary": "Get Fleet Log Lines", "description": "Sweep one management tool's log tails across the whole fleet.\n\n``tool`` is a log root key (installs, bootstrap, reports, state, encryption,\nusers, utilities, notifications, mdm, installer). Every device's tails for\nthat root are read straight from the management module in Postgres; when\n``levels`` excludes info the narrowing happens in the query, so a sweep for\nerrors and warnings ships only those lines. Each result carries the device,\nthe root's facts and the matching lines with their file and level;\n``summary=true`` adds the message patterns behind them, normalised so the\nsame fault on many devices is one row with a device count.", "operationId": "get_fleet_log_lines_api_v1_management_logs__tool__get", "parameters": [ { "name": "tool", "in": "path", "required": true, "schema": { "type": "string", "title": "Tool" } }, { "name": "levels", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated levels to return: error, warning, info, debug (default error,warning)", "title": "Levels" }, "description": "Comma-separated levels to return: error, warning, info, debug (default error,warning)" }, { "name": "platform", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "windows or macos", "title": "Platform" }, "description": "windows or macos" }, { "name": "file", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only lines from this file within the root, e.g. run.log", "title": "File" }, "description": "Only lines from this file within the root, e.g. run.log" }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case-insensitive substring the line must contain", "title": "Q" }, "description": "Case-insensitive substring the line must contain" }, { "name": "summary", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Also return fleet-wide message patterns (same fault on many devices counted once)", "default": false, "title": "Summary" }, "description": "Also return fleet-wide message patterns (same fault on many devices counted once)" }, { "name": "maxLinesPerDevice", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "minimum": 1, "default": 200, "title": "Maxlinesperdevice" } }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includearchived" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 5000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum devices to return", "title": "Limit" }, "description": "Maximum devices to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/events": { "get": { "tags": [ "events", "events" ], "summary": "Get Events", "description": "Get recent events with device names (optimized for dashboard).\n\nReturns lightweight event list with device context for fast dashboard rendering.\n**Note:** Full event payload is NOT included - use `/api/events/{id}/payload` for details.\n\n**Query Parameters:**\n- limit: Maximum events to return (1-1000, default 100)\n- offset: Number of events to skip (for pagination, default 0)\n- startDate: Filter events after this ISO8601 date (optional)\n- endDate: Filter events before this ISO8601 date (optional)\n- type: Filter by event type(s). Single value (e.g. `error`) or comma-separated (e.g. `success,warning,error,system`)\n\n**Response includes:**\n- Event ID, type, message, timestamp\n- Device serial number and name\n- Total count for pagination", "operationId": "get_events_api_v1_events_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of events to return", "default": 100, "title": "Limit" }, "description": "Maximum number of events to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of events to skip (for pagination)", "default": 0, "title": "Offset" }, "description": "Number of events to skip (for pagination)" }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter events after this ISO8601 date", "title": "Startdate" }, "description": "Filter events after this ISO8601 date" }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter events before this ISO8601 date", "title": "Enddate" }, "description": "Filter events before this ISO8601 date" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by event type (success, warning, error, info, system)", "title": "Type" }, "description": "Filter by event type (success, warning, error, info, system)" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "events", "events" ], "summary": "Submit Events", "description": "Submit device events and unified module data.\n\nThis endpoint handles:\n- Device registration/update\n- Module data storage (system, hardware, installs, network, etc.)\n- Event creation for tracking\n\nExpected payload structure:\n{\n \"metadata\": {\n \"deviceId\": \"UUID\",\n \"serialNumber\": \"SERIAL\",\n \"collectedAt\": \"ISO8601\",\n \"clientVersion\": \"version\",\n \"platform\": \"Windows|macOS\",\n \"collectionType\": \"Full|Single\",\n \"enabledModules\": [\"system\", \"hardware\", ...]\n },\n \"events\": [...], # Optional event messages\n \"system\": {...}, # Module data (top-level keys)\n \"hardware\": {...},\n \"installs\": {...},\n ...\n}", "operationId": "submit_events_api_v1_events_post", "parameters": [ { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/events/failures": { "get": { "tags": [ "events", "events" ], "summary": "Get Ingest Failures", "description": "Rejected device check-ins (failed registrations).\n\nEvery device request that was turned away -- bad or missing credentials,\nmalformed payload, invalid serial -- is recorded with whatever identity\nthe device presented. This answers \"the client was installed but the\ndevice never appeared\": if the machine reached the server at all, it is\nlisted here with the reason it was rejected.\n\nReason codes: auth -> invalid_passphrase, invalid_api_key,\ninvalid_bearer_token, invalid_internal_secret, missing_credentials,\ninsufficient_scope; validation -> upload_aborted, body_unreadable,\nempty_body, malformed_json, invalid_payload, empty_serial,\nsentinel_serial, short_serial, hostname_serial, serial_equals_hostname,\nnul_in_payload, usage_out_of_bounds; throttle -> rate_limited;\nserver_error -> internal_error, usage_write_failed.\n\nrate_limited and internal_error are recorded at the status the caller\nactually received. usage_write_failed is recorded at 500 even though the\ncheck-in returned 200: the device was not turned away, but its usage rows\nwere lost server-side, and data loss belongs in the default view rather\nthan filed under repairs. nul_in_payload and usage_out_of_bounds are recorded at\n200 -- the check-in was accepted, but it carried a client defect worth\nseeing.\n\nThose two are therefore NOT failures, and ``outcome`` keeps them out of a\nview whose whole promise is \"these devices did not get through\". A client\ndefect that the server repairs can be several thousand rows a day -- large\nenough to bury the handful of genuinely rejected devices this page exists\nto surface -- while still being worth watching until the client-side fix\nrolls out.\n\nupload_aborted / body_unreadable / empty_body are transport failures --\nthe device reached the server but its payload did not arrive intact.\nmalformed_json means a body that arrived and did not parse. The detail\ncarries declared vs received byte counts so the two stay separable.\n\nA transport failure is only a failed check-in if nothing arrived\nafterwards. Both clients make up to three attempts per check-in, 1s then\n2s apart (MaxRetryAttempts), and the next scheduled run sends again if\nthose are spent. A dropped upload is therefore normally resent down a\nfresh connection seconds later and the data lands; counting the dropped\nattempt as a device that was turned away describes an outage that is not\nhappening. A transport row whose device\nhas a later successful check-in is therefore ``retried``, not\n``rejected``. Only transport reasons qualify: a malformed body or a bad\npassphrase is resent identically, so a later success says nothing about\nthat check-in.\n\noutcome is derived from the recorded status and the server-side successful\ningest watermark rather than a stored flag, so it reads correctly over\nhistory as well, and a row reclassifies as soon as the device gets back in.\ncounts.rejected / counts.retried / counts.accepted are always all present\nso the other sides are one click away rather than invisible.", "operationId": "get_ingest_failures_api_v1_events_failures_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of failures to return", "default": 100, "title": "Limit" }, "description": "Maximum number of failures to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of failures to skip (for pagination)", "default": 0, "title": "Offset" }, "description": "Number of failures to skip (for pagination)" }, { "name": "serial", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by serial number (case-insensitive substring)", "title": "Serial" }, "description": "Filter by serial number (case-insensitive substring)" }, { "name": "reason", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by rejection reason code", "title": "Reason" }, "description": "Filter by rejection reason code" }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 2160, "minimum": 1, "description": "Look-back window in hours (default 7 days)", "default": 168, "title": "Hours" }, "description": "Look-back window in hours (default 7 days)" }, { "name": "outcome", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(rejected|retried|accepted|all)$", "description": "rejected (default) = turned away and nothing has arrived since; retried = the upload dropped but the client's retry landed; accepted = kept but repaired on the way in; all = every recorded row", "default": "rejected", "title": "Outcome" }, "description": "rejected (default) = turned away and nothing has arrived since; retried = the upload dropped but the client's retry landed; accepted = kept but repaired on the way in; all = every recorded row" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/events/{event_id}/payload": { "get": { "tags": [ "events", "events" ], "summary": "Get Event Payload", "description": "Get the FULL payload for a specific event including related module data.\n\nThis endpoint is called when user clicks to expand an event in the dashboard.\nIt fetches the event details AND the actual module data from the module tables.", "operationId": "get_event_payload_api_v1_events__event_id__payload_get", "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Event Id" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/dashboard": { "get": { "tags": [ "statistics", "statistics" ], "summary": "Get Dashboard Data", "description": "Consolidated dashboard endpoint - fetches all dashboard data in a single API call.\n\nCombines:\n- All devices with full OS data (eliminates need for individual device fetches)\n- Install statistics (devicesWithErrors, devicesWithWarnings, totalFailedInstalls)\n- Recent events (for dashboard event widget)\n\nThis eliminates 10+ separate API calls from the dashboard, dramatically improving load time.\n\nReturns:\n {\n \"devices\": [...], # Full device list with OS data\n \"totalDevices\": int, # Total device count\n \"installStats\": {...}, # Install error/warning counts\n \"events\": [...], # Recent events for widget\n \"totalEvents\": int, # Total recent events count\n \"lastUpdated\": str # ISO8601 timestamp\n }", "operationId": "get_dashboard_data_api_v1_dashboard_get", "parameters": [ { "name": "eventsLimit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 200, "title": "Eventslimit" } }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Includearchived" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/device/{serial_number}/archive": { "patch": { "tags": [ "admin", "devices" ], "summary": "Archive Device", "description": "Archive a device (soft delete).\n\nArchived devices:\n- Are hidden from all bulk endpoints by default\n- Still exist in database with all module data intact\n- Can be unarchived later\n- Do NOT receive new data submissions (rejected at ingestion)\n\nThis is useful for:\n- Decommissioned devices\n- Devices being retired/replaced\n- Test devices no longer needed\n- Keeping historical data while hiding from active reports\n\n**Authentication Required:**\n- Windows clients: X-API-PASSPHRASE header\n- Azure resources: X-MS-CLIENT-PRINCIPAL-ID header (Managed Identity)", "operationId": "archive_device_api_v1_device__serial_number__archive_patch", "parameters": [ { "name": "serial_number", "in": "path", "required": true, "schema": { "type": "string", "title": "Serial Number" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/device/{serial_number}/unarchive": { "patch": { "tags": [ "admin", "devices" ], "summary": "Unarchive Device", "description": "Unarchive a device (restore from soft delete).\n\nUnarchived devices:\n- Become visible in all bulk endpoints again\n- Can receive new data submissions\n- Restore to 'active' status\n- Retain all historical data\n\n**Authentication Required:**\n- Windows clients: X-API-PASSPHRASE header\n- Azure resources: X-MS-CLIENT-PRINCIPAL-ID header (Managed Identity)", "operationId": "unarchive_device_api_v1_device__serial_number__unarchive_patch", "parameters": [ { "name": "serial_number", "in": "path", "required": true, "schema": { "type": "string", "title": "Serial Number" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/admin/usage-history/date-anomalies": { "get": { "tags": [ "admin", "admin" ], "summary": "Usage History Date Anomalies", "description": "Rows in usage_history whose `date` could not have been produced by a\nhealthy client.\n\nRead-only. Exists because neither the fleet nor the per-device usage\nendpoint can see these rows: both clamp their lookback to 548 days, so a\nrow dated 1976 is invisible to every normal query while still being\ncounted by aggregates that scan the whole table.\n\nTwo buckets, each a different defect:\n\n- **tooOld** - a date below the floor. A client cannot have observed usage\n before it existed, so this is a parsing or conversion fault.\n- **inFuture** - a date after today. Usually a device clock, but it also\n lands rows in windows that have not happened yet, where they will be\n silently included the moment the window arrives.\n\n`updated_at` is the field that matters when reading the result: it is when\nthe row was last written, so it separates a historical mess that a baseline\nreset will clear from a fault that is still occurring and will simply\nrepopulate.", "operationId": "usage_history_date_anomalies_api_v1_admin_usage_history_date_anomalies_get", "parameters": [ { "name": "floor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Rows dated before this YYYY-MM-DD are implausible (default: 548 days ago, the API's own lookback ceiling)", "title": "Floor" }, "description": "Rows dated before this YYYY-MM-DD are implausible (default: 548 days ago, the API's own lookback ceiling)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum sample rows returned per bucket", "default": 100, "title": "Limit" }, "description": "Maximum sample rows returned per bucket" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/admin/usage-history/integrity": { "get": { "tags": [ "admin", "admin" ], "summary": "Usage History Integrity", "description": "Physical-plausibility check over recent usage_history rows, per platform.\n\nThe accuracy checks that gated September collection were run by hand\nagainst the fleet endpoints and per-device histories. This is the same\ncheck as one query so a timer can run it every day through the term and\nsay out loud when a client regression starts inflating the record again.\n\nEverything here is a hard physical bound, not a heuristic:\n\n- a duration cannot be negative;\n- foreground cannot exceed total, and active cannot exceed foreground,\n beyond one second of rounding slack;\n- a device cannot accumulate more than 24 hours of foreground or active\n time in one calendar day, summed across its applications.\n\nThe per-platform block for the last complete day gives the day's shape\n(devices with rows, foreground and active hours per device, launches) so\na check that passes the bounds still shows whether the fleet moved.\ntotal_seconds is process lifetime with no wall-clock ceiling and is not\nchecked against the day; see the usage endpoint for why it is not a\nreportable figure.", "operationId": "usage_history_integrity_api_v1_admin_usage_history_integrity_get", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "description": "Lookback window in days, by row date", "default": 7, "title": "Days" }, "description": "Lookback window in days, by row date" }, { "name": "sample", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Maximum offending device-days returned", "default": 20, "title": "Sample" }, "description": "Maximum offending device-days returned" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/admin/usage-history/export": { "get": { "tags": [ "admin", "admin" ], "summary": "Usage History Export", "description": "Stream usage_history rows for a date range as CSV.\n\nusage_history is the one table a device cannot re-report: every other\nmodule row is a current-state snapshot that self-heals on the next\ncheck-in. This is the read side of its archive -- the alerts app pulls\neach closed month through here and writes it to blob storage, so the\nrecord outlives the database's backup window.\n\nHalf-open range ``[from, to)`` on the row date, ordered by date, device\nand application so two exports of the same range are byte-identical.\nRows stream from a server-side cursor in batches; a month of the current\nfleet is a few hundred thousand rows and never sits in memory at once.", "operationId": "usage_history_export_api_v1_admin_usage_history_export_get", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "description": "First row date to include, YYYY-MM-DD", "title": "From" }, "description": "First row date to include, YYYY-MM-DD" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "description": "First row date to exclude, YYYY-MM-DD", "title": "To" }, "description": "First row date to exclude, YYYY-MM-DD" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/admin/usage-history/reset-baseline": { "post": { "tags": [ "admin", "admin" ], "summary": "Reset Usage History Baseline", "description": "Archive and remove usage_history rows before a cutoff date.\n\nWith ``device`` the reset is limited to those serial numbers, for the case\nwhere one client build wrote bad rows and the rest of the fleet is sound.\n\n**This is a DESTRUCTIVE operation on the live reporting table.**\n\nWhy it exists: usage_history accumulates client-sent window deltas, so a\nclient-side counting defect is written into the table permanently and\ncannot be recomputed from anything the server still holds. Correcting one\nmeans removing the affected rows. Every row is copied verbatim into\nusage_history_archive first, so the reset is recoverable and \"what did we\nreport before\" stays answerable.\n\nNot the same as /admin/usage-history/cleanup, which enforces a minimum\nretention of one month and exists for routine ageing-out. This takes an\nexplicit cutoff so a term baseline can start clean, and it archives rather\nthan discards.\n\nWithout ``confirm=true`` this returns a preview of exactly what would be\naffected and changes nothing. Run the preview first.", "operationId": "reset_usage_history_baseline_api_v1_admin_usage_history_reset_baseline_post", "parameters": [ { "name": "before", "in": "query", "required": true, "schema": { "type": "string", "description": "Archive and remove rows dated before this YYYY-MM-DD (exclusive)", "title": "Before" }, "description": "Archive and remove rows dated before this YYYY-MM-DD (exclusive)" }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Must be true to execute; otherwise a preview is returned", "default": false, "title": "Confirm" }, "description": "Must be true to execute; otherwise a preview is returned" }, { "name": "reason", "in": "query", "required": false, "schema": { "type": "string", "description": "Recorded on the archived rows so a batch can be identified later", "default": "", "title": "Reason" }, "description": "Recorded on the archived rows so a batch can be identified later" }, { "name": "device", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Limit the reset to these serial numbers; repeat for several", "title": "Device" }, "description": "Limit the reset to these serial numbers; repeat for several" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/admin/usage-history/cleanup": { "delete": { "tags": [ "admin", "admin" ], "summary": "Cleanup Usage History", "description": "Delete usage_history rows older than the specified retention period.\nDefault retention: 18 months. Call via scheduled task or manually.", "operationId": "cleanup_usage_history_api_v1_admin_usage_history_cleanup_delete", "parameters": [ { "name": "months", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 36, "minimum": 1, "description": "Retain data for this many months", "default": 18, "title": "Months" }, "description": "Retain data for this many months" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/admin/installs/clear-errors": { "delete": { "tags": [ "admin", "admin" ], "summary": "Clear Stale Installs Errors", "description": "Clear error and warning fields from installs data for stale devices.\n\nTargets devices that have not checked in (devices.last_seen) for the\nspecified number of days. Clears per-item error/warning fields in Cimian data and\nerror/warning strings in Munki data.\n\nThis is a manual maintenance operation - not automated.\n\n**Authentication Required:**\n- Windows clients: X-API-PASSPHRASE header\n- Azure resources: X-MS-CLIENT-PRINCIPAL-ID header (Managed Identity)", "operationId": "clear_stale_installs_errors_api_v1_admin_installs_clear_errors_delete", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 365, "minimum": 0, "description": "Clear errors/warnings from devices that have not reported in this many days; 0 clears every device (they re-report their true state on the next check-in)", "default": 10, "title": "Days" }, "description": "Clear errors/warnings from devices that have not reported in this many days; 0 clears every device (they re-report their true state on the next check-in)" }, { "name": "item_age_days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 365, "minimum": 0 }, { "type": "null" } ], "description": "Also clear individual errors/warnings whose own last attempt is older than this many days, on devices that ARE still checking in. Keying only on device check-in leaves week-old failures on machines that phone home daily.", "title": "Item Age Days" }, "description": "Also clear individual errors/warnings whose own last attempt is older than this many days, on devices that ARE still checking in. Keying only on device check-in leaves week-old failures on machines that phone home daily." }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/admin/installs/reclassify": { "post": { "tags": [ "admin", "admin" ], "summary": "Reclassify Stored Installs", "description": "Re-run the install-item classifier over stored installs rows.\n\nEvery item carries the state ingest decided for it, and the four counter\ncolumns the dashboard reads are stamped at the same moment. Both therefore\nreflect whatever the classifier said on that device's last check-in, so a\nchange to the classifier reaches a device only when it next reports — up to\nan hour for a lab machine, and far longer for a laptop that sleeps.\n\nThis applies the current classifier to what is already stored, so the fleet\nagrees with the code immediately. It is the same two functions ingest calls,\nnot a second implementation, and it is idempotent: a row whose stamps and\ncounters already match is left untouched, so the JSONB is not rewritten and\nthe TOAST churn that would come with it is avoided.\n\nBatched and manual, never automated — the database is IOPS-constrained and a\ntable-wide rewrite belongs off the request path of every other caller.\n\n**Authentication Required:**\n- Windows clients: X-API-PASSPHRASE header\n- Azure resources: X-MS-CLIENT-PRINCIPAL-ID header (Managed Identity)", "operationId": "reclassify_stored_installs_api_v1_admin_installs_reclassify_post", "parameters": [ { "name": "batch", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Rows to read per batch; the write is one statement per changed row", "default": 200, "title": "Batch" }, "description": "Rows to read per batch; the write is one statement per changed row" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Stop after this many rows, for a rehearsal against part of the fleet", "title": "Limit" }, "description": "Stop after this many rows, for a rehearsal against part of the fleet" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/admin/orphans": { "get": { "tags": [ "admin", "admin" ], "summary": "Orphaned Module Rows", "description": "Module rows whose device no longer exists.\n\nEvery fleet-wide query joins a module table to ``devices``, so a module row\nwhose ``device_id`` matches no device contributes to nothing: its errors are\nabsent from the dashboard tiles, its items from the installs page, its\napplications from the inventory. The row is still there, still counted by\nthe reclassify pass, and still invisible.\n\nThey should not exist -- ingest writes the device row before any module row,\nand deleting a device cascades -- so a non-zero count here is evidence of a\ndelete that did not cascade, or of a device row whose id and serial number\ndisagree. Read-only: this reports them and removes nothing.", "operationId": "orphaned_module_rows_api_v1_admin_orphans_get", "parameters": [ { "name": "samples", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 0, "default": 5, "title": "Samples" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "admin", "admin" ], "summary": "Delete Orphaned Module Rows", "description": "Delete the module rows of specific orphaned device ids.\n\nDeliberately not a blanket sweep. An orphan is a module row whose device\nrow is gone, and the reason it is gone matters: a machine that is still in\ninventory and might check in again deserves to keep its history, while a\ntest id or a hostname-keyed duplicate does not. So the caller names the ids,\nhaving decided that, and this refuses any id that is not actually an orphan\n-- naming a live device deletes nothing.\n\nIrreversible, and separate from ``DELETE /device/{serial}``, which is for\ndevices that still exist.\n\n**Authentication Required:**\n- Windows clients: X-API-PASSPHRASE header\n- Azure resources: X-MS-CLIENT-PRINCIPAL-ID header (Managed Identity)", "operationId": "delete_orphaned_module_rows_api_v1_admin_orphans_delete", "parameters": [ { "name": "device_ids", "in": "query", "required": true, "schema": { "type": "string", "description": "Comma-separated device ids to clean up; each must be an orphan", "title": "Device Ids" }, "description": "Comma-separated device ids to clean up; each must be an orphan" }, { "name": "confirm", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Must be true to delete", "default": false, "title": "Confirm" }, "description": "Must be true to delete" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/debug/database": { "get": { "tags": [ "admin", "admin" ], "summary": "Debug Database", "description": "Database diagnostic endpoint - analyze storage usage and data cleanup opportunities.\n\nThis endpoint helps identify:\n1. Duplicate records per device that should only have 1 row per module\n2. Orphaned records for devices that no longer exist\n3. Historical data retention issues\n4. Table bloat from dead tuples", "operationId": "debug_database_api_v1_debug_database_get", "parameters": [ { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/settings": { "get": { "tags": [ "settings", "settings" ], "summary": "Get Settings", "description": "Return the org-scoped settings document.\n\nWhen no document exists yet, returns ``{\"exists\": false, \"value\": null}`` so\nthe client can trigger first-time onboarding.", "operationId": "get_settings_api_v1_settings_get", "parameters": [ { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "settings", "settings" ], "summary": "Put Settings", "description": "Replace the org-scoped settings document.\n\nRestricted to internal-service callers (the Next.js proxy, which enforces the\nadmin role). The fleet passphrase and managed identities cannot reach this.", "operationId": "put_settings_api_v1_settings_put", "parameters": [ { "name": "X-Updated-By", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Updated-By" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/settings/inventory/discover": { "get": { "tags": [ "settings", "settings" ], "summary": "Discover Inventory Keys", "description": "Discover the inventory keys present across the fleet, with sample values.\n\nRestricted to internal-service callers (the admin-gated proxy), since the\nsample values can expose inventory data. Powers the onboarding wizard's\nfield-mapping step so admins can map whatever keys their Inventory.yaml emits.", "operationId": "discover_inventory_keys_api_v1_settings_inventory_discover_get", "parameters": [ { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include archived devices in discovery", "default": false, "title": "Include Archived" }, "description": "Include archived devices in discovery" }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/admin/api-keys": { "post": { "tags": [ "admin", "admin" ], "summary": "Create Api Key", "description": "Mint a new API key. The full key is returned once and never stored.", "operationId": "create_api_key_api_v1_admin_api_keys_post", "parameters": [ { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKey" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "admin", "admin" ], "summary": "List Api Keys", "description": "List API keys (metadata only; secrets are never returned).", "operationId": "list_api_keys_api_v1_admin_api_keys_get", "parameters": [ { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/admin/api-keys/{key_id}": { "delete": { "tags": [ "admin", "admin" ], "summary": "Revoke Api Key", "description": "Revoke a key (soft delete -- sets active=false; the audit row remains).", "operationId": "revoke_api_key_api_v1_admin_api_keys__key_id__delete", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" } }, { "name": "X-API-PASSPHRASE", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Passphrase" } }, { "name": "X-Client-Passphrase", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Client-Passphrase" } }, { "name": "X-Internal-Secret", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Internal-Secret" } }, { "name": "X-MS-CLIENT-PRINCIPAL-ID", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Ms-Client-Principal-Id" } }, { "name": "X-API-Key", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Api-Key" } }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "title": "Authorization" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "type": "string", "title": "X-Forwarded-For" } }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string", "title": "User-Agent" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/auth/config": { "get": { "tags": [ "auth" ], "summary": "Auth Config", "description": "Which credentials this deployment accepts, and the OIDC details a\nclient needs to mint a bearer token for it.", "operationId": "auth_config_api_v1_auth_config_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/": { "get": { "tags": [ "health" ], "summary": "Root", "description": "API root endpoint with service information.", "operationId": "root__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } } }, "components": { "schemas": { "CreateApiKey": { "properties": { "client_id": { "type": "string", "minLength": 1, "title": "Client Id", "description": "Human label / owner of the key" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes", "description": "Subset of read/ingest/admin" } }, "type": "object", "required": [ "client_id" ], "title": "CreateApiKey" }, "DeviceInfo": { "properties": { "serialNumber": { "type": "string", "title": "Serialnumber" }, "deviceId": { "type": "string", "title": "Deviceid" }, "deviceName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Devicename" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "hostname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hostname" }, "lastSeen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lastseen" }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Createdat" }, "registrationDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registrationdate" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "assetTag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assettag" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Platform" }, "osName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Osname" }, "osVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Osversion" }, "usage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Usage" }, "catalog": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Catalog" }, "department": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Department" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner" }, "lastEventTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lasteventtime" }, "totalEvents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Totalevents" }, "inventory": { "anyOf": [ { "$ref": "#/components/schemas/InventorySummary" }, { "type": "null" } ] }, "modules": { "anyOf": [ { "$ref": "#/components/schemas/DeviceModules" }, { "type": "null" } ] } }, "type": "object", "required": [ "serialNumber", "deviceId" ], "title": "DeviceInfo", "description": "Device information with database schema mapping." }, "DeviceModules": { "properties": { "system": { "anyOf": [ { "$ref": "#/components/schemas/SystemModule" }, { "type": "null" } ] }, "inventory": { "anyOf": [ { "$ref": "#/components/schemas/InventorySummary" }, { "type": "null" } ] } }, "type": "object", "title": "DeviceModules", "description": "Device modules container for bulk endpoint." }, "DeviceOS": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "build": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Build" }, "major": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Major" }, "minor": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Minor" }, "patch": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Patch" }, "edition": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Edition" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version" }, "featureUpdate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Featureupdate" }, "displayVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Displayversion" }, "architecture": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Architecture" }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Locale" }, "timeZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timezone" }, "installDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Installdate" } }, "type": "object", "title": "DeviceOS", "description": "Operating System information model." }, "DevicesResponse": { "properties": { "devices": { "items": { "$ref": "#/components/schemas/DeviceInfo" }, "type": "array", "title": "Devices" }, "total": { "type": "integer", "title": "Total" }, "message": { "type": "string", "title": "Message" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "pageSize": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pagesize" }, "hasMore": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Hasmore" } }, "type": "object", "required": [ "devices", "total", "message" ], "title": "DevicesResponse", "description": "Response model for bulk devices endpoint." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HealthResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "timestamp": { "type": "string", "title": "Timestamp" }, "database": { "type": "string", "title": "Database" }, "version": { "type": "string", "title": "Version" }, "deviceIdStandard": { "type": "string", "title": "Deviceidstandard", "default": "serialNumber" } }, "type": "object", "required": [ "status", "timestamp", "database", "version" ], "title": "HealthResponse", "description": "Response from /api/health." }, "InventorySummary": { "properties": { "deviceName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Devicename" }, "assetTag": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Assettag" }, "serialNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Serialnumber" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location" }, "department": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Department" }, "usage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Usage" }, "catalog": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Catalog" }, "owner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner" }, "fleet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fleet" } }, "type": "object", "title": "InventorySummary", "description": "Trimmed inventory data returned in bulk responses." }, "SystemModule": { "properties": { "operatingSystem": { "anyOf": [ { "$ref": "#/components/schemas/DeviceOS" }, { "type": "null" } ] } }, "type": "object", "title": "SystemModule", "description": "System module data model." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Per-client scoped API key (`rm__`), carrying read / ingest / admin scopes. Preferred." }, "ClientPassphrase": { "type": "apiKey", "in": "header", "name": "X-Client-Passphrase", "description": "Shared client passphrase (Windows/macOS agents; legacy)." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OIDC bearer token (provider-agnostic federated SSO)." } } }, "tags": [ { "name": "health", "description": "Health checks and status endpoints" }, { "name": "devices", "description": "Device management operations - list, get, archive, delete devices" }, { "name": "fleet", "description": "Fleet-wide bulk data endpoints for analytics dashboards" }, { "name": "events", "description": "Event logging, retrieval, and real-time notifications" }, { "name": "statistics", "description": "Fleet analytics, usage statistics, and reporting" }, { "name": "admin", "description": "Administrative operations and diagnostics" }, { "name": "settings", "description": "Server-side org settings: inventory mapping and security rules" } ], "security": [ { "ApiKeyAuth": [] }, { "ClientPassphrase": [] }, { "BearerAuth": [] } ] }