{ "schemes": [], "swagger": "2.0", "info": { "description": "API for managing devices, fleets, configurations, and rollouts.\n\n## Authentication - choose one of two methods\n\nAdmiral supports **two independent authentication methods**. Pick the one that fits your use case. You do **not** combine them.\n\n| | Personal API Token (PAT) | Service Account (OAuth2) |\n|---|---|---|\n| **Identity** | Tied to your user account | Independent machine identity |\n| **Best for** | Quick scripts, personal use | CI/CD, integrations, automation |\n| **Survives you leaving?** | No - dies with your account | Yes |\n| **Permissions** | Inherits your user access | Granted via IAM policies |\n| **Credential** | Token ID + Secret Key (long-lived) | Short-lived bearer token from client credentials |\n| **Headers used** | `X-API-Token-ID` + `X-API-Secret-Key` | `Authorization: Bearer ...` |\n\nSet the method's credentials in the **Authorize** button (top right).\n\n---\n\n### Method 1 - Personal API Token (PAT)\nTied to your user account; inherits your permissions. Generate from the Admiral web UI under **Settings > API Tokens**. The secret is shown only once.\n\nIn the **Authorize** dialog, fill in both:\n- `ApiTokenAuth` → your `X-API-Token-ID`\n- `ApiSecretAuth` → your `X-API-Secret-Key`\n\n### Method 2 - Service Account (OAuth2 client credentials)\nThe recommended method for automated systems. A service account is a machine identity with policy-scoped access. See **IAM > Service Accounts** in the web UI, or read the full guide at https://docs.admrl.co/automation/service-accounts.\n\nFirst exchange your client credentials for a short-lived bearer token:\n```\ncurl -X POST https://api.admrl.co/v1/oauth/token -H \"Content-Type: application/x-www-form-urlencoded\" -d \"grant_type=client_credentials\" -d \"client_id=$CLIENT_ID\" -d \"client_secret=$CLIENT_SECRET\"\n```\nThen in the **Authorize** dialog fill in `BearerAuth` with the full value: `Bearer eyJhbGci...`\n\n---\n\n### Organisation context (both methods)\nMost endpoints require an organisation context. Provide it in the `X-Organization-ID` header:\n```\nX-Organization-ID: your-organisation-id\n```\n\n---\n\n### Need more help?\nFor a complete guide to creating service accounts, minting and rotating keys, scoping access with policies, and full code examples, see the **[Service Accounts documentation](https://docs.admrl.co/automation/service-accounts)**.", "title": "Admiral API", "termsOfService": "https://admrl.co/terms/", "contact": { "name": "API Support", "url": "https://app.admrl.co/help", "email": "support@admrl.co" }, "version": "1.0" }, "host": "api.admrl.co", "basePath": "/v1", "paths": { "/assistant/chat/completions": { "post": { "description": "Streaming (SSE) OpenAI-style chat completions served by the Admiral-hosted assistant model. Portal sessions only; requires the X-Organization-ID header. The body is validated strictly (roles, text content, the Admiral tool allow-list, size caps) and the dashboard system prompt is required.", "consumes": [ "application/json" ], "produces": [ "text/event-stream" ], "tags": [ "Assistant" ], "summary": "Admiral Assistant chat completions", "parameters": [ { "type": "string", "description": "Organization ID", "name": "X-Organization-ID", "in": "header", "required": true } ], "responses": { "200": { "description": "SSE stream of chat.completion.chunk events", "schema": { "type": "string" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "402": { "description": "Payment Required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "413": { "description": "Request Entity Too Large", "schema": { "$ref": "#/definitions/controllers.Response" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/controllers.Response" } }, "502": { "description": "Bad Gateway", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/assistant/usage": { "get": { "description": "Budget decision, period-to-date tokens by class and daily fair-use allowance (percent used) for the Admiral-hosted assistant; staff also get the upstream daily cost. Portal sessions only.", "produces": [ "application/json" ], "tags": [ "Assistant" ], "summary": "Admiral Assistant usage", "parameters": [ { "type": "string", "description": "Organization ID", "name": "X-Organization-ID", "in": "header", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.AssistantUsageResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/audit-events": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Audit" ], "summary": "List audit events", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "minimum": 1, "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "maximum": 1000, "minimum": 1, "type": "integer", "default": 50, "description": "Items per page", "name": "limit", "in": "query" }, { "type": "string", "description": "Start time (RFC3339)", "name": "from", "in": "query" }, { "type": "string", "description": "End time (RFC3339)", "name": "to", "in": "query" }, { "type": "string", "description": "Filter by HTTP method", "name": "method", "in": "query" }, { "type": "string", "description": "Filter by request path prefix", "name": "pathPrefix", "in": "query" }, { "type": "string", "description": "Filter by actor user ID", "name": "actorUserId", "in": "query" } ], "responses": { "200": { "description": "Paginated audit events", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing organisation context or invalid query params", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "500": { "description": "Failed to load audit events", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/billing/edgewire/usage": { "get": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "Billing" ], "summary": "Get measured EdgeWire usage", "parameters": [ { "type": "string", "description": "Organisation", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "RFC3339 or date, default last 30 days", "name": "from", "in": "query" }, { "type": "string", "description": "Inclusive RFC3339 or date", "name": "to", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/edgewireusagerepo.Summary" } } } ] } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/billing/edgewire/usage/records": { "get": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "Billing" ], "summary": "Get measured EdgeWire usage records", "parameters": [ { "type": "string", "description": "Organisation", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "RFC3339 or date", "name": "from", "in": "query" }, { "type": "string", "description": "Inclusive RFC3339 or date", "name": "to", "in": "query" }, { "type": "integer", "description": "1-200, default 50", "name": "limit", "in": "query" }, { "type": "string", "description": "Opaque cursor", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "Service Unavailable", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/billing/features": { "get": { "security": [ { "BearerAuth": [] }, { "ApiSecretAuth": [], "ApiTokenAuth": [] } ], "description": "Returns which paid features (telemetry, signature_policy, usb_policy, audit_log) are enabled for the organisation, whether each is self-serve, and whether the account is enterprise. All feature keys are always present.", "produces": [ "application/json" ], "tags": [ "Billing" ], "summary": "Get organisation feature entitlements", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true } ], "responses": { "200": { "description": "Feature state", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/billingservice.FeaturesView" } } } ] } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/billing/features/{feature}": { "put": { "security": [ { "BearerAuth": [] }, { "ApiSecretAuth": [], "ApiTokenAuth": [] } ], "description": "Switch a self-serve feature (telemetry) on or off for the organisation. Requires the billing admin role. Enterprise features (signature_policy, usb_policy, audit_log) answer 400. The organisation must have a billing profile (409 otherwise).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Billing" ], "summary": "Enable or disable a paid feature", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "enum": [ "telemetry", "signature_policy", "usb_policy" ], "type": "string", "description": "Feature", "name": "feature", "in": "path", "required": true }, { "description": "Desired state", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.SetFeatureRequest" } } ], "responses": { "200": { "description": "Updated feature state", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/billingservice.FeaturesView" } } } ] } }, "400": { "description": "Invalid body or feature is not self-serve", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Requires billing admin", "schema": { "$ref": "#/definitions/controllers.Response" } }, "409": { "description": "Billing not set up", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/billing/pricing": { "get": { "security": [ { "BearerAuth": [] }, { "ApiSecretAuth": [], "ApiTokenAuth": [] } ], "description": "Returns every billable product with the price that applies to this organisation now (price is null when not set). Read-only; available while the account is billing-locked.", "produces": [ "application/json" ], "tags": [ "Billing" ], "summary": "Get billing pricing for the organisation", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true } ], "responses": { "200": { "description": "Pricing", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/billing.PricingView" } } } ] } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Billing profile not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/billing/registry-fallback": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Every fleet in the organisation with whether the registry proxy (registry fallback) is on and the data it carried over the period, plus organisation totals and a daily series. Switched-on fleets come first. `start` and `end` are UTC dates (YYYY-MM-DD) or RFC 3339 timestamps, end exclusive; the default is the current UTC month to date. Needs billing viewer on the organisation.", "produces": [ "application/json" ], "tags": [ "Image Proxy" ], "summary": "Get registry fallback across the organisation", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Period start", "name": "start", "in": "query" }, { "type": "string", "description": "Period end (exclusive)", "name": "end", "in": "query" } ], "responses": { "200": { "description": "Overview", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/imageproxyadminservice.OrgOverview" } } } ] } }, "400": { "description": "Invalid period", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/billing/usage": { "get": { "security": [ { "BearerAuth": [] }, { "ApiSecretAuth": [], "ApiTokenAuth": [] } ], "description": "Returns usage and cost for the current billing period (or the given range), priced exactly as the invoice would price it. from and to accept RFC3339 or YYYY-MM-DD; a bare to date includes that whole UTC day. The range must not exceed 400 days. Read-only; available while the account is billing-locked.", "produces": [ "application/json" ], "tags": [ "Billing" ], "summary": "Get billing usage for the organisation", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Range start (RFC3339 or YYYY-MM-DD)", "name": "from", "in": "query" }, { "type": "string", "description": "Range end, inclusive (RFC3339 or YYYY-MM-DD)", "name": "to", "in": "query" } ], "responses": { "200": { "description": "Usage", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/billing.UsageView" } } } ] } }, "400": { "description": "Invalid date range", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Billing profile not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/cli/edgewire/entitlements": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "The organisation's EdgeWire flags and limits (defaults applied): whether sessions are enabled, whether the TURN relay may be used, and the per-device, per-session and bandwidth limits. An organisation that was never entitled gets enabled=false.", "produces": [ "application/json" ], "tags": [ "EdgeWire" ], "summary": "Get EdgeWire entitlements", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true } ], "responses": { "200": { "description": "EdgeWire entitlements", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/billing.EdgeWireEntitlements" } } } ] } }, "400": { "description": "Missing organisation context", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "Not available on this deployment", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/cli/edgewire/session": { "post": { "security": [ { "EdgeWireToken": [] } ], "description": "Authorises the caller (OpenFGA edgewire relation, organisation entitlement, account state), signs a grant, hands it to the device (cmd.\u003cid\u003e.ew.open) and returns the grant, the device's ICE answer and a NATS signalling JWT. Errors carry error_code: edgewire_not_entitled, no_device_identity, too_many_sessions, device_unreachable (504), target_not_configured (404 before the device is asked, 409 when the device refuses), ssh_disabled, device_unsupported, device_busy and limit_exceeded (429), grant_rejected (500, a backend bug), device_rejected (502 with the device's reason).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "EdgeWire" ], "summary": "Open an EdgeWire session", "parameters": [ { "description": "Session request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.cliEdgeWireRequest" } } ], "responses": { "200": { "description": "Session", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.cliEdgeWireResponse" } } } ] } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Not signed in", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "No access or not entitled", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device not found or without an EdgeWire identity", "schema": { "$ref": "#/definitions/controllers.Response" } }, "409": { "description": "Device refused: target not configured, disabled or unsupported", "schema": { "$ref": "#/definitions/controllers.Response" } }, "429": { "description": "Session limit reached or device busy", "schema": { "$ref": "#/definitions/controllers.Response" } }, "502": { "description": "Device refused the session for another reason", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "EdgeWire is not configured", "schema": { "$ref": "#/definitions/controllers.Response" } }, "504": { "description": "Device unreachable", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/cli/edgewire/session/{sid}": { "delete": { "security": [ { "EdgeWireToken": [] } ], "description": "Tells the device to drop the session (cmd.\u003cid\u003e.ew.close) and forgets it. Only the session's own principal may close it.", "produces": [ "application/json" ], "tags": [ "EdgeWire" ], "summary": "Close an EdgeWire session", "parameters": [ { "type": "string", "description": "Session ID", "name": "sid", "in": "path", "required": true } ], "responses": { "200": { "description": "Closed", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Not signed in", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Session not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/cli/edgewire/session/{sid}/renew": { "post": { "security": [ { "EdgeWireToken": [] } ], "description": "Re-runs the authorisation, entitlement and account checks and returns the presented grant with a new validity window (same session, same keys). Send the result on the session's control stream.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "EdgeWire" ], "summary": "Renew an EdgeWire grant", "parameters": [ { "type": "string", "description": "Session ID", "name": "sid", "in": "path", "required": true }, { "description": "Current grant", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.cliEdgeWireRenewRequest" } } ], "responses": { "200": { "description": "Renewed grant", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.cliEdgeWireRenewResponse" } } } ] } }, "400": { "description": "Invalid grant", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Not signed in", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "No access or not entitled", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Session not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/configurations": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get a paginated list of configurations for an organisation. NOTE: This handler emits a non-standard envelope where `pagination` is a sibling of `data` rather than nested inside it.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "List configurations", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 10, "description": "Items per page", "name": "limit", "in": "query" }, { "type": "string", "description": "Search by name or description", "name": "search", "in": "query" }, { "type": "string", "description": "Filter by status", "name": "status", "in": "query" }, { "type": "string", "description": "Sort field", "name": "sortBy", "in": "query" }, { "type": "string", "description": "Sort order", "name": "sortOrder", "in": "query" } ], "responses": { "200": { "description": "Paginated configuration summaries with pagination metadata as a sibling of data", "schema": { "$ref": "#/definitions/controllers.ListConfigurationsEnvelope" } }, "400": { "description": "Organisation context header missing or invalid", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have permission to list configurations in this organisation", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "500": { "description": "Failed to query configurations", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } }, "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Create a new configuration with an initial specification. Unknown fields are rejected. `spec.ports[].port` is an integer between 1 and 65535 (a numeric string is accepted for backwards compatibility).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "Create configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Configuration details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CreateConfigurationRequest" } } ], "responses": { "201": { "description": "Configuration created with its initial version", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/configuration.Configuration" } } } ] } }, "400": { "description": "Validation failure: missing organisation context, malformed JSON, unrecognised field, missing name, missing/invalid spec, or referenced entity does not belong to the organisation", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have permission to create configurations in this organisation", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "409": { "description": "A configuration with this name already exists in the organisation", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "500": { "description": "Failed to persist configuration", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/configurations/summary": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get a summarised, fully-paginated list of configurations. Defaults to page 1, limit 10 if values are missing or invalid. NOTE: This handler emits a non-standard envelope where `pagination` is a sibling of `data` rather than nested inside it.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "List configuration summaries", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 10, "description": "Items per page", "name": "limit", "in": "query" }, { "type": "string", "description": "Search term", "name": "search", "in": "query" }, { "type": "string", "description": "Filter by status", "name": "status", "in": "query" }, { "type": "string", "description": "Sort field", "name": "sortBy", "in": "query" }, { "type": "string", "description": "Sort order", "name": "sortOrder", "in": "query" } ], "responses": { "200": { "description": "Configuration summaries with sibling pagination metadata", "schema": { "$ref": "#/definitions/controllers.ListConfigurationsEnvelope" } }, "400": { "description": "Organisation context header missing or invalid pagination parameters", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have permission to list configurations in this organisation", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "500": { "description": "Failed to query configurations", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/configurations/{configId}": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get a configuration's metadata by ID.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "Get configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Configuration ID (UUID)", "name": "configId", "in": "path", "required": true } ], "responses": { "200": { "description": "Configuration metadata", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Invalid configId format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Configuration not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Update configuration metadata (name, description, tags) or create a new version by providing a spec. If `spec` is supplied a new version is created and metadata fields are ignored on this call; otherwise at least one metadata field must be supplied. Unknown fields are rejected.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "Update configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Configuration ID (UUID)", "name": "configId", "in": "path", "required": true }, { "description": "Update details (metadata fields and/or spec)", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UpdateConfigurationRequestBody" } } ], "responses": { "200": { "description": "Configuration updated; either a new version was created or metadata was patched", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/configuration.Configuration" } } } ] } }, "400": { "description": "Missing/invalid configuration ID, missing organisation context, malformed JSON, unrecognised field, invalid spec, or no updatable fields supplied", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have permission to modify this configuration", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "500": { "description": "Failed to persist configuration update", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } }, "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Remove a configuration from the system. Fails if the configuration is currently in use.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "Delete configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Configuration ID (UUID)", "name": "configId", "in": "path", "required": true } ], "responses": { "200": { "description": "Configuration deleted successfully", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing/invalid configuration ID or organisation context", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have permission to delete this configuration", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "409": { "description": "Configuration is currently in use (deployed to one or more fleets) and cannot be deleted", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "500": { "description": "Failed to delete configuration", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/configurations/{configId}/details": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get configuration metadata along with the full specification of its latest version.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "Get configuration with latest spec", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Configuration ID (UUID)", "name": "configId", "in": "path", "required": true } ], "responses": { "200": { "description": "Configuration metadata, the latest spec, and full version info bundled together", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ConfigurationWithLatestVersionResponse" } } } ] } }, "400": { "description": "Missing/invalid configuration ID or organisation context", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this configuration", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Configuration does not exist in this organisation", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to load configuration or its latest version", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/configurations/{configId}/document": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Kubernetes-shaped Configuration document: spec is the latest version spec; status lists versions, fleets and devicesByVersion.", "produces": [ "application/json", "application/yaml" ], "tags": [ "Configurations" ], "summary": "Get configuration document", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Configuration ID (UUID)", "name": "configId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.ConfigurationDocument" } }, "404": { "description": "Configuration not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Replace the Configuration spec; a changed spec creates a new configuration version (X-Change-Reason recorded).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "Replace configuration document", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "resourceVersion", "name": "If-Match", "in": "header" }, { "type": "string", "format": "uuid", "description": "Configuration ID (UUID)", "name": "configId", "in": "path", "required": true }, { "description": "Configuration document", "name": "document", "in": "body", "required": true, "schema": { "$ref": "#/definitions/documentservice.ConfigurationDocument" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.ConfigurationDocument" } }, "409": { "description": "resourceVersion mismatch", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "patch": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "RFC 7386 JSON merge patch over the Configuration document.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "Patch configuration document", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "resourceVersion", "name": "If-Match", "in": "header" }, { "type": "string", "format": "uuid", "description": "Configuration ID (UUID)", "name": "configId", "in": "path", "required": true }, { "description": "Merge patch", "name": "patch", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.ConfigurationDocument" } } } } }, "/configurations/{configId}/document:render": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Revision and diff of an optional candidate Configuration document against the latest version, plus the fleets that use it.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "Render configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Configuration ID (UUID)", "name": "configId", "in": "path", "required": true }, { "description": "Candidate document", "name": "document", "in": "body", "schema": { "$ref": "#/definitions/documentservice.ConfigurationDocument" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.ConfigurationRenderResult" } } } } }, "/configurations/{configId}/duplicate": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Creates a new configuration whose version 1 is a copy of the source's latest (or the requested) version, with the source's tags. Secret files are not copied. Needs viewer on the source and config_creator on the organisation; signature policy and registry credential checks apply as for create.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "Duplicate a configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Source configuration ID (UUID)", "name": "configId", "in": "path", "required": true }, { "description": "New configuration", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/configservice.DuplicateConfigRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/configservice.DuplicateConfigResult" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "402": { "description": "Signature policy needs the signature_policy feature", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/configurations/{configId}/rollback": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Create a new version of the configuration by rolling back to a previous version's specification. Accepts either `target_version` or the legacy alias `version`.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "Rollback configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Configuration ID (UUID)", "name": "configId", "in": "path", "required": true }, { "description": "Rollback details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.RollbackConfigurationRequest" } } ], "responses": { "200": { "description": "Rollback applied; a new version was created mirroring the target version's spec", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.RollbackConfigurationResponse" } } } ] } }, "400": { "description": "Missing/invalid configuration ID, missing organisation context, malformed JSON, unrecognised field, or target_version less than 1", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have permission to modify this configuration", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "500": { "description": "Failed to roll back configuration", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/configurations/{configId}/secret-files": { "get": { "responses": {} }, "post": { "description": "Multipart (fields path, mode, uid, gid, file) or JSON (path, mode, uid, gid, content_base64). Content is encrypted with OpenBao and never returned.", "tags": [ "Configurations" ], "summary": "Upload a configuration secret file", "responses": {} } }, "/configurations/{configId}/secret-files/{fileId}": { "delete": { "responses": {} } }, "/configurations/{configId}/spec": { "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Update the container spec for a configuration, creating a new version. `spec` is required. `spec.ports[].port` is an integer between 1 and 65535 (a numeric string is still accepted for backwards compatibility). Unknown fields are rejected so a typo can never be silently dropped into a new version.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "Update configuration spec", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Configuration ID (UUID)", "name": "configId", "in": "path", "required": true }, { "description": "New configuration spec", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UpdateConfigurationSpecRequest" } } ], "responses": { "200": { "description": "Configuration spec updated (new version created)", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/configuration.Configuration" } } } ] } }, "400": { "description": "Missing/invalid configId, malformed JSON, unrecognised field, missing spec, or invalid spec (image/port/protocol)", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Configuration not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to persist configuration spec", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/configurations/{configId}/status": { "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Change the lifecycle status of a configuration (e.g., Draft, Active, Archived). `status` is required and must be one of the documented enum values.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "Update configuration status", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Configuration ID (UUID)", "name": "configId", "in": "path", "required": true }, { "description": "New status", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UpdateConfigurationStatusRequest" } } ], "responses": { "200": { "description": "Configuration status updated", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/configuration.Configuration" } } } ] } }, "400": { "description": "Missing/invalid configuration ID, missing organisation context, malformed JSON, unrecognised field, or status not one of Draft/Active/Testing/Deprecated/Archived", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have permission to modify this configuration", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Configuration not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to persist status change", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/configurations/{configId}/versions": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get all versions of a configuration, newest first.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "List configuration versions", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Configuration ID (UUID)", "name": "configId", "in": "path", "required": true } ], "responses": { "200": { "description": "Configuration version history", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/configuration.ConfigurationVersion" } } } } ] } }, "400": { "description": "Invalid configId format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Configuration not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to load configuration versions", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/configurations/{configId}/versions/{version}": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get a specific version of a configuration by version number.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Configurations" ], "summary": "Get configuration version", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Configuration ID (UUID)", "name": "configId", "in": "path", "required": true }, { "minimum": 1, "type": "integer", "description": "Version number", "name": "version", "in": "path", "required": true } ], "responses": { "200": { "description": "Configuration version", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/configuration.ConfigurationVersion" } } } ] } }, "400": { "description": "Invalid configId or version number", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Configuration or version not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to load configuration version", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get a paginated list of devices with filtering and search. The response envelope adds `pagination` and `counts` siblings to the standard `data` field.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "List devices", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 10, "description": "Items per page", "name": "limit", "in": "query" }, { "type": "string", "description": "Search term", "name": "search", "in": "query" }, { "type": "string", "description": "Filter by status", "name": "status", "in": "query" }, { "type": "string", "format": "uuid", "description": "Filter by fleet ID (UUID)", "name": "fleet_id", "in": "query" }, { "type": "string", "description": "Sort field", "name": "sort", "in": "query" }, { "type": "string", "description": "Sort direction", "name": "direction", "in": "query" } ], "responses": { "200": { "description": "Paginated device list with online/offline counts", "schema": { "$ref": "#/definitions/controllers.ListHostsEnvelope" } }, "400": { "description": "Missing organisation context or invalid fleet_id", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Caller does not have access to the requested fleet/organisation", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Failed to query devices", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/batch/delete": { "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Delete up to 100 devices in a single request.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Bulk delete devices", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Device IDs to delete", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.BulkDeleteHostsRequest" } } ], "responses": { "200": { "description": "Bulk delete completed", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.BulkDeleteHostsResponse" } } } ] } }, "400": { "description": "Parsing issues", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/bulk-claim": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Claim up to 50 registered hosts into an organisation.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Bulk claim hosts", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Bulk claim payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.BulkClaimHostRequest" } } ], "responses": { "200": { "description": "All devices claimed successfully", "schema": { "$ref": "#/definitions/controllers.BulkClaimHostAllSuccessResponse" } }, "207": { "description": "Partial success", "schema": { "$ref": "#/definitions/controllers.BulkClaimHostPartialResponse" } }, "400": { "description": "Every device failed", "schema": { "$ref": "#/definitions/controllers.BulkClaimHostAllFailedResponse" } } } } }, "/devices/claim": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Claim a registered host into an organisation.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Claim host", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Claim payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.ClaimHostRequest" } } ], "responses": { "200": { "description": "Host claimed successfully", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ClaimHostResponse" } } } ] } }, "401": { "description": "Identity required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "409": { "description": "Device conflict", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/validate-pairing-key": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Check whether a pairing key is valid without consuming it.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Validate pairing key", "parameters": [ { "description": "Pairing key", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.ValidatePairingKeyRequest" } } ], "responses": { "200": { "description": "Validation result", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ValidatePairingKeyResponse" } } } ] } }, "400": { "description": "Missing pairing_key", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get detailed information for a specific device.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device details", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Device detail", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.HostDetailResponse" } } } ] } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Update device properties such as name, location, tags, notes, or the screenshots_disabled switch. Changing screenshots_disabled pushes the new setting to the device.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Update device", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Update payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UpdateHostRequest" } } ], "responses": { "200": { "description": "Device updated successfully", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.UpdateHostResponse" } } } ] } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Unpair and delete a device.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Delete device", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "boolean", "description": "Force deletion even if device is unreachable", "name": "force", "in": "query" }, { "type": "string", "default": "reset_identity", "description": "Action to perform on the device", "name": "decommission_action", "in": "query" } ], "responses": { "200": { "description": "Device deleted successfully", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.DeleteHostResponse" } } } ] } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/available-versions": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "List component versions available for a device based on its architecture. Shows current versions and available updates.", "tags": [ "Devices" ], "summary": "List Available Versions for Device", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "enum": [ "initram", "rootfs", "modules" ], "type": "string", "description": "Component type (initram, rootfs, modules)", "name": "component", "in": "query" } ], "responses": { "200": { "description": "Component versions available for the device's architecture", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/system.AvailableVersionsResponse" } } } ] } }, "400": { "description": "Missing or invalid device ID in path", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to list available versions", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/configuration": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get the effective configuration for a host (fleet config + host overrides). The version number reflects the upstream fleet configuration version.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get host configuration", "parameters": [ { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Effective host configuration including any host-level override", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/hostservice.HostConfigurationResponse" } } } ] } }, "401": { "description": "Identity required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Host does not exist", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Create or update a host-specific configuration override. Overrides are unversioned and applied on top of the fleet configuration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Update host configuration override", "parameters": [ { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Configuration override", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UpdateHostConfigurationRequest" } } ], "responses": { "200": { "description": "Host configuration override created or updated", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.UpdateHostConfigurationResponse" } } } ] } }, "400": { "description": "Malformed input paylaod", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Identity required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/configuration/override": { "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Remove host-specific overrides and revert to fleet configuration only.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Clear host configuration override", "parameters": [ { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "Reason for clearing override", "name": "reason", "in": "query" } ], "responses": { "200": { "description": "Host configuration override cleared", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ClearHostConfigurationResponse" } } } ] } }, "401": { "description": "Identity required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "patch": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "RFC 7386 merge patch of the stored override; null resets a field to inherit. Empty results clear the override.", "consumes": [ "application/json", "application/merge-patch+json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Patch host configuration override", "parameters": [ { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "Change reason", "name": "X-Change-Reason", "in": "header" }, { "type": "string", "description": "Change reason (header wins)", "name": "reason", "in": "query" }, { "description": "Sparse override merge patch", "name": "patch", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/hostservice.HostConfigurationResponse" } } } ] } }, "400": { "description": "Invalid merge patch", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Identity required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/device-stats": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get comprehensive statistics for a device, including CPU, memory, disk, network, and container metrics.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device statistics", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "Comma-separated list of metrics to include (cpu,memory,disk,network,container,processes,battery,gpu,health)", "name": "include_metrics", "in": "query" } ], "responses": { "200": { "description": "Comprehensive device metrics snapshot", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.DeviceStatsResponse" } } } ] } }, "400": { "description": "Missing/invalid device ID or organisation context", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device stats not available or device does not exist", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to retrieve device statistics from the metric service", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/diagnose": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "One-call verdict from stored data only (nothing round-trips to the device): online, workload state, transition age, health score, top issue, a severity-ordered issue list (offline, crash loop, OOM, stuck transition, unexpected reboot, WebSocket fallback, disk, RTC drift, pending trial, failed updates, version floor breach, crash-like logs, notable events) with evidence, the last reboot, and the distilled signals. Crash-like log detection matches the CLI and MCP diagnose exactly.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Diagnose device", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/documentservice.Diagnosis" } } } ] } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } } } } }, "/devices/{deviceId}/diagnostics/probe": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Runs the structured diagnostics probe on the device (network, time, identity, wireless, storage, boot, thermal, workload, services, gpu) and returns the report. Items marked sensitive are returned with value [redacted] unless the caller is Admiral platform staff. The network section includes packet loss and path quality (loss to the gateway, DNS server and cloud, per-hop loss, interface errors) on agents that report them; networkVerdict then names the likely cause (local link, upstream ISP/WAN, DNS path, resolver, NIC errors) with evidence and confidence, and is omitted when nothing in the network section is wrong.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Run device diagnostics probe", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Sections and timeout", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.ProbeRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ProbeReport" } } } ] } }, "429": { "description": "rate_limited: one probe per 5 s per device, shared by every caller (Retry-After)", "schema": { "$ref": "#/definitions/devicestate.CommsErrorBody" } }, "503": { "description": "device_offline", "schema": { "$ref": "#/definitions/devicestate.CommsErrorBody" } }, "504": { "description": "device_timeout", "schema": { "$ref": "#/definitions/devicestate.CommsErrorBody" } } } } }, "/devices/{deviceId}/document": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Kubernetes-shaped Device document (apiVersion admrl.co/v1): metadata with generation and resourceVersion, the writable spec, and the observed status. Send Accept application/yaml for YAML. The ETag header carries the resourceVersion for If-Match.", "produces": [ "application/json", "application/yaml" ], "tags": [ "Devices" ], "summary": "Get device document", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.DeviceDocument" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Replace the Device spec. If-Match (or metadata.resourceVersion) must equal the current resourceVersion, else 409. Writes go through the existing services (fleet move, override, network, screenshots, USB policy), bump metadata.generation and push the rendered desired state. spec.workload.from, spec.system.updates and spec.secrets are read-only here. X-Admrl-Push reports sent, failed, skipped or unavailable.", "consumes": [ "application/json", "application/yaml" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Replace device document", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "resourceVersion", "name": "If-Match", "in": "header" }, { "type": "string", "description": "Recorded in the override history", "name": "X-Change-Reason", "in": "header" }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Device document", "name": "document", "in": "body", "required": true, "schema": { "$ref": "#/definitions/documentservice.DeviceDocument" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.DeviceDocument" } }, "400": { "description": "Validation failed", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/documentservice.ValidationError" } } } ] } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "409": { "description": "resourceVersion mismatch", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "patch": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "RFC 7386 JSON merge patch over the Device document (Content-Type application/merge-patch+json), e.g. {\"spec\":{\"fleet\":\"\u003cfleetId\u003e\"}}. Same rules as PUT.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Patch device document", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "resourceVersion", "name": "If-Match", "in": "header" }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Merge patch", "name": "patch", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.DeviceDocument" } }, "400": { "description": "Validation failed", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/documentservice.ValidationError" } } } ] } }, "409": { "description": "resourceVersion mismatch", "schema": { "$ref": "#/definitions/controllers.Response" } }, "415": { "description": "Unsupported patch type", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/document:adoptLocalOverride": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Copy the device's local override (edited on the device via TUI, BLE or console) into the spec: network goes to spec.network. Bumps generation and pushes; the device then clears its override. Paths the backend cannot store yet are listed in notAdopted.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Adopt device local override", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "resourceVersion", "name": "If-Match", "in": "header" }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.AdoptResult" } }, "409": { "description": "No local override, or resourceVersion mismatch", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/document:discardLocalOverride": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Send the device a desired-state push that clears local-override paths (network, system.diagnosticsMode, system.hostname, or * for all). This can take connectivity away from a device that depends on a locally entered network. Protocol-1 firmware only.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Discard device local override", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Paths (default all)", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.DiscardLocalOverrideRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.DiscardLocalOverrideResponse" } }, "409": { "description": "No local override or legacy firmware", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/document:render": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Render the bundle the device would receive (secrets stripped, credentials redacted) with its revision and a diff against what the device last reported. dryRun=1 only renders; otherwise the bundle is also pushed (editor). An optional candidate Device document in the body is validated like PUT and rendered without being stored or pushed: the result adds specDiff, currentRevision and currentDiff (against the current render), renderedRevision and notRendered.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Render device desired state", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "boolean", "description": "Render only", "name": "dryRun", "in": "query" }, { "description": "Candidate document", "name": "document", "in": "body", "schema": { "$ref": "#/definitions/documentservice.DeviceDocument" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.RenderResult" } }, "503": { "description": "Renderer not available", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/edgewire/targets": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Deprecated host-address targets are inactive. Configure named container-only services in Configuration spec.edgewire.services using the existing configuration workflow.", "produces": [ "application/json" ], "tags": [ "EdgeWire" ], "summary": "Get a device's EdgeWire targets", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Targets", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.EdgeWireTargetsBody" } } } ] } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Deprecated host-address targets are inactive. Configure named container-only services in Configuration spec.edgewire.services using the existing configuration workflow.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "EdgeWire" ], "summary": "Set a device's EdgeWire targets", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Targets", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.EdgeWireTargetsBody" } } ], "responses": { "400": { "description": "Invalid targets", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "410": { "description": "Retired; use Configuration spec.edgewire.services", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/events": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Retrieve events for a specific device with pagination and filtering.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device events", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Device ID", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "default": "\"24 hours ago\"", "description": "Start time (RFC3339 format)", "name": "start", "in": "query" }, { "type": "string", "default": "\"now\"", "description": "End time (RFC3339 format)", "name": "end", "in": "query" }, { "maximum": 1000, "minimum": 1, "type": "integer", "default": 50, "description": "Number of events to return (max: 1000)", "name": "limit", "in": "query" }, { "minimum": 0, "type": "integer", "default": 0, "description": "Pagination offset", "name": "offset", "in": "query" }, { "type": "string", "description": "Filter by event type", "name": "event", "in": "query" }, { "type": "string", "description": "Filter by event source", "name": "source", "in": "query" } ], "responses": { "200": { "description": "Paginated list of events for the device within the requested window", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.EventsListResponse" } } } ] } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "500": { "description": "Failed to query event store", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/fleet": { "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Move a device to a different fleet within the organisation.\n\nOptionally wipe the device's dynamic payload data (container images\nand/or BTRFS data volumes) as part of the move. Because the target\nfleet may have different owners, wiping prevents data from leaking\nacross ownership boundaries. When `wipe` is true, at least one of\n`wipe_options.images` or `wipe_options.volumes` must be set, and the\ncaller must be an **admin** of the device. The wipe does NOT unpair\nor factory-reset the device — only payload data is destroyed.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Change device fleet", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Target fleet and optional wipe options", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.ChangeDeviceFleetRequest" } } ], "responses": { "200": { "description": "Device moved to new fleet", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ChangeDeviceFleetResponse" } } } ] } }, "400": { "description": "Missing or invalid flotilla_id, invalid wipe options, invalid request payload, or invalid device ID format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device or fleet, or is not a device admin (required for wipe)", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Fleet or device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to change device fleet", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } }, "504": { "description": "Device is not contactable to perform the wipe", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/image-cache-manifest": { "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Set the list of images that should be cached on a device.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Set device cache manifest", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Cache manifest", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.SetDeviceCacheManifestRequest" } } ], "responses": { "200": { "description": "Cache manifest was dispatched to the device", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.SetDeviceCacheManifestResponse" } } } ] } }, "400": { "description": "Missing device ID, malformed JSON, or empty image_names list", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied to caching policy setup", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device with the given ID does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "503": { "description": "Failed to dispatch cache manifest to the device (backend transport failure)", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable — offline or did not respond in time", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/images": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get all container images present on a device.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "List device images", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "List of container images currently present on the device", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ListDeviceImagesResponse" } } } ] } }, "400": { "description": "Missing or invalid device ID in path", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied to device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device with the given ID does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "503": { "description": "Failed to communicate with device (backend transport failure)", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable — offline or did not respond in time", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } }, "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Pull or create a container image on a device.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Pull image on device", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Image details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CreateDeviceImageRequest" } } ], "responses": { "202": { "description": "Image pull request was dispatched to the device", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.DeviceImageOperationResponse" } } } ] } }, "400": { "description": "Missing device ID, malformed JSON body, or empty image_name", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied to device image pulling", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device with the given ID does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to write pull operation to tasks", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } }, "503": { "description": "Failed to dispatch the image pull command to the device", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Image pull request timed out waiting for the device", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } }, "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Delete a container image from a device.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Delete device image", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Delete options", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.DeleteDeviceImageRequest" } } ], "responses": { "200": { "description": "Image delete request was dispatched to the device", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.DeviceImageOperationResponse" } } } ] } }, "400": { "description": "Missing device ID in path", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied to image deletions", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device with the given ID does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "503": { "description": "Failed to communicate with device (backend transport failure)", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable — offline or did not respond in time", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/images/pin": { "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Set whether a container image on a device is pinned. Pinned images are excluded from image retention cleanup.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Pin or unpin a device image", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Pin options", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.SetDeviceImagePinRequest" } } ], "responses": { "200": { "description": "Image pin request was applied on the device", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.DeviceImageOperationResponse" } } } ] } }, "400": { "description": "Missing device ID, malformed JSON body, or empty image", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied to image pinning", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device with the given ID does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "503": { "description": "Failed to communicate with device (backend transport failure)", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable — offline or did not respond in time", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/memory-test": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Current or last memory test run, passive memory health (capabilities, hardware-corrupted bytes, EDAC counters, retired pages, fault) and recent results. source live is the device's answer now; source stored is the last health snapshot and the stored results when the device is offline or did not answer. supported false means the device is online but its firmware has no memory test.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device memory test status", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Memory test status", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.MemoryTestStatusResponse" } } } ] } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } } } }, "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Start a RAM test on the device. impact running keeps the workload running; stopped stops it for the run. placement online keeps the device booted and connected; offline reboots it into a one-shot test boot (impact stopped only). Offline runs can only be started from a signed-in dashboard session: API tokens, CLI tokens and service accounts get 403 operator_required. Plan rules: passes 1..20, kernelPasses 1..17 (offline only), timeBudgetSeconds 60..43200; omitted values use the mode default. Device answers map to busy 409, invalid 400, unsupported 422, workload_stop_failed 502; an offline device answers 503. Limited to one start per device every few seconds (429).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Start a device memory test", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Test plan", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.MemoryTestStartRequest" } } ], "responses": { "202": { "description": "Memory test started", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.MemoryTestRunResponse" } } } ] } }, "400": { "description": "Invalid plan (error invalid)", "schema": { "$ref": "#/definitions/controllers.MemoryTestErrorBody" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "operator_required, or no access to the device", "schema": { "$ref": "#/definitions/controllers.MemoryTestErrorBody" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "409": { "description": "A memory test is already running (error busy, status = the active run)", "schema": { "$ref": "#/definitions/controllers.MemoryTestErrorBody" } }, "422": { "description": "The device firmware or board does not support this test (error unsupported)", "schema": { "$ref": "#/definitions/controllers.MemoryTestErrorBody" } }, "429": { "description": "Started a moment ago; retry after Retry-After seconds", "schema": { "$ref": "#/definitions/controllers.Response" } }, "502": { "description": "The device could not start the test (workload_stop_failed, internal)", "schema": { "$ref": "#/definitions/controllers.MemoryTestErrorBody" } }, "503": { "description": "Device is offline", "schema": { "$ref": "#/definitions/controllers.Response" } }, "504": { "description": "Device did not respond in time", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/memory-test/cancel": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Cancel the running memory test (runId optional: empty cancels whatever is running). A test boot held after a failure is released and the device reboots to normal. When the device reports the test is not running, or cannot answer, a test still shown as running is closed here. 409 not_running when nothing runs.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Cancel a device memory test", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Run to cancel", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.MemoryTestCancelRequest" } } ], "responses": { "200": { "description": "Memory test cancelled", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.MemoryTestRunResponse" } } } ] } }, "400": { "description": "Invalid request body", "schema": { "$ref": "#/definitions/controllers.MemoryTestErrorBody" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "409": { "description": "No memory test is running (error not_running)", "schema": { "$ref": "#/definitions/controllers.MemoryTestErrorBody" } }, "422": { "description": "The device firmware does not support memory tests", "schema": { "$ref": "#/definitions/controllers.MemoryTestErrorBody" } }, "502": { "description": "The device could not cancel the test", "schema": { "$ref": "#/definitions/controllers.MemoryTestErrorBody" } }, "503": { "description": "Device is offline", "schema": { "$ref": "#/definitions/controllers.Response" } }, "504": { "description": "Device did not respond in time", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/memory-test/results": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Stored memory test results for the device, newest first. Each result has the plan, outcome (pass, fail, cancelled, interrupted, error), verdict (ok, weak_cells, data_line, address_line, thermal, unknown), coverage, up to 256 errors with physical addresses, and the pages retired by the run.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "List device memory test results", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "integer", "description": "Maximum results (default 20, max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Memory test results", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.MemoryTestResultsResponse" } } } ] } }, "400": { "description": "Invalid limit", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to read results", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/memory-test/results/{runId}": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "One stored memory test run: plan, outcome, verdict, coverage, the first 256 raw errors, the per-page summary of every error, retired pages, hardware details and versions. 404 when the run does not exist for this device.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get one device memory test result", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "Run ID", "name": "runId", "in": "path", "required": true } ], "responses": { "200": { "description": "Memory test result", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.MemoryTestResultResponse" } } } ] } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device or run not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to read the result", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/memory-test/results/{runId}/errors.csv": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "CSV attachment for one run: a comment line with the report ID, device, run and evidence SHA-256; the per-page summary rows; a blank line; then the raw error rows (first 256). Cells starting with = + - or @ are prefixed with an apostrophe so spreadsheets do not run them as formulas.", "produces": [ "text/csv" ], "tags": [ "Devices" ], "summary": "Download memory test errors as CSV", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "Run ID", "name": "runId", "in": "path", "required": true } ], "responses": { "200": { "description": "CSV file", "schema": { "type": "string" }, "headers": { "Content-Disposition": { "type": "string", "description": "attachment; filename=memory-test-device-name-runid.csv" } } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device or run not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to build the report", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/memory-test/results/{runId}/report": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "The customer report for one memory test run: the stored result, the evidence SHA-256 of that result, organisation, device and fleet names, and the analysis (plain-language verdict and next step, failing-bit histogram, byte lanes, errors by pattern, temperature and memory module, recurrence across passes, merged bad ranges, the worst pages and notes). The report ID is MT-first 8 characters of the run ID-date the run finished.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get a memory test report", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "Run ID", "name": "runId", "in": "path", "required": true } ], "responses": { "200": { "description": "Memory test report", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/memtestreport.Report" } } } ] } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device or run not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to build the report", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/memory-test/results/{runId}/report.json": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "The same report as the report route, as a JSON file attachment and not wrapped in the response envelope.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Download a memory test report as JSON", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "Run ID", "name": "runId", "in": "path", "required": true } ], "responses": { "200": { "description": "Report file", "schema": { "$ref": "#/definitions/memtestreport.Report" }, "headers": { "Content-Disposition": { "type": "string", "description": "attachment; filename=memory-test-device-name-runid.json" } } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device or run not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to build the report", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/network/configuration": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Retrieve the device-specific network configuration override.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device network configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Device network configuration override (or empty body if none is set)", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing or invalid device ID in path", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Failed to retrieve configuration", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Apply a network configuration to a device. Supplied payload requires structurally valid interface arrays.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Set device network configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Network configuration", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.SetNetworkConfigurationRequest" } } ], "responses": { "200": { "description": "Network configuration accepted", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "JSON Parsing error or explicit structure validation mismatch", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device does not exist", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Remove the device-specific network configuration override and revert to the fleet-level configuration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Delete device network configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Device network configuration deleted successfully", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing or invalid device ID in path", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Failed to delete configuration", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/network/effective-configuration": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get the effective network configuration for a device, merged from device and fleet scopes.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get effective device network configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Effective network configuration with origin source (device or fleet)", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.EffectiveNetworkConfigurationResponse" } } } ] } }, "400": { "description": "Missing or invalid device ID in path", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Failed to retrieve effective configuration", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/network/status": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Retrieve the current network status, including all interfaces and their states.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device network status", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Current network interfaces", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.GetNetworkStatusResponse" } } } ] } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device does not exist", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/network/wifi/scan": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Trigger a Wi-Fi scan on the device and return the discovered networks.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Scan Wi-Fi networks", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "List of Wi-Fi networks discovered by the device", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ScanWifiResponse" } } } ] } }, "400": { "description": "Missing or invalid device ID in path", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Device does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "Failed to communicate with device (backend transport failure)", "schema": { "$ref": "#/definitions/controllers.Response" } }, "504": { "description": "Device is not contactable — offline or scan did not complete in time", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/reboot": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Issue a reboot command to a device.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Reboot device", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Device ID", "name": "deviceId", "in": "path", "required": true }, { "description": "Optional control flags", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.DeviceControlRequest" } } ], "responses": { "200": { "description": "Reboot command dispatched", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.DeviceOperationResponse" } } } ] } }, "400": { "description": "Invalid device ID format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to dispatch reboot command", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/reset": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Trigger a factory reset on a device. **Destructive** — restores the device to factory settings.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Factory-reset device", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Device ID", "name": "deviceId", "in": "path", "required": true }, { "description": "Optional control flags", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.DeviceControlRequest" } } ], "responses": { "200": { "description": "Factory reset command dispatched", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ResetDeviceResponse" } } } ] } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to dispatch factory reset command", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/screenshot": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Capture a screenshot from a device. The device picks JPEG for a real display and PNG for the virtual console render unless format is given. Device-reported conditions are returned in data.status: ok, disabled and no_display answer 200; busy answers 503 with Retry-After; capture_failed, too_large and bad_request answer 502.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device screenshot", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Device ID", "name": "deviceId", "in": "path", "required": true }, { "type": "integer", "default": 0, "description": "Display number (0 for primary)", "name": "display", "in": "query" }, { "enum": [ "png", "jpeg" ], "type": "string", "description": "Image format; empty lets the device choose", "name": "format", "in": "query" }, { "type": "integer", "default": 0, "description": "Downscale to at most this width in pixels (0 = native, max 4096)", "name": "maxWidth", "in": "query" }, { "type": "integer", "default": 0, "description": "JPEG quality 1-100 (0 = device default)", "name": "quality", "in": "query" }, { "enum": [ "auto", "display", "virtual" ], "type": "string", "default": "auto", "description": "Capture source", "name": "source", "in": "query" } ], "responses": { "200": { "description": "Screenshot, or a disabled / no_display status without an image", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ScreenshotResponse" } } } ] } }, "400": { "description": "Missing device ID, or invalid display, format, maxWidth, quality or source", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device with the given ID does not exist", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "502": { "description": "The device failed to capture, or the image was too large", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "The device is busy (Retry-After: 2), or could not be communicated with", "schema": { "$ref": "#/definitions/controllers.Response" } }, "504": { "description": "Screenshot request timed out waiting for the device", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/screenshots": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Start a screenshot capture and return at once with status pending. The device streams the image to the backend in chunks; poll GET /devices/{deviceId}/screenshots/{shotId}?wait=15 until status is ready or failed, then fetch the bytes from the image URL. Devices whose firmware predates chunked transfer are served transparently through the legacy path (transport v1). A device with screenshots turned off answers 202 with status failed and code disabled. The shot expires after 15 minutes.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Request a device screenshot (v2)", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Capture options", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/controllers.ScreenshotCreateRequest" } } ], "responses": { "202": { "description": "Capture started; Location points at the shot", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ScreenshotMeta" } } } ] } }, "400": { "description": "Invalid format, maxWidth, quality, source or display", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "429": { "description": "Too many screenshot requests in flight (Retry-After: 2)", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "Screenshots are temporarily unavailable", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } } } } }, "/devices/{deviceId}/screenshots/{shotId}": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Return the metadata of a screenshot. With wait (seconds, at most 15, or a duration such as 10s) the request is held open until the shot is no longer pending or the wait elapses, in which case the still-pending meta is returned. Unknown, expired and other devices' or organisations' shots answer 404.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device screenshot status (v2)", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "Screenshot ID", "name": "shotId", "in": "path", "required": true }, { "type": "string", "description": "Long-poll up to this long (seconds or duration, max 15s)", "name": "wait", "in": "query" } ], "responses": { "200": { "description": "Screenshot metadata", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ScreenshotMeta" } } } ] } }, "400": { "description": "Invalid wait", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device or screenshot not found, or expired", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } } } } }, "/devices/{deviceId}/screenshots/{shotId}/image": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Stream the image bytes of a ready screenshot with Content-Type, Content-Length, ETag (the sha256) and Cache-Control private, max-age=900. 409 while the shot is pending or after it failed; 404 when unknown, expired, or another device's or organisation's shot.", "produces": [ "image/jpeg", "image/png" ], "tags": [ "Devices" ], "summary": "Get device screenshot image (v2)", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "Screenshot ID", "name": "shotId", "in": "path", "required": true } ], "responses": { "200": { "description": "Image bytes", "schema": { "type": "file" } }, "304": { "description": "Not modified (If-None-Match matches the ETag)" }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device or screenshot not found, or expired", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "409": { "description": "Screenshot is not ready", "schema": { "$ref": "#/definitions/controllers.ConflictResponse" } } } } }, "/devices/{deviceId}/secret-files": { "get": { "responses": {} }, "post": { "responses": {} } }, "/devices/{deviceId}/secret-files/{fileId}": { "delete": { "responses": {} } }, "/devices/{deviceId}/services": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get the list of network services discovered on a device.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device services", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Discovered services for the device", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ServiceDiscoveryResponse" } } } ] } }, "400": { "description": "Missing device ID or invalid format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "503": { "description": "Failed to communicate with device (backend transport failure)", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable — offline or did not respond in time", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/shutdown": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Issue a shutdown command to a device.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Shutdown device", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Device ID", "name": "deviceId", "in": "path", "required": true }, { "description": "Optional control flags", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.DeviceControlRequest" } } ], "responses": { "200": { "description": "Shutdown command dispatched", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.DeviceOperationResponse" } } } ] } }, "400": { "description": "Invalid device ID format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to dispatch shutdown command", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/specifications": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get hardware and system specifications for a device, including DMI fields, integrated GPUs and accelerators, displays, and versions (including the kernel version). By default the device is asked live; when it is offline or does not answer, the last specification it reported is returned with source stored. Pass source=stored to skip the device and read the stored specification only (404 when none has been reported). The response carries source (live or stored) and collectedAt (when the backend received the specification; absent for stored specifications that predate the timestamp).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device specifications", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "enum": [ "live", "stored" ], "type": "string", "description": "Set to stored to return the stored specification without contacting the device", "name": "source", "in": "query" } ], "responses": { "200": { "description": "Specifications resolved successfully", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.DeviceSpecificationResponse" } } } ] } }, "400": { "description": "Missing device ID in path or invalid source value", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied to device metrics specification", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device with the given ID does not exist, or no specification has been reported yet (source=stored)", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failure evaluating spec payloads internally", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } }, "503": { "description": "Failed to retrieve specification data from the device and none is stored", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } } } } }, "/devices/{deviceId}/state": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "The device's observed-state document (workload, network, system, boot, transport, time, storage, conditions, boot reasons) as last stored. live=1 asks the device for its cached snapshot instead (cmd.\u003cid\u003e.state.get). Support-scope fields are redacted for customer principals.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device observed state", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "boolean", "description": "Ask the device", "name": "live", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.DeviceStateResponse" } } } ] } }, "404": { "description": "Device not found or no state yet", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "429": { "description": "rate_limited: live=1 is limited to one call per 5 s per device (Retry-After)", "schema": { "$ref": "#/definitions/devicestate.CommsErrorBody" } }, "503": { "description": "device_offline", "schema": { "$ref": "#/definitions/devicestate.CommsErrorBody" } }, "504": { "description": "device_timeout", "schema": { "$ref": "#/definitions/devicestate.CommsErrorBody" } } } } }, "/devices/{deviceId}/state/stream": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Server-sent events: an initial \"state\" event with the stored document, then one \"state\" event per update (kind state, workload_report, heartbeat, network, spec). A comment keepalive is sent every 25 s; on each one the caller's credential, organisation access and device access are checked again. The server ends the stream with a final \"end\" event ({reason: unauthorized|lifetime}) when that check fails or after 30 minutes; clients reconnect. Support-scope fields are redacted for customer principals; local-override network credentials are always redacted.", "produces": [ "text/event-stream" ], "tags": [ "Devices" ], "summary": "Stream device observed state", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "event: state", "schema": { "$ref": "#/definitions/controllers.StateStreamEvent" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } } } } }, "/devices/{deviceId}/system-services": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Report the services supervised by the device's init system (s6): their state, pid, uptime, recent exits and a health verdict (stable, starting, unstable, flapping, restarting, stopped, unavailable, unsupervised). Not to be confused with GET /devices/{deviceId}/services, which lists listening network ports.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device system services", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "Limit the report to one service", "name": "name", "in": "query" }, { "type": "integer", "description": "Recent deaths to include per service (0 = default 5, max 50)", "name": "deaths", "in": "query" } ], "responses": { "200": { "description": "System services for the device", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.SystemServicesResponse" } } } ] } }, "400": { "description": "Invalid name or deaths", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device or service not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "502": { "description": "The device could not produce the report", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "Failed to communicate with device", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable — offline or did not respond in time", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/unpair": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Issue an unpair command to a device, removing it from the control plane.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Unpair device", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Device ID", "name": "deviceId", "in": "path", "required": true }, { "description": "Optional control flags", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.DeviceControlRequest" } } ], "responses": { "200": { "description": "Unpair command dispatched", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.UnpairDeviceResponse" } } } ] } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to dispatch unpair command", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/update": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Trigger a system update on a device. Either `image_id` or `partition` must be provided.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Update device", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Device ID", "name": "deviceId", "in": "path", "required": true }, { "description": "Update payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.DeviceUpdateRequest" } } ], "responses": { "200": { "description": "Update command dispatched", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.DeviceUpdateOperationResponse" } } } ] } }, "400": { "description": "Invalid payload, missing image_id/partition, partition not 'A'/'B', or invalid device ID format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to dispatch update command", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/update-state": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Query the device for its current system component versions and update status", "tags": [ "Devices" ], "summary": "Get Device Update State", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Live device update state including hardware identifiers and current component versions", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/system.DeviceUpdateState" } } } ] } }, "400": { "description": "Missing or invalid device ID in path", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to query device update state", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/update-version": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Trigger an update on a device via LibP2P. Can push \"current\" versions or specific versions.", "tags": [ "Devices" ], "summary": "Push Update to Device", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Update details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/system.PushUpdateRequest" } } ], "responses": { "200": { "description": "Update manifest dispatched to the device", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing/invalid device ID, invalid payload, or neither use_current_versions nor specific_version_ids supplied", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to dispatch update manifest", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/usb": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Live query: every USB device attached to the device (root hubs included), each interface with its class, driver and policy status (allowed, blocked or protected, with a reason). supported false means the kernel cannot enforce a USB policy; the inventory is still reported.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device USB inventory", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "USB inventory for the device", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.UsbInventoryResponse" } } } ] } }, "400": { "description": "Invalid device ID", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "502": { "description": "The device returned an empty or invalid inventory", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "Failed to communicate with device", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable — offline or did not respond in time", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/usb-policy": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "The device override, its fleet's policy and the effective policy with its source (device, fleet or default). Works while the device is offline.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device USB policy", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/usbpolicyservice.DevicePolicyView" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Save a USB policy override for this device and push it. delivered is false when the device is offline or did not accept the push; it converges on its next pull. Requires device edit access.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Set device USB policy", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "USB policy", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UsbPolicyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/usbpolicyservice.DevicePolicyUpdateView" } } } ] } }, "400": { "description": "Invalid policy", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Remove the device override so the device inherits its fleet's USB policy, and push the result. Requires device edit access.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Clear device USB policy", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/usbpolicyservice.DevicePolicyUpdateView" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/devices/{deviceId}/version-info": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get current device versions, available updates, and recommended versions", "tags": [ "Devices" ], "summary": "Get Device Version Info", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Current versions, available updates, and recommended versions for the device", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/system.DeviceVersionInfo" } } } ] } }, "400": { "description": "Missing or invalid device ID in path", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to assemble device version info", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/devices/{deviceId}/volumes": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "List BTRFS subvolumes present on a device. Requires viewer access to the device.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "List device volumes", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Volumes retrieved", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.VolumeListResponse" } } } ] } }, "400": { "description": "Missing or invalid device ID, or command failed on device", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "503": { "description": "Failed to communicate with device", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } }, "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Create a BTRFS subvolume on a device. Requires editor access to the device.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Create device volume", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Volume details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CreateVolumeRequest" } } ], "responses": { "200": { "description": "Volume created", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.VolumeCommandResponse" } } } ] } }, "400": { "description": "Missing/invalid device ID, invalid body, or command failed on device", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "503": { "description": "Failed to communicate with device", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } }, "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Delete a BTRFS subvolume on a device. Requires editor access to the device. Set secureDelete=true to request a secure wipe.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Delete device volume", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Volume to delete", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.DeleteVolumeRequest" } } ], "responses": { "200": { "description": "Volume deleted", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.VolumeCommandResponse" } } } ] } }, "400": { "description": "Missing/invalid device ID, invalid body, or command failed on device", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "503": { "description": "Failed to communicate with device", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/volumes/{volume}/backups": { "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Delete all backup snapshots of a volume on a device. The volume is a name or its 64-hex hash and may be unused by the current configuration. Requires editor access to the device. A device-side refusal returns 409; agents that predate this action return 501 not_supported_by_agent.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Delete all backups of a device volume", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "Volume name or 64-hex hash", "name": "volume", "in": "path", "required": true } ], "responses": { "200": { "description": "Backups deleted", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.VolumeBackupCommandResponse" } } } ] } }, "400": { "description": "Missing/invalid device ID or volume", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "409": { "description": "Device refused the delete", "schema": { "$ref": "#/definitions/controllers.Response" } }, "501": { "description": "Device agent does not support this action (not_supported_by_agent)", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "Failed to communicate with device", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/volumes/{volume}/backups/{backup}": { "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Delete one backup snapshot of a volume on a device. The volume is a name or its 64-hex hash and may be unused by the current configuration. Requires editor access to the device. A device-side refusal returns 409; agents that predate this action return 501 not_supported_by_agent.", "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Delete a device volume backup", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "Volume name or 64-hex hash", "name": "volume", "in": "path", "required": true }, { "type": "string", "description": "Backup name (14-digit timestamp)", "name": "backup", "in": "path", "required": true } ], "responses": { "200": { "description": "Backup deleted", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.VolumeBackupCommandResponse" } } } ] } }, "400": { "description": "Missing/invalid device ID, volume or backup", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "409": { "description": "Device refused the delete", "schema": { "$ref": "#/definitions/controllers.Response" } }, "501": { "description": "Device agent does not support this action (not_supported_by_agent)", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "Failed to communicate with device", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/wipe": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Clear dynamic payload data (container images and/or BTRFS volumes) on a device WITHOUT unpairing or factory-resetting the OS. Destructive: the cleared data cannot be recovered. Requires admin access to the device. At least one of images/volumes must be true.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Wipe device payload data", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "What to wipe", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.WipeDeviceRequest" } } ], "responses": { "200": { "description": "Wipe command dispatched to the device", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.WipeDeviceResponse" } } } ] } }, "400": { "description": "Missing/invalid device ID, invalid body, or nothing selected to wipe", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have admin access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "503": { "description": "Failed to communicate with device (backend transport failure)", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable — offline or did not acknowledge in time", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/workload": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get the status of the workload on a device, including the configuration identity (configurationName, image, version) in running. By default the last workload report the device pushed is returned (source stored, with reportedAt, online and lastSeenAt); live=1 asks the device (source live). If the device is unreachable the endpoint still returns 200 with the last report or state=\"unknown\".", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Get device workload status", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "boolean", "description": "Ask the device instead of returning the last report", "name": "live", "in": "query" } ], "responses": { "200": { "description": "Workload status retrieved", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.WorkloadStatusResponse" } } } ] } }, "400": { "description": "Missing device ID in path or invalid format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Unexpected error retrieving workload status", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } }, "504": { "description": "Workload status request timed out before the device responded", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/workload/cmd": { "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Send a control command (START/STOP/RESTART/DELETE) to a device's workload container.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Send workload command", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "description": "Command details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.WorkloadCommandRequest" } } ], "responses": { "200": { "description": "Workload command completed successfully", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.WorkloadCommandResponse" } } } ] } }, "400": { "description": "Validation failure or command failed on device container", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.WorkloadCommandResponse" } } } ] } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to dispatch workload command", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } }, "503": { "description": "Failed to communicate with device (backend transport failure)", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable — offline or did not respond in time", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/devices/{deviceId}/workload/push": { "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Push the latest workload configuration to a device. When stageOnly=true the device pre-pulls the image and prepares resources but does not apply/restart until a subsequent non-staged push or its maintenance window opens.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Devices" ], "summary": "Push workload configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true }, { "type": "boolean", "description": "Pre-pull image but do not apply/restart until the maintenance window", "name": "stageOnly", "in": "query" } ], "responses": { "200": { "description": "Workload configuration dispatched to the device", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.WorkloadPushResponse" } } } ] } }, "400": { "description": "Missing or invalid device ID, or push failed", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this device", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Device does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "503": { "description": "Failed to communicate with device (backend transport failure)", "schema": { "$ref": "#/definitions/controllers.ServiceUnavailableResponse" } }, "504": { "description": "Device is not contactable — offline or did not acknowledge in time", "schema": { "$ref": "#/definitions/controllers.GatewayTimeoutResponse" } } } } }, "/edgewire/connections": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Live EdgeWire sessions per device of the organisation, from the devices' reported state. Org admins and platform staff see every session with addresses and owners; other members see all devices but only their own sessions in full (other sessions carry no owner and no addresses). Devices whose agent reports no EdgeWire section have reporting=false. When the organisation is not entitled, enabled=false and devices is empty.", "produces": [ "application/json" ], "tags": [ "EdgeWire" ], "summary": "List EdgeWire connections", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Only devices of this fleet (UUID)", "name": "fleetId", "in": "query" }, { "type": "string", "description": "Only this device (UUID)", "name": "deviceId", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.EdgeWireConnectionsResponse" } } } ] } }, "400": { "description": "Bad filter or missing organisation", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "No device view permission", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "State store unavailable", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/edgewire/sessions": { "get": { "security": [ { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "EdgeWire" ], "summary": "List own EdgeWire sessions", "parameters": [ { "type": "string", "description": "Organisation", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "integer", "description": "Page size (1-200)", "name": "limit", "in": "query" }, { "type": "string", "description": "Opaque page cursor", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/edgewire/sessions/{sid}": { "delete": { "security": [ { "BearerAuth": [] } ], "tags": [ "EdgeWire" ], "summary": "Close own EdgeWire session", "parameters": [ { "type": "string", "description": "Organisation", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Session ID", "name": "sid", "in": "path", "required": true } ], "responses": { "202": { "description": "Accepted", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/edgewire/token": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Any principal the backend resolves (portal session, admrl-cli token, personal API token or service account) exchanges its credential for an opaque EdgeWire token (prefix admrl_ew_), which is the only credential the /cli/edgewire/session endpoints accept. The token records the subject (user or service account), the organisation from X-Organization-ID, an optional device and target scope, and the credential it came from; revoking that credential, the subject's access or the token itself ends it and its live sessions. The scope only narrows: every session still passes the subject's own authorisation. ttl_seconds defaults to 3600 and is capped at 86400; a token never outlives the CLI token it was exchanged from. The token is shown once. A subject may hold at most 100 live (unexpired, unrevoked) tokens; beyond that the call is 429. Errors carry error_code: bad_request, unsupported_credential (403), too_many_tokens (429).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "EdgeWire" ], "summary": "Exchange a credential for an EdgeWire token", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Optional scope and lifetime", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.edgeWireTokenRequest" } } ], "responses": { "200": { "description": "EdgeWire token", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.edgeWireTokenResponse" } } } ] } }, "400": { "description": "Invalid scope or missing organisation", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "402": { "description": "Account locked", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Credential cannot be exchanged", "schema": { "$ref": "#/definitions/controllers.Response" } }, "429": { "description": "The subject already holds 100 live tokens (error_code too_many_tokens)", "schema": { "$ref": "#/definitions/controllers.Response" } }, "503": { "description": "EdgeWire is not configured", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/edgewire/token/{id}": { "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Revokes the caller's own EdgeWire token (by the id returned when it was issued) and ends its live EdgeWire sessions. Another principal's token is indistinguishable from a missing one.", "produces": [ "application/json" ], "tags": [ "EdgeWire" ], "summary": "Revoke an EdgeWire token", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "EdgeWire token id", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Revoked", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Token not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/edgewire/trust": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Public keys of the EdgeWire grant issuers as [{kid, scope, ed25519, mldsa65}], key halves in padded base64url. `data` is the trust file the CLI loads. Empty when EdgeWire is not configured. Public keys only; cacheable for an hour.", "produces": [ "application/json" ], "tags": [ "EdgeWire" ], "summary": "EdgeWire grant-issuer trust set", "responses": { "200": { "description": "Issuer trust set", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/controllers.EdgeWireTrustKey" } } } } ] } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get a paginated list of fleets with device counts. Supports filtering by tag via repeatable `tag` query params (`key` or `key:value`).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "List fleets", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "minimum": 1, "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "minimum": 1, "type": "integer", "default": 10, "description": "Items per page", "name": "limit", "in": "query" }, { "type": "string", "description": "Search by name, ID, or location", "name": "search", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "Filter by tag", "name": "tag", "in": "query" }, { "enum": [ "all", "any" ], "type": "string", "default": "all", "description": "How multiple tags combine", "name": "tag_match", "in": "query" } ], "responses": { "200": { "description": "Paginated list of fleets", "schema": { "$ref": "#/definitions/controllers.FleetListEnvelope" } }, "400": { "description": "Missing organisation context", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Create a new fleet in the organisation. Name is required. When update_window.enabled is true, days, start_time, end_time, and timezone are required (create may default empty timezone to UTC if enabled).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Create fleet", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Fleet config details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CreateFleetRequest" } } ], "responses": { "201": { "description": "Fleet created successfully", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetCreatedResponse" } } } ] } }, "400": { "description": "Malformed payload or validation failure", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Identity required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal failure", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get detailed information for a specific fleet.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Get fleet by ID", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "Fleet details", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetResponse" } } } ] } }, "400": { "description": "Missing context or parameters", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet not found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Failed to load database fleet", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Update fleet metadata, tags, or update window. When update_window.enabled is true, days, start_time, end_time, and timezone (IANA format) are strictly validated and required.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Update fleet", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Update details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UpdateFleetRequest" } } ], "responses": { "200": { "description": "Fleet updated successfully", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetUpdatedResponse" } } } ] } }, "400": { "description": "Malformed JSON, missing required fields, or layout validation error", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Incomplete credentials", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Target fleet missing", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Database update failed", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Delete a fleet and notify paired devices.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Delete fleet", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "boolean", "default": false, "description": "Unpair devices", "name": "unpair_devices", "in": "query" } ], "responses": { "200": { "description": "Success", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetDeletedResponse" } } } ] } }, "400": { "description": "Bad context", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Credentials absent", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet absent", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Deletion failure", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/airdetect": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] } ], "description": "Get the current AirDetect analytics state for a fleet.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "AirDetect" ], "summary": "Get AirDetect status", "parameters": [ { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "AirDetect status", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.AirdetectStatusResponse" } } } ] } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Enable or disable the AirDetect analytics feature for a fleet. Body must match strictly.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "AirDetect" ], "summary": "Enable/disable AirDetect analytics", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Toggle AirDetect on or off", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.SetAirdetectRequest" } } ], "responses": { "200": { "description": "AirDetect state updated successfully", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.AirdetectStatusResponse" } } } ] } }, "400": { "description": "Malformed body, invalid attributes or structural error", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/airdetect/devices/{deviceId}/now": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Real-time visitor snapshot.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "AirDetect" ], "summary": "Get AirDetect live presence for a device (\"right now\")", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "Device ID", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.AirdetectDeviceLivePresence" } } } ] } } } } }, "/fleets/{fleetId}/airdetect/devices/{deviceId}/presence-window": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Count distinct visitors present during a playout window.", "produces": [ "application/json" ], "tags": [ "AirDetect" ], "summary": "Get AirDetect device presence during a window (ad attribution)", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "Device ID", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "RFC3339 window start", "name": "start", "in": "query", "required": true }, { "type": "string", "description": "RFC3339 window end", "name": "end", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.AirdetectWindowPresenceResponse" } } } ] } } } } }, "/fleets/{fleetId}/airdetect/devices/{deviceId}/presence-windows": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Batch analytics runner. Supply at least one window layout inside windows array.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "AirDetect" ], "summary": "Evaluate AirDetect presence for many windows (playout attribution)", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "Device ID", "name": "deviceId", "in": "path", "required": true }, { "description": "Playout window details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.AirdetectWindowsRequest" } } ], "responses": { "200": { "description": "Playout response summary", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Malformed payload or structural validation constraints error", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/airdetect/devices/{deviceId}/usage": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get the AirDetect usage breakdown for a single device within a fleet.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "AirDetect" ], "summary": "Get AirDetect device analytics", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "Device ID", "name": "deviceId", "in": "path", "required": true }, { "type": "string", "description": "RFC3339 start of the reporting period", "name": "start", "in": "query" }, { "type": "string", "description": "RFC3339 end of the reporting period", "name": "end", "in": "query" }, { "enum": [ "hour", "day", "week", "month" ], "type": "string", "default": "day", "description": "Time-series bucket size", "name": "granularity", "in": "query" } ], "responses": { "200": { "description": "Detailed device usage time series", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/airdetect/now": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get the real-time snapshot of active visitors in a fleet.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "AirDetect" ], "summary": "Get AirDetect live presence (\"right now\")", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "Snapshot", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.AirdetectLivePresenceResponse" } } } ] } } } } }, "/fleets/{fleetId}/airdetect/presence-window": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Find exposure counts.", "produces": [ "application/json" ], "tags": [ "AirDetect" ], "summary": "Get AirDetect fleet presence during a window (campaign reach)", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "RFC3339 window start", "name": "start", "in": "query", "required": true }, { "type": "string", "description": "RFC3339 window end", "name": "end", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.AirdetectWindowPresenceResponse" } } } ] } } } } }, "/fleets/{fleetId}/airdetect/sessions": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get a paginated list of raw AirDetect sessions for a fleet.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "AirDetect" ], "summary": "List AirDetect sessions", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "RFC3339 start of the reporting period", "name": "start", "in": "query" }, { "type": "string", "description": "RFC3339 end of the reporting period", "name": "end", "in": "query" }, { "type": "integer", "default": 100, "description": "Page size (max 500)", "name": "limit", "in": "query" }, { "type": "string", "description": "Pagination cursor", "name": "cursor", "in": "query" }, { "type": "string", "description": "Filter by visitor", "name": "visitor_id", "in": "query" }, { "type": "string", "description": "Filter by proximity bucket", "name": "proximity", "in": "query" }, { "type": "string", "description": "Filter by device", "name": "device_id", "in": "query" }, { "type": "number", "description": "Minimum confidence", "name": "min_confidence", "in": "query" }, { "type": "number", "description": "Minimum dwell", "name": "min_dwell", "in": "query" }, { "type": "number", "description": "Maximum dwell", "name": "max_dwell", "in": "query" } ], "responses": { "200": { "description": "Raw AirDetect sessions page", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/airdetect/sessions/export": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "produces": [ "text/csv", "application/json" ], "tags": [ "AirDetect" ], "summary": "Export AirDetect sessions (CSV)", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "Start time", "name": "start", "in": "query" }, { "type": "string", "description": "End time", "name": "end", "in": "query" }, { "type": "string", "description": "Filter device", "name": "device_id", "in": "query" }, { "type": "string", "description": "Proximity search", "name": "proximity", "in": "query" }, { "type": "number", "description": "Min confidence", "name": "min_confidence", "in": "query" }, { "type": "integer", "description": "Min dwell", "name": "min_dwell", "in": "query" }, { "type": "integer", "description": "Max dwell", "name": "max_dwell", "in": "query" } ], "responses": { "200": { "description": "CSV Export payload", "schema": { "type": "file" } } } } }, "/fleets/{fleetId}/airdetect/usage": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get AirDetect period usage and estimated cost for a fleet. Defaults to the current calendar month (UTC) when start/end are not supplied.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "AirDetect" ], "summary": "Get AirDetect usage summary", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "RFC3339 start of the reporting period", "name": "start", "in": "query" }, { "type": "string", "description": "RFC3339 end of the reporting period", "name": "end", "in": "query" } ], "responses": { "200": { "description": "Fleet usage summary with estimated cost and per-device breakdown", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.AirdetectUsageResponse" } } } ] } }, "400": { "description": "Missing organisation context", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "402": { "description": "Account is suspended or terminated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet does not exist, is not accessible, or AirDetect is not enabled", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Failed to query AirDetect usage", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/airdetect/usage/detail": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get the full AirDetect usage breakdown for a fleet over a period, bucketed by chosen granularity.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "AirDetect" ], "summary": "Get AirDetect detailed fleet analytics", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "RFC3339 start of the reporting period", "name": "start", "in": "query" }, { "type": "string", "description": "RFC3339 end of the reporting period", "name": "end", "in": "query" }, { "enum": [ "hour", "day", "week", "month" ], "type": "string", "default": "day", "description": "Time-series bucket size", "name": "granularity", "in": "query" } ], "responses": { "200": { "description": "Detailed fleet usage time series", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/configuration": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Find the spec associated with this fleet.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Get fleet configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/fleetservice.FleetConfigurationResponse" } } } ] } }, "401": { "description": "Authentication failure", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Spec not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Link a configuration ID to this fleet. Input configuration_id must be structural UUID validation schema.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Assign configuration to fleet", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Target config request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.AssignConfigurationRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetConfigurationAssignedResponse" } } } ] } }, "400": { "description": "Invalid configuration_id or structural validation schema error", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Identity missing", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Configuration/Fleet not matched", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Persist failure", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/configuration/history": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Audit trail of linked configurations.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Get fleet configuration history", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/fleetservice.FleetConfigurationHistory" } } } } ] } }, "404": { "description": "Fleet missing", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/custom-metrics": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Report whether devices in the fleet accept custom workload metrics on the local metrics socket.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Get custom workload metrics state", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "Custom metrics state", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.CustomMetricsResponse" } } } ] } }, "400": { "description": "Invalid fleet ID or missing organisation context", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Enable or disable the custom workload metrics socket for every device in the fleet. Requires fleet editor access. Body must match strictly. A running workload picks up the socket mount on its next container recreate.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Enable or disable custom workload metrics", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Toggle custom metrics on or off", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.SetCustomMetricsRequest" } } ], "responses": { "200": { "description": "Custom metrics state updated", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.CustomMetricsResponse" } } } ] } }, "400": { "description": "Malformed body or invalid fleet ID", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/devices": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get a paginated list of devices belonging to a fleet.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "List fleet devices", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "minimum": 1, "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "minimum": 1, "type": "integer", "default": 10, "description": "Items per page", "name": "limit", "in": "query" }, { "type": "string", "description": "Search query", "name": "search", "in": "query" }, { "type": "string", "description": "Filter by status", "name": "status", "in": "query" }, { "type": "string", "description": "Sort field", "name": "sort", "in": "query" }, { "type": "string", "description": "Sort direction", "name": "direction", "in": "query" } ], "responses": { "200": { "description": "Paginated fleet devices list", "schema": { "$ref": "#/definitions/controllers.FleetDevicesListEnvelope" } }, "400": { "description": "Invalid inputs", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet not found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal error", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/document": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Kubernetes-shaped Fleet document: spec.configuration, spec.updates, spec.signaturePolicy, spec.security, spec.usbPolicy, spec.network, spec.features; status.devices counts (total, online, converged, crashing, stuck).", "produces": [ "application/json", "application/yaml" ], "tags": [ "Fleets" ], "summary": "Get fleet document", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.FleetDocument" } }, "404": { "description": "Fleet not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Replace the Fleet spec. spec.configuration and spec.updates are writable; the other spec fields are read-only here. If-Match as for devices.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Replace fleet document", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "resourceVersion", "name": "If-Match", "in": "header" }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Fleet document", "name": "document", "in": "body", "required": true, "schema": { "$ref": "#/definitions/documentservice.FleetDocument" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.FleetDocument" } }, "400": { "description": "Validation failed", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/documentservice.ValidationError" } } } ] } }, "409": { "description": "resourceVersion mismatch", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "patch": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "RFC 7386 JSON merge patch over the Fleet document.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Patch fleet document", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "resourceVersion", "name": "If-Match", "in": "header" }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Merge patch", "name": "patch", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.FleetDocument" } }, "409": { "description": "resourceVersion mismatch", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/document:render": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Per-device render and diff for every device in the fleet (first 100 by name). An optional candidate Fleet document in the body adds specDiff against the current spec.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Render fleet (rollout preview)", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Candidate document", "name": "document", "in": "body", "schema": { "$ref": "#/definitions/documentservice.FleetDocument" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.FleetRenderResult" } } } } }, "/fleets/{fleetId}/duplicate": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Creates a new fleet with the source fleet's settings (location, tags, groups, update window and policy, USB / security / signature / device policies, configuration and version, custom metrics). Devices are never copied. Billed features (airdetect, image proxy) are not copied and listed in skipped, as is anything that failed after the fleet was created. Needs viewer on the source and fleet_creator on the organisation.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Duplicate a fleet", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Source fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "New fleet", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/fleetservice.DuplicateFleetRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/fleetservice.DuplicateFleetResult" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "402": { "description": "Signature policy needs the signature_policy feature", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/events": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get a time-filtered event feed for a fleet.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Get fleet events", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "End time (RFC3339 or 'now')", "name": "end", "in": "query" }, { "type": "integer", "default": 50, "description": "Max events", "name": "limit", "in": "query" }, { "type": "integer", "default": 0, "description": "Offset", "name": "offset", "in": "query" }, { "type": "string", "description": "Filter by event type", "name": "event", "in": "query" }, { "type": "string", "description": "Filter by source", "name": "source", "in": "query" } ], "responses": { "200": { "description": "Fleet event feed", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Invalid fleetId format or query params", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Fleet not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to load fleet events", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/fleets/{fleetId}/image-proxy": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "produces": [ "application/json" ], "tags": [ "Image Proxy" ], "summary": "Get registry proxy status", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "Status", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ImageProxyStatusResponse" } } } ] } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Enable or disable the registry proxy value-added service for a fleet. Devices in an enabled fleet that cannot reach their registry directly can pull images through the control plane; data carried is metered and billed. Billed action: requires an organisation admin or billing admin.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Image Proxy" ], "summary": "Enable/disable the registry proxy", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Toggle the registry proxy on or off", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.SetImageProxyRequest" } } ], "responses": { "200": { "description": "Updated", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ImageProxyStatusResponse" } } } ] } }, "400": { "description": "Malformed body", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/image-proxy/usage": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Data carried by the registry proxy for a fleet: totals, per day and per device (top 200 by bytes). `start` and `end` are UTC dates (YYYY-MM-DD) or RFC 3339 timestamps, truncated to UTC days, end exclusive. Defaults to the current UTC month to date; at most 366 days.", "produces": [ "application/json" ], "tags": [ "Image Proxy" ], "summary": "Get registry proxy usage", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "Period start", "name": "start", "in": "query" }, { "type": "string", "description": "Period end (exclusive)", "name": "end", "in": "query" } ], "responses": { "200": { "description": "Usage", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ImageProxyUsageResponse" } } } ] } }, "400": { "description": "Invalid period", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/network/configuration": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Retrieve the fleet-level network configuration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Get fleet network configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "Fleet network configuration (or empty body if none is set)", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing/invalid fleet ID in path or organisation context", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Failed to retrieve configuration", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Apply or update a fleet-level network configuration. Supplied interfaces configuration set requires structural layout constraints validation.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Set fleet network configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Fleet network configuration", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.SetFleetNetworkConfigurationRequest" } } ], "responses": { "200": { "description": "Fleet network configuration saved successfully", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing/invalid fleet ID or invalid structural payload specification", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.Response" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Failed to persist configuration", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Remove the fleet-level network configuration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Delete fleet network configuration", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "Fleet network configuration deleted successfully", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing/invalid fleet ID in path or organisation context", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthorised", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet does not exist or caller has no access", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Failed to delete configuration", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/security-policy": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "TPM / secure boot / disk encryption / recovery key escrow requirements for the fleet, with device compliance counts. Compliance only; it never changes device behaviour.", "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Get fleet security policy", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/securityservice.PolicyView" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Replace the fleet's security requirements and re-evaluate its devices. Requires fleet write access.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Set fleet security policy", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Requirements", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/securityservice.PolicyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/securityservice.PolicyView" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/ssh": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Report whether SSH (device sshd and remote shell sessions) is enabled for the devices in the fleet. Enabled unless turned off.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Get fleet SSH access state", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "SSH access state", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetSSHResponse" } } } ] } }, "400": { "description": "Invalid fleet ID or missing organisation context", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Turn SSH (device sshd and remote shell sessions) on or off for every device in the fleet. Requires fleet editor access. Body must match strictly. New remote shell sessions are refused with 409 ssh_disabled while off; existing sessions are ended by the device.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Enable or disable fleet SSH access", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Toggle SSH access on or off", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.SetFleetSSHRequest" } } ], "responses": { "200": { "description": "SSH access state updated", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetSSHResponse" } } } ] } }, "400": { "description": "Malformed body or invalid fleet ID", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/tag-keys": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Find tag collections.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Get fleet tag keys", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "Query key filter", "name": "q", "in": "query" } ], "responses": { "200": { "description": "Success", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetTagKeysResponse" } } } ] } }, "404": { "description": "Fleet absent", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/tags": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get the key/value tags assigned to a fleet.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Get fleet tags", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "Fleet tags", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetTagsResponse" } } } ] } }, "400": { "description": "Missing context", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Replace the complete set of tags on a fleet. Tag arrays must be populated with structurally clean elements.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Replace fleet tags", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Tags to set", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.FleetTagsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetTagsResponse" } } } ] } }, "400": { "description": "Invalid payload or structural data constraints error", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Merge tags into a fleet. Supplied tags array must contain structural key elements.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Add or update fleet tags", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Tags input", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.FleetTagsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetTagsResponse" } } } ] } }, "400": { "description": "Invalid payload or structural data constraints error", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Remove structural metadata records. supply clean non-empty structural keys.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Delete fleet tags", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "Query key filter", "name": "key", "in": "query" }, { "description": "Tag keys payload", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.DeleteFleetTagsRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetTagsResponse" } } } ] } }, "400": { "description": "At least one tag key is required", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/uniformity": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Percentage (0-100) that two random devices in the fleet carry identical hardware, overall and per component, with the distinct variants and the devices on each. Requires fleet viewer access.", "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Fleet hardware uniformity", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/fleetservice.FleetUniformity" } } } ] } } } } }, "/fleets/{fleetId}/update-policy": { "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Pin the system image and initram versions for a fleet, or set it to track the latest (current) versions. Targets are per (architecture, board); arm64 targets must specify a board.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Set fleet update policy", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Update policy", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UpdatePolicyRequest" } } ], "responses": { "200": { "description": "Fleet update policy set", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/fleet.UpdatePolicy" } } } ] } }, "400": { "description": "Invalid policy (bad mode, missing board on arm64, unknown/incompatible pinned version)", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Request blocked by the WAF", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "404": { "description": "Fleet not accessible in this organisation", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to persist update policy", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/fleets/{fleetId}/update-window": { "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Update the maintenance window configuration. When enabled is true, days, start_time (HH:MM), end_time (HH:MM), and timezone (IANA) are strictly required. Unknown JSON properties are rejected.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Update fleet update window", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Update window configuration", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UpdateWindowRequest" } } ], "responses": { "200": { "description": "Success", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetUpdateWindowUpdatedResponse" } } } ] } }, "400": { "description": "Malformed JSON, missing required fields, or layout validation error", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal error", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/update-window/check": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Check if the current time matches the fleet's maintenance window.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Check if updates are allowed", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.FleetUpdateAllowedResponse" } } } ] } }, "400": { "description": "Bad parameter schema", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Identity missing", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet absent", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal error", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/usb-policy": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "The fleet's default USB policy; null when none is configured (devices default to off unless overridden).", "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Get fleet USB policy", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/usbpolicyservice.FleetPolicyView" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Save the fleet's default USB policy and start a background push to every device in the fleet (devices with an override keep it). devices_notified counts the devices a push was started for. Requires fleet write access.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Set fleet USB policy", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "USB policy", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UsbPolicyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/usbpolicyservice.FleetPolicyUpdateView" } } } ] } }, "400": { "description": "Invalid policy", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Remove the fleet's USB policy (devices without an override fall back to off) and push to every device in the fleet. Requires fleet write access.", "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Clear fleet USB policy", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/usbpolicyservice.FleetPolicyUpdateView" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/users": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Audit direct user permissions on this resource.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "List fleet users", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/controllers.FleetUserResponse" } } } } ] } }, "404": { "description": "Resource missing", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Grant access permissions directly on this resource. User and explicit domain-valid role are required.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Add user to fleet", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "description": "Payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.AddUserToFleetRequest" } } ], "responses": { "200": { "description": "User added to fleet successfully", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Both user_id and role are required or invalid role", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated or access forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/fleets/{fleetId}/users/{userId}": { "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Modify permissions. Explicit role key is structurally required.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Update user role on fleet", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "Target User ID (String)", "name": "userId", "in": "path", "required": true }, { "description": "Updated details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UpdateUserFleetRoleRequest" } } ], "responses": { "200": { "description": "User role updated successfully", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Invalid payload, missing role, or unallowed role value", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Revoke a user's access permissions.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Fleets" ], "summary": "Remove user from fleet", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Fleet ID (UUID)", "name": "fleetId", "in": "path", "required": true }, { "type": "string", "description": "Target User ID (String)", "name": "userId", "in": "path", "required": true } ], "responses": { "200": { "description": "User removed from fleet successfully", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing target reference", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/health/live": { "get": { "description": "Returns 200 unless an internal client has permanently failed; then returns 503 without exposing internal details.", "produces": [ "application/json" ], "tags": [ "Health" ], "summary": "Liveness probe", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/health/ready": { "get": { "description": "Reports subsystem health. Returns 503 only when a critical subsystem is down; non-critical subsystems being down are reported in the body but keep a 200 so the instance continues serving.", "produces": [ "application/json" ], "tags": [ "Health" ], "summary": "Readiness probe", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "503": { "description": "Service Unavailable", "schema": { "type": "object", "additionalProperties": true } } } } }, "/health/ready/{service}": { "get": { "description": "Reports the health of a single subsystem. 200 when up, 503 when down, 404 for an unknown service.", "produces": [ "application/json" ], "tags": [ "Health" ], "summary": "Per-service readiness probe", "parameters": [ { "enum": [ "db", "auth", "workflow", "fabric" ], "type": "string", "description": "Subsystem alias", "name": "service", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "503": { "description": "Service Unavailable", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/helpdesk/tickets": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a support ticket. Optionally ties it to a fleet, configuration or device in the caller's organisation (`subject`). With a device subject and `attachDiagnostics=true`, a diagnostics bundle is requested best-effort; the ticket is always created and `data.diagnostics` reports `requested` (with `bundleId`) or `unavailable` (with `reason`).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Helpdesk" ], "summary": "Create support ticket", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Ticket", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CreateTicketRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.CreateTicketResponse" } } } ] } }, "400": { "description": "Invalid input, subject type or subject id", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Subject not found in this organisation", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/iam/assignments": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Filter by profile, subject (kind:id) or scope (type:id). Cursor-paginated.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "IAM" ], "summary": "List profile assignments", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Filter by profile ID", "name": "profile_id", "in": "query" }, { "type": "string", "description": "Filter by subject, kind:id (user, group, service_account)", "name": "subject", "in": "query" }, { "type": "string", "description": "Filter by scope, type:id (organisation, flotilla, managed_host)", "name": "scope", "in": "query" }, { "type": "integer", "description": "Page size", "name": "limit", "in": "query" }, { "type": "string", "description": "Pagination cursor from next_cursor", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Assignments", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.AssignmentListData" } } } ] } }, "400": { "description": "Missing organisation context or invalid request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Manage access permission required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Assigns a profile to a user, group or service account at organisation, fleet or device scope. Requires manage access and delegation of every capability granted. Repeating the same assignment returns the existing record. Capabilities that cannot apply at that scope are returned in skipped.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "IAM" ], "summary": "Assign a permission profile", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Profile, subject and scope", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/iam.CreateAssignmentRequest" } } ], "responses": { "200": { "description": "Assignment created or existing assignment returned", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.AssignmentCreatedData" } } } ] } }, "400": { "description": "Missing organisation context or invalid request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Manage access permission required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "409": { "description": "Would remove the last owner", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/iam/assignments/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Removes one assignment. Refused with 409 if it is the organisation's last Owner.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "IAM" ], "summary": "Remove a profile assignment", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Assignment ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Assignment removed", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing organisation context or invalid request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Manage access permission required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Assignment not found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "409": { "description": "Last owner of the organisation", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/iam/capabilities": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns every permission capability, grouped, with customer-facing labels, risk, the scopes it can be granted at, and the capabilities it implies.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "IAM" ], "summary": "Get capability catalogue", "responses": { "200": { "description": "Capability catalogue", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/iam.CapabilitiesCatalogueResponse" } } } ] } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/iam/me/capabilities": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Returns the capabilities the caller holds at a scope (default: organisation), with is_admin and is_owner. Readable by any authenticated principal, including API tokens.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "IAM" ], "summary": "Get my capabilities at a scope", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Scope as type:id (organisation, flotilla, managed_host). Defaults to the organisation.", "name": "scope", "in": "query" } ], "responses": { "200": { "description": "Capabilities", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/iam.MyCapabilitiesResponse" } } } ] } }, "400": { "description": "Missing organisation context or invalid scope", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Scope resource not found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/iam/profiles": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Built-in profiles first, then custom profiles by name. Visible to org members and to holders of manage access.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "IAM" ], "summary": "List permission profiles", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true } ], "responses": { "200": { "description": "Profiles", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.ProfileListData" } } } ] } }, "400": { "description": "Missing organisation context or invalid request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Manage access permission required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a custom profile from a set of capability ids. Requires manage access on the org. Rejects unknown ids, an empty set, and duplicate names.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "IAM" ], "summary": "Create a custom permission profile", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Profile definition", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/iam.CreateProfileRequest" } } ], "responses": { "201": { "description": "Profile created", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/iam.ProfileView" } } } ] } }, "400": { "description": "Missing organisation context or invalid request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Manage access permission required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/iam/profiles/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Returns one profile with its stored and effective capabilities and assignment count.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "IAM" ], "summary": "Get a permission profile", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Profile ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Profile", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/iam.ProfileView" } } } ] } }, "400": { "description": "Missing organisation context or invalid request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Profile not found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "description": "Changes name, description or capabilities. Changing capabilities reconciles every assignment. Built-in profiles return 409.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "IAM" ], "summary": "Update a custom permission profile", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Profile ID", "name": "id", "in": "path", "required": true }, { "description": "Fields to change", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/iam.UpdateProfileRequest" } } ], "responses": { "200": { "description": "Profile updated", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/iam.ProfileView" } } } ] } }, "400": { "description": "Missing organisation context or invalid request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Manage access permission required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Profile not found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "409": { "description": "Built-in profiles cannot be changed", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Refused for built-in profiles and for profiles that still have assignments; the message states how many.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "IAM" ], "summary": "Delete a custom permission profile", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Profile ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Profile deleted", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing organisation context or invalid request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Manage access permission required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Profile not found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "409": { "description": "Built-in profile, or profile has assignments", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/iam/profiles/{id}/duplicate": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Creates a new custom profile with the same capabilities. Works on built-in profiles as well.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "IAM" ], "summary": "Duplicate a permission profile", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Source profile ID", "name": "id", "in": "path", "required": true }, { "description": "New profile name", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/iam.DuplicateProfileRequest" } } ], "responses": { "201": { "description": "Profile duplicated", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/iam.ProfileView" } } } ] } }, "400": { "description": "Missing organisation context or invalid request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Manage access permission required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Profile not found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/notifications": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get paginated list of user notifications. API tokens have read-only access.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Notifications" ], "summary": "List notifications", "parameters": [ { "type": "string", "description": "Organization ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "integer", "default": 50, "description": "Items per page", "name": "limit", "in": "query" }, { "type": "integer", "default": 0, "description": "Pagination offset", "name": "offset", "in": "query" }, { "type": "boolean", "default": false, "description": "Show only unread", "name": "unread_only", "in": "query" }, { "type": "string", "description": "Filter by status", "name": "status", "in": "query" }, { "type": "string", "description": "Filter by type", "name": "type", "in": "query" }, { "type": "string", "description": "Filter by priority", "name": "priority", "in": "query" }, { "type": "string", "description": "Filter by time (RFC3339)", "name": "since", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/notification.Notification" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/notifications/stats": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get notification statistics for the user. API tokens have read-only access.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Notifications" ], "summary": "Get notification stats", "parameters": [ { "type": "string", "description": "Organization ID", "name": "X-Organization-ID", "in": "header", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/notification.NotificationStats" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/oauth/mcp/authorize": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Requires a signed-in portal session and membership of organization_id. Returns data.redirect_to: redirect_uri with code, state and iss, or with error access_denied.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MCP Connector" ], "summary": "Approve or deny an MCP authorization request", "parameters": [ { "description": "Authorization parameters and decision", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.mcpDecisionBody" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "403": { "description": "Forbidden", "schema": { "type": "object", "additionalProperties": true } } } } }, "/oauth/mcp/authorize/request": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Used by the consent page. Requires a signed-in portal session. When client_id or redirect_uri is invalid the 400 carries no redirect_to and the UI must not redirect; for any other invalid parameter the 400 data carries redirect_to with error, state and iss.", "produces": [ "application/json" ], "tags": [ "MCP Connector" ], "summary": "Validate an MCP authorization request", "parameters": [ { "type": "string", "description": "Client id", "name": "client_id", "in": "query", "required": true }, { "type": "string", "description": "Registered redirect URI", "name": "redirect_uri", "in": "query", "required": true }, { "type": "string", "description": "Must be code", "name": "response_type", "in": "query", "required": true }, { "type": "string", "description": "PKCE S256 challenge", "name": "code_challenge", "in": "query", "required": true }, { "type": "string", "description": "Must be S256", "name": "code_challenge_method", "in": "query", "required": true }, { "type": "string", "description": "admrl:read and optionally admrl:write", "name": "scope", "in": "query" }, { "type": "string", "description": "Opaque client state", "name": "state", "in": "query" }, { "type": "string", "description": "RFC 8707 resource", "name": "resource", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/controllers.mcpAuthorizeRequestView" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } } } } }, "/oauth/mcp/register": { "post": { "description": "Dynamic client registration for the hosted Admiral MCP connector. Public clients only (token_endpoint_auth_method none). Redirect URIs must be https, or http on a loopback host (127.0.0.1, localhost, [::1]) with any port, and must not contain a fragment. Errors are RFC 6749 JSON, not the usual envelope. Rate limited per IP.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "MCP Connector" ], "summary": "Register an MCP connector client (RFC 7591)", "parameters": [ { "description": "Client metadata", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/mcpauthservice.RegisterRequest" } } ], "responses": { "201": { "description": "client_id, client_id_issued_at, client_name, redirect_uris, grant_types, response_types, token_endpoint_auth_method", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.oauthErrorBody" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/controllers.oauthErrorBody" } } } } }, "/oauth/mcp/revoke": { "post": { "description": "Always answers 200 for a well-formed request. Revoking a refresh token revokes its whole grant; revoking an access token revokes only that token.", "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "tags": [ "MCP Connector" ], "summary": "Revoke an MCP connector token (RFC 7009)", "parameters": [ { "type": "string", "description": "Access or refresh token", "name": "token", "in": "formData", "required": true }, { "type": "string", "description": "Client id", "name": "client_id", "in": "formData" } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/oauth/mcp/token": { "post": { "description": "OAuth 2.1 token endpoint for the hosted Admiral MCP connector. grant_type authorization_code takes code, redirect_uri, client_id, code_verifier (PKCE S256) and resource. grant_type refresh_token takes refresh_token, client_id and an optional scope that must be a subset of the granted scope; refresh tokens rotate on every use and reuse of a rotated token revokes the whole grant. Access tokens last one hour. Responses carry Cache-Control no-store. Errors are RFC 6749 JSON.", "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "tags": [ "MCP Connector" ], "summary": "MCP connector token endpoint", "parameters": [ { "type": "string", "description": "authorization_code or refresh_token", "name": "grant_type", "in": "formData", "required": true }, { "type": "string", "description": "Authorization code", "name": "code", "in": "formData" }, { "type": "string", "description": "Redirect URI used in the authorization request", "name": "redirect_uri", "in": "formData" }, { "type": "string", "description": "Client id", "name": "client_id", "in": "formData", "required": true }, { "type": "string", "description": "PKCE verifier", "name": "code_verifier", "in": "formData" }, { "type": "string", "description": "RFC 8707 resource, must equal the MCP resource URL", "name": "resource", "in": "formData" }, { "type": "string", "description": "Refresh token", "name": "refresh_token", "in": "formData" }, { "type": "string", "description": "Narrowed scope for a refresh", "name": "scope", "in": "formData" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/mcpauthservice.TokenResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.oauthErrorBody" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/controllers.oauthErrorBody" } } } } }, "/oauth/token": { "post": { "description": "Exchanges service account client credentials for a short-lived bearer JWT using the OAuth2 `client_credentials` grant.\n\nCredentials may be supplied as `application/x-www-form-urlencoded` (standard OAuth2), as a JSON body, or via HTTP Basic auth (Basic auth takes precedence per RFC 6749).\nThe returned `access_token` is used as a `Bearer` token on subsequent API requests. It is short-lived; re-exchange your credentials when it expires.", "consumes": [ "application/x-www-form-urlencoded", "application/json" ], "produces": [ "application/json" ], "tags": [ "Authentication" ], "summary": "Obtain an OAuth2 access token", "parameters": [ { "type": "string", "default": "client_credentials", "description": "Must be `client_credentials`", "name": "grant_type", "in": "formData", "required": true }, { "type": "string", "description": "Service account client ID (e.g. `sa_...`)", "name": "client_id", "in": "formData", "required": true }, { "type": "string", "description": "Service account client secret", "name": "client_secret", "in": "formData", "required": true } ], "responses": { "200": { "description": "Access token issued successfully", "schema": { "$ref": "#/definitions/controllers.TokenResponse" } }, "400": { "description": "Invalid request or unsupported grant type", "schema": { "$ref": "#/definitions/controllers.OAuthErrorResponse" } }, "401": { "description": "Invalid client credentials", "schema": { "$ref": "#/definitions/controllers.OAuthErrorResponse" } }, "500": { "description": "Failed to issue token", "schema": { "$ref": "#/definitions/controllers.OAuthErrorResponse" } } } } }, "/organisations/{orgId}/document": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Kubernetes-shaped Organisation document (apiVersion admrl.co/v1): spec.policy is the organisation default device policy, status.defaults the built-in defaults. Any organisation member can read. Send Accept application/yaml for YAML. The ETag header carries the resourceVersion for If-Match.", "produces": [ "application/json", "application/yaml" ], "tags": [ "Organisations" ], "summary": "Get organisation document", "parameters": [ { "type": "string", "format": "uuid", "description": "Organisation ID (UUID)", "name": "orgId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.OrganisationDocument" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Replace spec.policy (null clears it). Organisation admins only. JSON or YAML (Content-Type application/yaml). If-Match carries the resourceVersion (409 on mismatch). An invalid policy is a 422 whose data.issues lists {path,message}.", "consumes": [ "application/json", "application/yaml" ], "produces": [ "application/json" ], "tags": [ "Organisations" ], "summary": "Replace organisation document", "parameters": [ { "type": "string", "description": "resourceVersion", "name": "If-Match", "in": "header" }, { "type": "string", "format": "uuid", "description": "Organisation ID (UUID)", "name": "orgId", "in": "path", "required": true }, { "description": "Organisation document", "name": "document", "in": "body", "required": true, "schema": { "$ref": "#/definitions/documentservice.OrganisationDocument" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.OrganisationDocument" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "409": { "description": "resourceVersion mismatch", "schema": { "$ref": "#/definitions/controllers.Response" } }, "422": { "description": "Invalid policy", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/documentservice.PolicyValidationError" } } } ] } } } }, "patch": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "RFC 7386 JSON merge patch over the Organisation document (e.g. {\"spec\":{\"policy\":{\"health\":{\"maxOffline\":\"7d\"}}}}; null clears). Organisation admins only. If-Match as for PUT.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Organisations" ], "summary": "Patch organisation document", "parameters": [ { "type": "string", "description": "resourceVersion", "name": "If-Match", "in": "header" }, { "type": "string", "format": "uuid", "description": "Organisation ID (UUID)", "name": "orgId", "in": "path", "required": true }, { "description": "Merge patch", "name": "patch", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/documentservice.OrganisationDocument" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "409": { "description": "resourceVersion mismatch", "schema": { "$ref": "#/definitions/controllers.Response" } }, "422": { "description": "Invalid policy", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/documentservice.PolicyValidationError" } } } ] } } } } }, "/organisations/{orgId}/signature-policy": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Organisation-level default; fleets and configurations may add to it (strictest wins). signaturePolicy is null when unset. Any organisation member can read.", "produces": [ "application/json" ], "tags": [ "Organisations" ], "summary": "Get organisation default image signature policy", "parameters": [ { "type": "string", "format": "uuid", "description": "Organisation ID (UUID)", "name": "orgId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/signaturepolicyservice.View" } } } ] } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Replaces the organisation default. Organisation admins only. An invalid policy (unparsable key/certificate, required without any trust root) is a 400 whose data is {field:\"signaturePolicy\",message}.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Organisations" ], "summary": "Set organisation default image signature policy", "parameters": [ { "type": "string", "format": "uuid", "description": "Organisation ID (UUID)", "name": "orgId", "in": "path", "required": true }, { "description": "Policy", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.OrgSignaturePolicyRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/signaturepolicyservice.View" } } } ] } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/ping": { "get": { "description": "Returns pong if service is healthy", "produces": [ "text/plain" ], "tags": [ "Health" ], "summary": "Health check", "responses": { "200": { "description": "pong", "schema": { "type": "string" } } } } }, "/provisioning/profiles": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get all provisioning profiles for an organisation, optionally filtered by fleet ID.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Provisioning" ], "summary": "List provisioning profiles", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Filter by Fleet ID", "name": "fleet_id", "in": "query" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 10, "description": "Items per page", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Retrieved profiles lists", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.PaginatedProfilesResponse" } } } ] } }, "401": { "description": "Unauthenticated request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Fleet context filter not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Create a new provisioning profile for device onboarding.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Provisioning" ], "summary": "Create provisioning profile", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Provisioning profile details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CreateProvisioningProfileRequest" } } ], "responses": { "201": { "description": "Successfully created profile", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Malformed request body or null values parsed", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Forbidden access", "schema": { "$ref": "#/definitions/controllers.Response" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/provisioning/profiles/{profileId}": { "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Delete a provisioning profile by ID.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Provisioning" ], "summary": "Delete provisioning profile", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Provisioning Profile ID (UUID)", "name": "profileId", "in": "path", "required": true } ], "responses": { "200": { "description": "Profile successfully deleted", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Invalid Profile ID format (must be a UUID) or missing organisation context", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthenticated request", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Unauthorized deletion attempt", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Provisioning profile not found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Internal deletion execution failure", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/provisioning/profiles/{profileId}/download": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Generates a fresh installer link.", "tags": [ "Provisioning" ], "summary": "Download installer", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Provisioning Profile ID (UUID)", "name": "profileId", "in": "path", "required": true }, { "type": "boolean", "description": "Bake the target fleet's current container image into the installer (default false)", "name": "preload_workload", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved binary download links", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Organization ID header is required or bad Profile ID format", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Authentication token missing", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Access denied context", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Installer binary target not found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "500": { "description": "Error rendering sign contexts", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/provisioning/profiles/{profileId}/status": { "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Enable or disable a provisioning profile.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Provisioning" ], "summary": "Update profile status", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Provisioning Profile ID (UUID)", "name": "profileId", "in": "path", "required": true }, { "description": "Status update request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UpdateProfileStatusRequest" } } ], "responses": { "200": { "description": "Enabled or disabled profile successfully", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Invalid Profile id or body formatting payload", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Unauthorized access token", "schema": { "$ref": "#/definitions/controllers.Response" } }, "403": { "description": "Caller does not have required permissions", "schema": { "$ref": "#/definitions/controllers.Response" } }, "404": { "description": "Profile not found", "schema": { "$ref": "#/definitions/controllers.Response" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Could not update status changes", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/registry-credentials": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get a paginated list of registry credentials within an organisation. NOTE: This handler emits a non-standard envelope where `pagination` is a sibling of `data` rather than nested inside it.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Registry Credentials" ], "summary": "List registry credentials", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Items per page", "name": "limit", "in": "query" }, { "type": "string", "description": "Search term", "name": "search", "in": "query" }, { "type": "string", "description": "Sort field", "name": "sortBy", "in": "query" }, { "type": "string", "description": "Sort direction", "name": "sortOrder", "in": "query" } ], "responses": { "200": { "description": "Paginated registry credentials with pagination metadata as a sibling of data; secret material is redacted", "schema": { "$ref": "#/definitions/controllers.ListCredentialsEnvelope" } }, "400": { "description": "Organisation context header missing or invalid, or invalid pagination parameters", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have permission to list credentials in this organisation", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "500": { "description": "Failed to query credentials", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } }, "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Create a new container registry credential. Supports basic auth and AWS ECR.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Registry Credentials" ], "summary": "Create registry credential", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Credential details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CreateCredentialRequest" } } ], "responses": { "201": { "description": "Credential created (secret material redacted in the response)", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/registrycredential.RegistryCredential" } } } ] } }, "400": { "description": "Missing organisation context, malformed JSON, or required credential field missing for the chosen type", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Request blocked by the WAF", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to persist credential", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/registry-credentials/{credentialId}": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Get the details of a specific registry credential. Secret material is redacted in the response.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Registry Credentials" ], "summary": "Get registry credential", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Credential ID (UUID)", "name": "credentialId", "in": "path", "required": true } ], "responses": { "200": { "description": "Credential metadata (secret material redacted)", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/registrycredential.RegistryCredential" } } } ] } }, "400": { "description": "Organisation context header missing or invalid, or malformed credential ID", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have access to this credential", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Credential does not exist in this organisation", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to retrieve credential", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } }, "put": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Update an existing registry credential. Only fields supplied in the request body are modified; omitted fields are left unchanged.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Registry Credentials" ], "summary": "Update registry credential", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Credential ID (UUID)", "name": "credentialId", "in": "path", "required": true }, { "description": "Credential update payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UpdateCredentialRequest" } } ], "responses": { "200": { "description": "Credential updated (secret material redacted in the response)", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/registrycredential.RegistryCredential" } } } ] } }, "400": { "description": "Missing organisation context, malformed JSON, malformed credential ID, required field missing, field not allowed for this credential type, or unknown credential type", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Request blocked by the WAF", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "404": { "description": "Credential does not exist in this organisation", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to persist credential update", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } }, "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Delete a registry credential. Fails if the credential is currently in use.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Registry Credentials" ], "summary": "Delete registry credential", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Credential ID (UUID)", "name": "credentialId", "in": "path", "required": true } ], "responses": { "200": { "description": "Credential deleted", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Organisation context header missing or invalid, or malformed credential ID", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have permission to delete this credential", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Credential does not exist in this organisation", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "409": { "description": "Credential is currently referenced by one or more configurations and cannot be deleted", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "500": { "description": "Failed to delete credential", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/rollouts": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Rollouts" ], "summary": "List rollouts", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "minimum": 1, "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "maximum": 1000, "minimum": 1, "type": "integer", "default": 50, "description": "Items per page", "name": "limit", "in": "query" }, { "type": "string", "description": "Filter by status (comma-separated)", "name": "status", "in": "query" }, { "type": "string", "description": "Only rollouts targeting this fleet (comma-separated UUIDs)", "name": "fleet_id", "in": "query" }, { "type": "string", "description": "Search term", "name": "search", "in": "query" } ], "responses": { "200": { "description": "Paginated rollouts", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing organisation context, invalid fleet_id or status", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "500": { "description": "Failed to retrieve rollouts", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } }, "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Create and start a rollout to one or more fleets. Supports configuration, system update, reboot, and workload restart rollouts.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Rollouts" ], "summary": "Create rollout", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Rollout details", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CreateRolloutRequest" } } ], "responses": { "201": { "description": "Rollout created and workflow started", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.RolloutDTO" } } } ] } }, "202": { "description": "Rollout persisted but workflow failed to start; resubmit via the start endpoint", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.RolloutCreatedAcceptedResponse" } } } ] } }, "400": { "description": "Invalid JSON body, missing name/type/fleet_ids, or spec mismatch for type", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied to rollout execution", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "415": { "description": "Unsupported Content-Type (WAF)", "schema": { "$ref": "#/definitions/controllers.WAFBlockedResponse" } }, "500": { "description": "Failed to create rollout", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/rollouts/impact": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Estimate how many devices a rollout would affect.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Rollouts" ], "summary": "Calculate rollout impact", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Impact query", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.CalculateImpactRequest" } } ], "responses": { "200": { "description": "Estimated impact", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing/invalid fleet_ids or type", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } } } } }, "/rollouts/{rolloutId}": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Rollouts" ], "summary": "Get rollout", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Rollout ID (UUID)", "name": "rolloutId", "in": "path", "required": true } ], "responses": { "200": { "description": "Rollout detail", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Invalid rollout ID format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Rollout not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to load rollout", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } }, "delete": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Rollouts" ], "summary": "Delete rollout", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Rollout ID (UUID)", "name": "rolloutId", "in": "path", "required": true } ], "responses": { "200": { "description": "Rollout deleted", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Invalid rollout ID format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Rollout not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to delete rollout", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/rollouts/{rolloutId}/cancel": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Stops the rollout for good. Every device returns to its fleet's configuration version: pins held by the rollout are released. To keep a different version, set the fleet's configuration version. Rows still in flight end as cancelled. 409 when the rollout is terminal.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Rollouts" ], "summary": "Cancel a rollout", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Rollout ID (UUID)", "name": "rolloutId", "in": "path", "required": true }, { "description": "Optional reason", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.RolloutControlRequest" } } ], "responses": { "202": { "description": "Accepted", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.RolloutControlResponse" } } } ] } }, "400": { "description": "Invalid body", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Rollout not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "409": { "description": "Rollout state does not allow this action", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/rollouts/{rolloutId}/devices": { "get": { "security": [ { "BearerAuth": [] } ], "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Rollout ID (UUID)", "name": "rolloutId", "in": "path", "required": true }, { "minimum": 1, "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "minimum": 1, "type": "integer", "default": 50, "description": "Items per page", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Devices list", "schema": { "$ref": "#/definitions/controllers.RolloutDevicesEnvelope" } }, "404": { "description": "Rollout not found", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/rollouts/{rolloutId}/devices/active": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Rollouts" ], "summary": "List active rollout devices", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Rollout ID (UUID)", "name": "rolloutId", "in": "path", "required": true } ], "responses": { "200": { "description": "Active devices in rollout", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Invalid rollout ID format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "500": { "description": "Failed to load active devices", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/rollouts/{rolloutId}/devices/failed": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Rollouts" ], "summary": "List failed rollout devices", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Rollout ID (UUID)", "name": "rolloutId", "in": "path", "required": true }, { "type": "string", "description": "Filter by error type", "name": "error_type", "in": "query" } ], "responses": { "200": { "description": "Failed devices in rollout", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Invalid rollout ID format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "500": { "description": "Failed to load failed devices", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/rollouts/{rolloutId}/devices/{deviceId}": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Rollouts" ], "summary": "Get rollout device status", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Rollout ID (UUID)", "name": "rolloutId", "in": "path", "required": true }, { "type": "string", "format": "uuid", "description": "Device ID (UUID)", "name": "deviceId", "in": "path", "required": true } ], "responses": { "200": { "description": "Per-device rollout status", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Invalid rollout or device ID format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Authentication required", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Rollout or device not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "500": { "description": "Failed to load device rollout status", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/rollouts/{rolloutId}/pause": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Stops admitting devices. Devices already admitted continue to converge. Idempotent on a paused rollout. 409 when the rollout is terminal or predates the scheduler.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Rollouts" ], "summary": "Pause a rollout", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Rollout ID (UUID)", "name": "rolloutId", "in": "path", "required": true }, { "description": "Optional reason", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.RolloutControlRequest" } } ], "responses": { "202": { "description": "Accepted", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.RolloutControlResponse" } } } ] } }, "400": { "description": "Invalid body", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Rollout not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "409": { "description": "Rollout state does not allow this action", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/rollouts/{rolloutId}/resume": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Re-opens admission and acknowledges the current failures: the failure and unavailable budgets count new failures from now on. 409 when the rollout is not paused.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Rollouts" ], "summary": "Resume a paused rollout", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Rollout ID (UUID)", "name": "rolloutId", "in": "path", "required": true }, { "description": "Optional reason", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.RolloutControlRequest" } } ], "responses": { "202": { "description": "Accepted", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.RolloutControlResponse" } } } ] } }, "400": { "description": "Invalid body", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Rollout not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "409": { "description": "Rollout state does not allow this action", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/rollouts/{rolloutId}/rollback": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Reverts every admitted device to the fleet configuration and ends the rollout as rolled_back. Devices that were never admitted are untouched. Configuration rollouts only (409 otherwise).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Rollouts" ], "summary": "Roll back a rollout", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Rollout ID (UUID)", "name": "rolloutId", "in": "path", "required": true }, { "description": "Optional reason", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/controllers.RolloutControlRequest" } } ], "responses": { "202": { "description": "Accepted", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.RolloutControlResponse" } } } ] } }, "400": { "description": "Invalid body", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Rollout not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } }, "409": { "description": "Rollout state does not allow this action", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/rollouts/{rolloutId}/stop": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Stop or cancel an in-flight rollout.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Rollouts" ], "summary": "Stop rollout", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Rollout ID", "name": "rolloutId", "in": "path", "required": true } ], "responses": { "200": { "description": "Rollout stopped/cancelled", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Missing rollout parameters or invalid format", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Caller does not have required permissions", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "500": { "description": "Failed to stop rollout", "schema": { "$ref": "#/definitions/controllers.InternalServerErrorResponse" } } } } }, "/rollouts/{rolloutId}/stream": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "description": "Server-sent events. \"rollout\" events carry {rolloutId, status, pausedReason, stage, counts{targets, admitted, inFlight, converged, failed, stuck, pendingReconnect, dropped}, at} on every change after connect (the state at connect is not re-sent unless the rollout is already terminal; read it from GET /rollouts/{id}); \"device\" events carry {deviceId, phase, progress, at} on every phase or progress change of an admitted device. A comment keepalive is sent every 25 s; on each one the caller's credential and organisation access are checked again. The stream ends after the rollout reaches a terminal status, or with a final \"end\" event ({reason: unauthorized|lifetime}) when that check fails or after 30 minutes; clients reconnect. Use GET /rollouts/{id} and /rollouts/{id}/devices for the initial state.", "produces": [ "text/event-stream" ], "tags": [ "Rollouts" ], "summary": "Stream rollout progress", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "format": "uuid", "description": "Rollout ID (UUID)", "name": "rolloutId", "in": "path", "required": true } ], "responses": { "200": { "description": "event: rollout (and event: device with rolloutservice.DeviceStreamEvent)", "schema": { "$ref": "#/definitions/rolloutservice.RolloutStreamSummary" } }, "403": { "description": "Access denied", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Rollout not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } } } } }, "/search": { "get": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Search" ], "summary": "Perform Global Search", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "type": "string", "description": "Search query string", "name": "q", "in": "query", "required": true }, { "type": "integer", "default": 20, "description": "Max count of items to fetch", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Search completed successfully", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Search query is required", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/search/advanced": { "post": { "security": [ { "ApiSecretAuth": [], "ApiTokenAuth": [] }, { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Search" ], "summary": "Advanced Search query", "parameters": [ { "type": "string", "description": "Organisation ID", "name": "X-Organization-ID", "in": "header", "required": true }, { "description": "Advanced filters", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/searchservice.AdvancedSearchParams" } } ], "responses": { "200": { "description": "Advanced search completed successfully", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Invalid body payload structure", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/settings": { "get": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Settings" ], "summary": "Fetch system configurations and settings", "responses": { "200": { "description": "Settings payload retrieved", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.SettingsResponse" } } } ] } }, "401": { "description": "Identity required", "schema": { "$ref": "#/definitions/controllers.Response" } } } }, "put": { "security": [ { "BearerAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Settings" ], "summary": "Update system settings values", "parameters": [ { "description": "Update payload request body", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/controllers.UpdateSettingsRequest" } } ], "responses": { "200": { "description": "Settings updated successfully", "schema": { "$ref": "#/definitions/controllers.Response" } }, "400": { "description": "Malformed payload structure", "schema": { "$ref": "#/definitions/controllers.Response" } } } } }, "/system/minimum-versions": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List the minimum component version floors that gate device onboarding", "tags": [ "System" ], "summary": "List Minimum Versions", "responses": { "200": { "description": "Configured floors", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/system.MinimumVersion" } } } } ] } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Requires global admin", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Set (or raise) the minimum version for a component/architecture/board. Omit board to apply to all boards on the architecture.", "tags": [ "System" ], "summary": "Set Minimum Version", "parameters": [ { "description": "Floor definition", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/system.SetMinimumVersionRequest" } } ], "responses": { "200": { "description": "Floor stored", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/system.MinimumVersion" } } } ] } }, "400": { "description": "Invalid payload", "schema": { "$ref": "#/definitions/controllers.BadRequestResponse" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Requires global admin", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } } } } }, "/system/minimum-versions/breaches": { "get": { "security": [ { "BearerAuth": [] } ], "description": "List devices that failed a minimum-version floor at onboarding and are retrying a mandatory update. High attempt counts, or remediable=false, indicate the remediation is not working.", "tags": [ "System" ], "summary": "List Minimum Version Breaches", "responses": { "200": { "description": "Devices below a floor", "schema": { "allOf": [ { "$ref": "#/definitions/controllers.Response" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/system.FloorBreachRecord" } } } } ] } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Requires global admin", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } } } } }, "/system/minimum-versions/{minimumId}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Remove a minimum version floor, allowing devices on older builds to onboard again", "tags": [ "System" ], "summary": "Delete Minimum Version", "parameters": [ { "type": "string", "format": "uuid", "description": "Minimum version ID (UUID)", "name": "minimumId", "in": "path", "required": true } ], "responses": { "200": { "description": "Floor removed", "schema": { "$ref": "#/definitions/controllers.Response" } }, "401": { "description": "Caller is not authenticated", "schema": { "$ref": "#/definitions/controllers.UnauthorizedResponse" } }, "403": { "description": "Requires global admin", "schema": { "$ref": "#/definitions/controllers.ForbiddenResponse" } }, "404": { "description": "Floor not found", "schema": { "$ref": "#/definitions/controllers.NotFoundResponse" } } } } }, "/user/mcp-grants": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Active grants of the signed-in user (portal session only).", "produces": [ "application/json" ], "tags": [ "MCP Connector" ], "summary": "List connected MCP apps", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/user/mcp-grants/{grantId}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Revokes the grant and every access and refresh token that belongs to it.", "produces": [ "application/json" ], "tags": [ "MCP Connector" ], "summary": "Disconnect an MCP app", "parameters": [ { "type": "string", "description": "Grant id", "name": "grantId", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } } } } }, "/user/sessions": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Browser sessions, admrl-cli tokens, personal API tokens and connected MCP apps (portal session only). Current session first, then most recently used.", "produces": [ "application/json" ], "tags": [ "Sessions" ], "summary": "List sessions and access", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/user/sessions/revoke-all": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Browser sessions (Firebase refresh tokens + cutoff), CLI tokens and MCP grants. Personal API tokens only with include_api_tokens. keep_current spares the calling browser session.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Sessions" ], "summary": "Revoke all sessions and access", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/user/sessions/{type}/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "tags": [ "Sessions" ], "summary": "Revoke a session or access credential", "parameters": [ { "type": "string", "description": "browser | cli | api_token | mcp", "name": "type", "in": "path", "required": true }, { "type": "string", "description": "Credential id from the list", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "schema": { "type": "object", "additionalProperties": true } } } } }, "/user/ssh-keys": { "get": { "tags": [ "Users" ], "summary": "List my SSH public keys", "responses": {} }, "post": { "description": "Registers a public key so the signed-in user can log in over `admrl ssh` to every device they have shell access to, with the matching private key. Only bare public keys are accepted (ed25519, ecdsa, rsa \u003e= 2048 bits).", "tags": [ "Users" ], "summary": "Register an SSH public key", "responses": {} } }, "/user/ssh-keys/{keyId}": { "delete": { "tags": [ "Users" ], "summary": "Remove an SSH public key", "responses": {} } } }, "definitions": { "airdetect.Bucketed": { "type": "object", "properties": { "key": { "type": "string" }, "person_minutes": { "type": "number" }, "person_seconds": { "type": "number" }, "share": { "description": "Share is this bucket's fraction of total visitor_count for the period\n(0..1). Convenience for the UI; computed at amalgamation time.", "type": "number" }, "visitor_count": { "type": "integer" } } }, "assistantbudget.Decision": { "type": "object", "properties": { "allowed": { "description": "Allowed is false when the request must be refused with 402.", "type": "boolean" }, "hasPaymentMethod": { "type": "boolean" }, "includedCreditCents": { "description": "Included credit for this period (default 500).", "type": "integer" }, "limitCents": { "description": "Hard limit for this organisation this period: the credit for trials\nand organisations without a payment method, otherwise the monthly cap.", "type": "integer" }, "periodEnd": { "type": "string" }, "periodStart": { "type": "string" }, "priced": { "description": "Priced is false while staff have not set usage plans for the token\nproducts: spend is then 0 and only the rate limits apply.", "type": "boolean" }, "reason": { "description": "Reason is empty when Allowed, otherwise billing.ReasonAssistantCreditExhausted,\nbilling.ReasonAssistantCapReached or billing.ReasonAccountSuspended.", "type": "string" }, "spendCents": { "description": "Spend so far this period at the prices in force, before the credit.", "type": "integer" }, "trial": { "description": "Trial / payment-method state that chose LimitCents.", "type": "boolean" } } }, "billing.AddonUsage": { "type": "object", "properties": { "billable_days": { "type": "integer" }, "enabled": { "type": "boolean" }, "feature": { "type": "string" }, "fee_cents": { "description": "prorated so far", "type": "integer" }, "monthly_fee_cents": { "type": "integer" }, "period_days": { "type": "integer" }, "priced": { "type": "boolean" }, "product_id": { "type": "string" } } }, "billing.CatalogPrice": { "type": "object", "properties": { "allowances": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" } }, "currency": { "type": "string" }, "effective_from": { "type": "string" }, "monthly_fee_cents": { "description": "Add-on products: monthly block fee and included units per period (raw\nunits; average active series for telemetry_metric_series).", "type": "integer" }, "plan_id": { "type": "string" }, "plan_name": { "type": "string" }, "source": { "description": "\"global\" | \"org\" | \"inherited\"", "type": "string" }, "tier_model": { "$ref": "#/definitions/billing.TierModel" }, "tiers": { "type": "array", "items": { "$ref": "#/definitions/billing.PricingTier" } }, "unit_price_micro_cents": { "description": "Usage products: price per billing unit in micro-cents.", "type": "integer" } } }, "billing.CatalogProduct": { "type": "object", "properties": { "addon_id": { "description": "AddonID is set on usage products included in an add-on block.", "type": "string" }, "description": { "type": "string" }, "feature": { "description": "Feature is set on add-ons and on usage products included in an add-on\n(\"telemetry\"): their usage bills only through that add-on.", "type": "string" }, "id": { "type": "string" }, "kind": { "description": "ProductKind*", "type": "string" }, "name": { "type": "string" }, "org_overrides": { "description": "Admin catalogue only: number of orgs with their own plan for it.", "type": "integer" }, "price": { "description": "Price in effect now. Nil = not priced (usage recorded, nothing billed).", "allOf": [ { "$ref": "#/definitions/billing.CatalogPrice" } ] }, "raw_per_unit": { "description": "raw units per billing unit (1, GiB, 60)", "type": "integer" }, "raw_unit": { "description": "stored counter unit: \"request\", \"byte\", \"series_day\", \"person_second\", \"\"", "type": "string" }, "unit": { "description": "billing unit: \"device\", \"request\", \"GiB\", \"series_day\", \"person_minute\", \"month\"", "type": "string" } } }, "billing.EdgeWireEntitlements": { "type": "object", "properties": { "enabled": { "description": "Enabled lets the organisation open EdgeWire sessions.", "type": "boolean" }, "included_relay_gb": { "description": "IncludedRelayGB is the relayed volume per month before overage billing.", "type": "integer" }, "internal": { "description": "Internal marks Admiral's own organisation: bypasses the entitlement\ncheck (never FGA) and allows the NATS packet fallback.", "type": "boolean" }, "max_session_mbps": { "description": "MaxSessionMbps caps one session's egress; nil is no cap.", "type": "integer" }, "max_sessions_per_device": { "description": "MaxSessionsPerDevice and MaxStreamsPerSession: 0 stored means the\ndefault (EdgeWireDefaultMax*); Effective resolves it.", "type": "integer" }, "max_streams_per_session": { "type": "integer" }, "relay": { "description": "Relay lets sessions use the TURN relay. Without it grants carry STUN\nonly and no TURN credentials.", "type": "boolean" } } }, "billing.PreviewLine": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "description": { "type": "string" }, "kind": { "description": "metadata plan_kind", "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "product_id": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" } } }, "billing.PricingTier": { "type": "object", "properties": { "flat_fee_cents": { "type": "integer" }, "name": { "type": "string" }, "unit_price_cents": { "type": "integer" }, "unit_price_micro_cents": { "description": "UnitPriceMicroCents is an optional sub-cent per-unit rate for usage-based\nproducts (e.g. airdetect at $0.00002/person-minute = 20 micro-cents).\nWhen non-zero it takes precedence over UnitPriceCents for usage plans.\n1 cent = 10,000 micro-cents.", "type": "integer" }, "up_to_units": { "type": "integer" } } }, "billing.PricingView": { "type": "object", "properties": { "currency": { "type": "string" }, "products": { "type": "array", "items": { "$ref": "#/definitions/billing.CatalogProduct" } } } }, "billing.TierModel": { "type": "string", "enum": [ "flat", "graduated", "volume", "package" ], "x-enum-comments": { "TierFlat": "one price per unit, flat_fee added once", "TierGraduated": "tier N applies to units in range (tier[N-1], tier[N]]", "TierPackage": "ceil(units / package_size) * package_price", "TierVolume": "all units priced at the tier total lands in" }, "x-enum-descriptions": [ "one price per unit, flat_fee added once", "tier N applies to units in range (tier[N-1], tier[N]]", "all units priced at the tier total lands in", "ceil(units / package_size) * package_price" ], "x-enum-varnames": [ "TierFlat", "TierGraduated", "TierVolume", "TierPackage" ] }, "billing.UsageDay": { "type": "object", "properties": { "api": { "type": "integer" }, "billable": { "description": "Billable is false on trial days and, for add-on products, on days the\nadd-on was off (free tier).", "type": "boolean" }, "day": { "type": "string" }, "raw": { "type": "integer" }, "ui": { "description": "Channel split for telemetry API products (raw units); omitted elsewhere.", "type": "integer" } } }, "billing.UsageProductSummary": { "type": "object", "properties": { "addon_id": { "type": "string" }, "allowance_raw": { "description": "Add-on allowance products: prorated allowance and the split.", "type": "integer" }, "billable_raw": { "type": "integer" }, "cost_cents": { "description": "Cost so far in cents (overage for allowance products, the usage line\nfor usage products, the fee for add-ons, the device line for devices).", "type": "integer" }, "days": { "type": "array", "items": { "$ref": "#/definitions/billing.UsageDay" } }, "included_raw": { "type": "integer" }, "kind": { "type": "string" }, "name": { "type": "string" }, "overage_raw": { "type": "integer" }, "priced": { "type": "boolean" }, "product_id": { "type": "string" }, "raw_per_unit": { "type": "integer" }, "total_raw": { "type": "integer" }, "unit": { "type": "string" } } }, "billing.UsageView": { "type": "object", "properties": { "addons": { "type": "array", "items": { "$ref": "#/definitions/billing.AddonUsage" } }, "as_of": { "type": "string" }, "currency": { "type": "string" }, "lines": { "description": "Lines is the invoice preview for the period so far, as the invoice\ngenerator would produce it today (same code path).", "type": "array", "items": { "$ref": "#/definitions/billing.PreviewLine" } }, "organisation_id": { "type": "string" }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "products": { "type": "array", "items": { "$ref": "#/definitions/billing.UsageProductSummary" } }, "subtotal_cents": { "type": "integer" } } }, "billingservice.FeatureStatus": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "enabled_at": { "type": "string" }, "self_serve": { "type": "boolean" } } }, "billingservice.FeaturesView": { "type": "object", "properties": { "enterprise": { "type": "boolean" }, "features": { "type": "object", "additionalProperties": { "$ref": "#/definitions/billingservice.FeatureStatus" } }, "staff_override": { "description": "StaffOverride is true when the caller is an Admiral platform admin on a\nportal session: the API does not apply the 402 gates for them, so the\ndashboard should not lock anything either. Features still show the\norganisation's real state.", "type": "boolean" }, "telemetry_free_window_hours": { "type": "integer" } } }, "configservice.ConfigurationSummary": { "type": "object", "properties": { "created_at": { "type": "string" }, "created_by": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "latest_version": { "type": "integer" }, "name": { "type": "string" }, "status": { "$ref": "#/definitions/configuration.ConfigStatus" }, "tags": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } } }, "configservice.DuplicateConfigRequest": { "type": "object", "properties": { "description": { "description": "Description; absent = the source's.", "type": "string" }, "name": { "description": "Name of the new configuration (required).", "type": "string" }, "version": { "description": "Version of the source to copy; 0 or absent = the latest.", "type": "integer" } } }, "configservice.DuplicateConfigResult": { "type": "object", "properties": { "configuration": { "$ref": "#/definitions/configservice.DuplicatedConfig" }, "skipped": { "type": "array", "items": { "$ref": "#/definitions/configservice.SkippedConfigField" } }, "sourceVersion": { "type": "integer" } } }, "configservice.DuplicatedConfig": { "type": "object", "properties": { "id": { "type": "string" }, "latestVersion": { "type": "integer" }, "name": { "type": "string" } } }, "configservice.SkippedConfigField": { "type": "object", "properties": { "field": { "type": "string" }, "reason": { "type": "string" } } }, "configuration.ConfigStatus": { "type": "string", "enum": [ "draft", "active", "testing", "deprecated", "archived" ], "x-enum-comments": { "ConfigStatusActive": "Ready for use", "ConfigStatusArchived": "Archived", "ConfigStatusDeprecated": "No longer recommended", "ConfigStatusDraft": "Being edited", "ConfigStatusTesting": "Being tested" }, "x-enum-descriptions": [ "Being edited", "Ready for use", "Being tested", "No longer recommended", "Archived" ], "x-enum-varnames": [ "ConfigStatusDraft", "ConfigStatusActive", "ConfigStatusTesting", "ConfigStatusDeprecated", "ConfigStatusArchived" ] }, "configuration.Configuration": { "type": "object", "properties": { "created_at": { "type": "string" }, "created_by": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "latest_version": { "description": "Current version number", "type": "integer" }, "name": { "description": "Not unique - just a display name", "type": "string" }, "organisation_id": { "type": "string" }, "status": { "$ref": "#/definitions/configuration.ConfigStatus" }, "tags": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } } }, "configuration.ConfigurationSpec": { "type": "object", "properties": { "command": { "description": "Command and arguments to run instead of the image default.", "type": "array", "items": { "type": "string" } }, "desiredState": { "description": "Whether the workload should run or stop; defaults to RUNNING.", "type": "string", "enum": [ "RUNNING", "STOPPED" ], "example": "RUNNING" }, "edgewire": { "description": "EdgeWire names container-only services; managed through configuration versions.", "allOf": [ { "$ref": "#/definitions/configuration.EdgeWireConfiguration" } ] }, "environment": { "description": "Environment variables supplied to the workload.", "type": "object", "additionalProperties": { "type": "string" } }, "image": { "description": "Container image reference to pull and run.", "type": "string" }, "mounts": { "description": "Additional filesystem mounts; devices accept tmpfs or sources under /dev.", "type": "array", "items": { "$ref": "#/definitions/configuration.Mount" } }, "options": { "description": "Runtime options for the workload.", "allOf": [ { "$ref": "#/definitions/configuration.ContainerOptions" } ] }, "ports": { "description": "Container ports to publish on the device.", "type": "array", "items": { "$ref": "#/definitions/configuration.Port" } }, "registry_credential_id": { "description": "Saved registry credential used to pull private images.", "type": "string" }, "signaturePolicy": { "description": "Image-signature trust settings; inherits organisation and fleet requirements when omitted.", "allOf": [ { "$ref": "#/definitions/container.SignaturePolicy" } ] }, "volumes": { "description": "Named persistent volumes mounted into the workload.", "type": "object", "additionalProperties": { "$ref": "#/definitions/configuration.VolumeMount" } } } }, "configuration.ConfigurationVersion": { "type": "object", "properties": { "change_reason": { "type": "string" }, "changed_by": { "type": "string" }, "configuration_id": { "description": "Parent config", "type": "string" }, "created_at": { "type": "string" }, "id": { "description": "Unique version UUID", "type": "string" }, "is_rollback": { "type": "boolean" }, "rolled_back_from": { "type": "integer" }, "rolled_back_to": { "type": "integer" }, "spec": { "$ref": "#/definitions/configuration.ConfigurationSpec" }, "version_label": { "description": "Optional: \"v1.0.0\", \"stable\", etc.", "type": "string" }, "version_number": { "description": "v1, v2, v3, etc.", "type": "integer" } } }, "configuration.ContainerOptions": { "type": "object", "properties": { "all_devices_allowed": { "description": "Allow host devices instead of isolating device access.", "type": "boolean" }, "capabilities": { "description": "Legacy capability list; current devices use their built-in capabilities.", "type": "array", "items": { "type": "string" } }, "cgroup": { "description": "Legacy control-group path; not applied by current devices.", "type": "string" }, "devices": { "description": "Legacy device list; not applied by current devices.", "type": "array", "items": { "type": "string" } }, "disableHostBluetooth": { "description": "Stop the host Bluetooth service while the workload owns Bluetooth.", "type": "boolean" }, "ephemeral_root": { "description": "Use a temporary writable root layer that is discarded when the workload stops.", "type": "boolean" }, "exposeDBus": { "description": "Expose the host system D-Bus socket to the workload.", "type": "boolean" }, "host_hosts_file": { "description": "Request use of the host hosts file.", "type": "boolean" }, "host_namespaces": { "description": "Share host networking using network or net; other values have no effect on current devices.", "type": "array", "items": { "type": "string", "enum": [ "network", "net" ] }, "example": [ "network" ] }, "host_resolvconf": { "description": "Request use of the host DNS resolver configuration.", "type": "boolean" }, "image_cleaning": { "description": "Image retention and scheduled cleanup settings.", "allOf": [ { "$ref": "#/definitions/configuration.ImageCleaningPolicy" } ] }, "masked_paths": { "description": "Legacy paths to hide; current devices use their built-in path restrictions.", "type": "array", "items": { "type": "string" } }, "new_privileges": { "description": "Legacy privilege setting; not applied by current devices.", "type": "boolean" }, "parent_cgroup_devices": { "description": "Legacy parent-device setting; not applied by current devices.", "type": "boolean" }, "privileged": { "description": "Legacy privileged-mode setting; not applied by current devices.", "type": "boolean" }, "read_only_root": { "description": "Mount the container root filesystem read-only.", "type": "boolean" }, "readonly_paths": { "description": "Legacy read-only paths; current devices use their built-in path restrictions.", "type": "array", "items": { "type": "string" } }, "tty": { "description": "Let the workload own the device screen and input instead of the status display.", "type": "boolean" } } }, "configuration.EdgeWireConfiguration": { "type": "object", "properties": { "services": { "description": "Services is the complete named container-only service allowlist.", "type": "array", "items": { "$ref": "#/definitions/container.EdgeWireService" } } } }, "configuration.ImageCleaningPolicy": { "type": "object", "properties": { "enabled": { "description": "Allow unused images to be removed; false disables image removal.", "type": "boolean" }, "interval_hours": { "description": "Hours between scheduled cleanup runs; defaults to 24 when zero.", "type": "integer" }, "max_age_days": { "description": "Legacy age limit; current devices clean unneeded images regardless of age.", "type": "integer" }, "prune_dangling": { "description": "Legacy dangling-image switch; current devices clean unneeded images automatically.", "type": "boolean" }, "prune_on_update": { "description": "Legacy update-cleanup switch; current devices clean unneeded images automatically.", "type": "boolean" }, "retention_count": { "description": "Number of recent image versions to retain, with at least one previous version kept for rollback.", "type": "integer" } } }, "configuration.Mount": { "type": "object", "properties": { "destination": { "description": "Mount path inside the container.", "type": "string", "example": "/data" }, "options": { "description": "Linux mount options, such as ro, rw, rbind, or mode=1777.", "type": "array", "items": { "type": "string" } }, "source": { "description": "Mount source; non-tmpfs sources must be /dev or a path beneath it.", "type": "string" }, "type": { "description": "Filesystem mount type, such as bind or tmpfs.", "type": "string", "example": "bind" } } }, "configuration.Port": { "type": "object", "properties": { "port": { "description": "Container port number, from 1 to 65535.", "type": "integer", "example": 1234 }, "protocol": { "description": "Transport protocol; defaults to tcp when omitted.", "type": "string", "enum": [ "tcp", "udp" ], "example": "tcp" } } }, "configuration.VolumeMount": { "type": "object", "properties": { "destination": { "description": "Volume mount path inside the container.", "type": "string", "example": "/data" }, "options": { "description": "Linux mount options for the volume, such as rbind and rw.", "type": "array", "items": { "type": "string" } }, "source": { "description": "Host directory used as the persistent volume source.", "type": "string" } } }, "container.ContainerRollback": { "type": "object", "properties": { "at": { "type": "string" }, "failures": { "type": "integer" }, "fromConfigurationName": { "type": "string" }, "fromImage": { "type": "string" }, "fromVersion": { "type": "integer" }, "reason": { "type": "string" }, "toVersion": { "type": "integer" } } }, "container.ContainerStatus": { "type": "object", "properties": { "configurationName": { "description": "Applied configuration identity currently on the device. Optional so older\nedges that omit these keys remain decode-compatible. Backend looks up the\nfull configuration from configurationName + image + version. Workload\nName is not sent — it is almost always \"default\".", "type": "string" }, "error": { "type": "string" }, "image": { "type": "string" }, "rollback": { "description": "Rollback is set while the device is refusing a configuration it rolled\nback from. The applied identity above is the configuration it fell back\nto. Cleared once a different configuration is applied. Optional so older\npeers keep decoding the rest of the struct.", "allOf": [ { "$ref": "#/definitions/container.ContainerRollback" } ] }, "secretFiles": { "description": "SecretFiles reports per-file apply status (metadata only, never content).", "type": "array", "items": { "$ref": "#/definitions/container.SecretFileStatus" } }, "signature": { "description": "Signature reports the image-signature verification result for the applied\n(or, while a transition is refused, the rejected) image. Nil when the\ndevice has no policy or an older agent.", "allOf": [ { "$ref": "#/definitions/container.SignatureStatus" } ] }, "startedAt": { "type": "string" }, "state": { "description": "e.g., \"RUNNING\", \"STOPPED\", \"ERROR\", \"CRASHING\", \"STAGING\", \"STAGED\"", "type": "string" }, "transition": { "description": "In-flight transition / update progress (omitted during steady state)", "allOf": [ { "$ref": "#/definitions/container.ContainerTransition" } ] }, "version": { "type": "integer" } } }, "container.ContainerTransition": { "type": "object", "properties": { "message": { "description": "e.g. \"Downloading layer 2/5\"", "type": "string" }, "state": { "description": "e.g. \"resolving\", \"downloading\", \"extracting\", \"preparing\", \"staged\", \"starting\"", "type": "string" }, "targetVersion": { "type": "integer" } } }, "container.CosignKey": { "type": "object", "properties": { "name": { "description": "Optional label for this trusted key, up to 128 characters.", "type": "string" }, "publicKey": { "description": "PEM-encoded PKIX public key for ECDSA, Ed25519, or RSA signatures.", "type": "string" } } }, "container.EdgeWireService": { "type": "object", "properties": { "name": { "description": "Name uniquely identifies the service in workload-forward grants.", "type": "string" }, "port": { "description": "Port is the container-loopback port, between 1 and 65535.", "type": "integer" }, "protocol": { "description": "Protocol is tcp or udp.", "type": "string" } } }, "container.NotationTrust": { "type": "object", "properties": { "caCerts": { "description": "PEM-encoded root or intermediate certificates trusted for Notation signatures.", "type": "array", "items": { "type": "string" } }, "name": { "description": "Optional label for this trust store, up to 128 characters.", "type": "string" }, "trustedIdentities": { "description": "Allowed certificate subjects in RFC 2253 form, or * for any signer trusted by these certificates.", "type": "array", "items": { "type": "string" } } } }, "container.SecretFileStatus": { "type": "object", "properties": { "appliedAt": { "type": "string" }, "error": { "type": "string" }, "id": { "type": "string" }, "path": { "type": "string" }, "sha256": { "type": "string" }, "state": { "description": "\"applied\", \"unchanged\", \"failed\"", "type": "string" } } }, "container.SignaturePolicy": { "type": "object", "properties": { "cosignKeys": { "description": "Trusted Cosign public keys; a signature from any configured key is accepted.", "type": "array", "items": { "$ref": "#/definitions/container.CosignKey" } }, "notation": { "description": "Trusted Notation certificates and allowed signer identities.", "allOf": [ { "$ref": "#/definitions/container.NotationTrust" } ] }, "required": { "description": "Require a trusted image signature before running; cannot relax an organisation or fleet requirement.", "type": "boolean" } } }, "container.SignatureStatus": { "type": "object", "properties": { "digest": { "type": "string" }, "error": { "type": "string" }, "format": { "description": "\"cosign\" | \"notation\"", "type": "string" }, "required": { "type": "boolean" }, "signer": { "description": "cosign key name or notation leaf subject", "type": "string" }, "verified": { "type": "boolean" }, "verifiedAt": { "type": "string" } } }, "controllers.Accelerator": { "type": "object", "properties": { "driver": { "type": "string", "example": "nvdla" }, "integrated": { "description": "Integrated is true for SoC-integrated accelerators (DLA, PVA, NPU).", "type": "boolean", "example": true }, "model": { "type": "string", "example": "Google Edge TPU" }, "node": { "type": "string", "example": "/sys/devices/platform/15880000.nvdla0" }, "pci_device": { "$ref": "#/definitions/controllers.PCIDevice" }, "vendor": { "type": "string", "example": "Google" } } }, "controllers.AccessPointConfigRequest": { "type": "object", "required": [ "ssid" ], "properties": { "channel": { "type": "integer" }, "hidden": { "type": "boolean" }, "ip": { "$ref": "#/definitions/controllers.IPSettingsRequest" }, "psk": { "type": "string" }, "security": { "type": "string" }, "ssid": { "type": "string", "minLength": 1 } } }, "controllers.AddUserToFleetRequest": { "type": "object", "required": [ "role", "user_id" ], "properties": { "role": { "type": "string", "enum": [ "admin", "editor", "viewer" ], "example": "editor" }, "user_id": { "type": "string", "minLength": 1, "example": "oafrHUx6ZbftN340XV4JiA982Mo1" } } }, "controllers.AddressStatusResponse": { "type": "object", "properties": { "address": { "type": "string", "example": "192.168.1.42/24" }, "version": { "type": "string", "enum": [ "ipv4", "ipv6" ], "example": "ipv4" } } }, "controllers.AirdetectDeviceLivePresence": { "type": "object", "properties": { "device_id": { "type": "string", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, "oldest_arrival": { "type": "string", "example": "2024-09-12T14:05:00Z" }, "present_visitors": { "type": "integer", "example": 7 } } }, "controllers.AirdetectDeviceUsage": { "type": "object", "properties": { "device_id": { "type": "string", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, "person_minutes": { "type": "number", "example": 11050 }, "visitor_count": { "type": "integer", "example": 312 } } }, "controllers.AirdetectLivePresenceResponse": { "type": "object", "properties": { "as_of": { "type": "string", "example": "2024-09-12T14:30:00Z" }, "fleet_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "oldest_arrival": { "type": "string", "example": "2024-09-12T14:05:00Z" }, "present_visitors": { "type": "integer", "example": 42 } } }, "controllers.AirdetectStatusResponse": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true }, "enabled_at": { "type": "string", "example": "2024-09-12T14:30:00Z" }, "fleet_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } }, "controllers.AirdetectUsageResponse": { "type": "object", "properties": { "devices": { "type": "array", "items": { "$ref": "#/definitions/controllers.AirdetectDeviceUsage" } }, "estimated_cost_cents": { "type": "integer", "example": 904 }, "fleet_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "period_end": { "type": "string", "example": "2024-09-30T23:59:59Z" }, "period_start": { "type": "string", "example": "2024-09-01T00:00:00Z" }, "person_minutes": { "type": "number", "example": 45200.5 }, "visitor_count": { "type": "integer", "example": 1284 } } }, "controllers.AirdetectWindowInput": { "type": "object", "required": [ "end", "start" ], "properties": { "end": { "type": "string", "example": "2024-09-12T14:32:25Z" }, "label": { "type": "string", "example": "creative_42" }, "start": { "type": "string", "example": "2024-09-12T14:32:10Z" } } }, "controllers.AirdetectWindowPresenceResponse": { "type": "object", "properties": { "by_proximity": { "type": "array", "items": { "$ref": "#/definitions/airdetect.Bucketed" } }, "device_id": { "type": "string" }, "end": { "type": "string" }, "fleet_id": { "type": "string" }, "label": { "type": "string" }, "mean_dwell_in_window_seconds": { "type": "number" }, "peak_concurrent": { "type": "integer" }, "person_seconds_in_window": { "type": "number" }, "present_visitors": { "type": "integer" }, "start": { "type": "string" } } }, "controllers.AirdetectWindowsRequest": { "type": "object", "required": [ "windows" ], "properties": { "windows": { "type": "array", "items": { "$ref": "#/definitions/controllers.AirdetectWindowInput" } } } }, "controllers.AssignConfigurationRequest": { "type": "object", "required": [ "configuration_id" ], "properties": { "configuration_id": { "type": "string", "format": "uuid", "minLength": 1, "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, "version": { "type": "integer", "minimum": 1, "example": 2 } } }, "controllers.AssignmentCreatedData": { "type": "object", "properties": { "assignment": { "$ref": "#/definitions/iam.AssignmentView" }, "skipped": { "type": "array", "items": { "$ref": "#/definitions/iam.SkippedCapability" } } } }, "controllers.AssignmentListData": { "type": "object", "properties": { "assignments": { "type": "array", "items": { "$ref": "#/definitions/iam.AssignmentView" } }, "next_cursor": { "type": "string" }, "total": { "type": "integer" } } }, "controllers.AssistantDailyAllowance": { "type": "object", "properties": { "orgPercent": { "type": "integer" }, "userPercent": { "type": "integer" } } }, "controllers.AssistantDailyCost": { "type": "object", "properties": { "orgCents": { "type": "number" }, "orgLimitCents": { "type": "integer" }, "userCents": { "type": "number" }, "userLimitCents": { "type": "integer" } } }, "controllers.AssistantDailyTokens": { "type": "object", "properties": { "org": { "type": "integer" }, "orgLimit": { "type": "integer" }, "user": { "type": "integer" }, "userLimit": { "type": "integer" } } }, "controllers.AssistantTokensUsed": { "type": "object", "properties": { "cacheWrite": { "type": "integer" }, "cachedInput": { "type": "integer" }, "input": { "type": "integer" }, "output": { "type": "integer" } } }, "controllers.AssistantUsageResponse": { "type": "object", "properties": { "dailyAllowance": { "$ref": "#/definitions/controllers.AssistantDailyAllowance" }, "dailyCost": { "description": "staff only", "allOf": [ { "$ref": "#/definitions/controllers.AssistantDailyCost" } ] }, "dailyTokens": { "description": "deprecated: zero limits", "allOf": [ { "$ref": "#/definitions/controllers.AssistantDailyTokens" } ] }, "decision": { "$ref": "#/definitions/assistantbudget.Decision" }, "model": { "type": "string" }, "modelLabel": { "type": "string" }, "tokens": { "$ref": "#/definitions/controllers.AssistantTokensUsed" } } }, "controllers.BIOS": { "type": "object", "properties": { "date": { "type": "string", "example": "03/15/2023" }, "vendor": { "type": "string", "example": "Dell Inc." }, "version": { "type": "string", "example": "1.10.2" } } }, "controllers.BadRequestResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 400 }, "msg": { "type": "string", "example": "Invalid request payload" } } }, "controllers.Baseboard": { "type": "object", "properties": { "assetTag": { "type": "string", "example": "" }, "product": { "type": "string", "example": "0PHYC8" }, "serialNumber": { "type": "string", "example": ".7X9KQ3.CN701234" }, "vendor": { "type": "string", "example": "Dell Inc." }, "version": { "type": "string", "example": "A01" } } }, "controllers.BatteryStats": { "type": "object", "properties": { "capacity": { "type": "number", "example": 95.5 }, "current": { "type": "number", "example": 1.2 }, "status": { "description": "1: charging, -1: discharging, 0: full", "type": "integer", "example": 1 }, "voltage": { "type": "number", "example": 12.4 } } }, "controllers.BridgeConfigRequest": { "type": "object", "required": [ "member_macs", "name" ], "properties": { "ip": { "$ref": "#/definitions/controllers.IPSettingsRequest" }, "member_macs": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "minLength": 1 } } }, "controllers.BulkClaimHostAllFailedData": { "type": "object", "properties": { "failure_count": { "type": "integer", "example": 2 }, "results": { "type": "array", "items": { "$ref": "#/definitions/controllers.BulkClaimHostFailureResultExample" } }, "success_count": { "type": "integer", "example": 0 }, "total_requested": { "type": "integer", "example": 2 } } }, "controllers.BulkClaimHostAllFailedResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 400 }, "data": { "$ref": "#/definitions/controllers.BulkClaimHostAllFailedData" }, "msg": { "type": "string", "example": "Failed to claim any devices" } } }, "controllers.BulkClaimHostAllSuccessData": { "type": "object", "properties": { "failure_count": { "type": "integer", "example": 0 }, "results": { "type": "array", "items": { "$ref": "#/definitions/controllers.BulkClaimHostSuccessResultExample" } }, "success_count": { "type": "integer", "example": 2 }, "total_requested": { "type": "integer", "example": 2 } } }, "controllers.BulkClaimHostAllSuccessResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "data": { "$ref": "#/definitions/controllers.BulkClaimHostAllSuccessData" }, "msg": { "type": "string", "example": "All devices claimed successfully" } } }, "controllers.BulkClaimHostFailureResultExample": { "type": "object", "properties": { "error": { "type": "string", "example": "Device already claimed by another organisation" }, "index": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "edge-gateway-02" }, "pairing_key": { "type": "string", "example": "BCDEF" }, "success": { "type": "boolean", "example": false } } }, "controllers.BulkClaimHostItem": { "type": "object", "properties": { "flotilla_id": { "type": "string", "minLength": 1 }, "location": { "$ref": "#/definitions/controllers.LocationCoordinates" }, "name": { "type": "string", "minLength": 1 }, "pairing_key": { "type": "string", "minLength": 1 }, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.Tag" } } } }, "controllers.BulkClaimHostPartialData": { "type": "object", "properties": { "failure_count": { "type": "integer", "example": 1 }, "results": { "type": "array", "items": { "$ref": "#/definitions/controllers.BulkClaimHostResult" } }, "success_count": { "type": "integer", "example": 2 }, "total_requested": { "type": "integer", "example": 3 } } }, "controllers.BulkClaimHostPartialResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 207 }, "data": { "$ref": "#/definitions/controllers.BulkClaimHostPartialData" }, "msg": { "type": "string", "example": "Claimed 2 of 3 devices" } } }, "controllers.BulkClaimHostRequest": { "type": "object", "properties": { "devices": { "type": "array", "items": { "$ref": "#/definitions/controllers.BulkClaimHostItem" } } } }, "controllers.BulkClaimHostResult": { "type": "object", "properties": { "error": { "type": "string", "example": "Device already claimed by another organisation" }, "host_id": { "type": "string", "example": "8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c" }, "index": { "type": "integer", "example": 0 }, "name": { "type": "string", "example": "edge-gateway-01" }, "pairing_key": { "type": "string", "example": "ABCDE" }, "status": { "type": "string", "example": "claimed" }, "success": { "type": "boolean", "example": true } } }, "controllers.BulkClaimHostSuccessResultExample": { "type": "object", "properties": { "host_id": { "type": "string", "example": "8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c" }, "index": { "type": "integer", "example": 0 }, "name": { "type": "string", "example": "edge-gateway-01" }, "pairing_key": { "type": "string", "example": "ABCDE" }, "status": { "type": "string", "example": "claimed" }, "success": { "type": "boolean", "example": true } } }, "controllers.BulkDeleteHostsRequest": { "type": "object", "properties": { "decommission_action": { "type": "string", "example": "unpair" }, "device_ids": { "type": "array", "items": { "type": "string" } } } }, "controllers.BulkDeleteHostsResponse": { "type": "object", "properties": { "deleted_count": { "type": "integer", "example": 8 }, "requested_count": { "type": "integer", "example": 10 }, "results": { "type": "object", "additionalProperties": { "$ref": "#/definitions/hostservice.DeletedResult" } }, "skipped_count": { "type": "integer", "example": 2 } } }, "controllers.CANBus": { "type": "object", "properties": { "bitrate": { "type": "integer", "example": 500000 }, "driver": { "type": "string", "example": "mttcan" }, "fd": { "type": "boolean", "example": true }, "name": { "type": "string", "example": "can0" }, "nodes": { "type": "array", "items": { "$ref": "#/definitions/controllers.MCUNode" } }, "state": { "description": "State is ERROR-ACTIVE, ERROR-WARNING, ERROR-PASSIVE, BUS-OFF, STOPPED or empty.", "type": "string", "example": "ERROR-ACTIVE" }, "up": { "type": "boolean", "example": true } } }, "controllers.CICDSettings": { "type": "object", "properties": { "repository": { "$ref": "#/definitions/controllers.RepositorySettings" } } }, "controllers.CPU": { "type": "object", "properties": { "cores": { "type": "integer", "example": 32 }, "family": { "type": "string", "example": "6" }, "microcode": { "type": "string", "example": "0xd000389" }, "model": { "type": "string", "example": "Intel(R) Xeon(R) Gold 6338" }, "threads": { "type": "integer", "example": 64 }, "vendor": { "type": "string", "example": "GenuineIntel" } } }, "controllers.CPUStats": { "type": "object", "properties": { "context_switches": { "type": "integer", "example": 123456 }, "core_count": { "type": "integer", "example": 8 }, "interrupts": { "type": "integer", "example": 98765 }, "load_average_1": { "type": "number", "example": 2.15 }, "load_average_15": { "type": "number", "example": 2.56 }, "load_average_5": { "type": "number", "example": 2.34 }, "per_core_usage": { "type": "array", "items": { "type": "number" }, "example": [ 42.3, 48.1, 43.5, 46.2, 44.8, 47.3, 45.1, 43.9 ] }, "usage_percent": { "type": "number", "example": 45.5 } } }, "controllers.Cache": { "type": "object", "properties": { "level": { "type": "integer", "example": 3 }, "size": { "type": "integer", "example": 8192 }, "type": { "type": "string", "example": "Unified" } } }, "controllers.CalculateImpactRequest": { "type": "object", "properties": { "fleet_ids": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "minLength": 1, "enum": [ "config", "reboot", "restart_workload", "system_update" ], "example": "config" } } }, "controllers.ChangeDeviceFleetRequest": { "type": "object", "properties": { "flotilla_id": { "description": "FlotillaID is the target fleet UUID the device should be moved into.", "type": "string", "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, "wipe": { "description": "Wipe, when true, triggers a payload data wipe on the device as part of\nthe fleet change. The new fleet may have different owners, so wiping\nprevents data leaking across ownership boundaries. Requires device admin.", "type": "boolean", "example": false }, "wipe_options": { "description": "WipeOptions controls what is destroyed when `wipe` is true. Ignored when\n`wipe` is false. At least one of images/volumes must be set when wiping.", "allOf": [ { "$ref": "#/definitions/controllers.WipeOptions" } ] } } }, "controllers.ChangeDeviceFleetResponse": { "type": "object", "properties": { "flotilla_id": { "type": "string", "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "edge-device-01" }, "updated_at": { "type": "string", "example": "2024-09-12T14:30:00Z" }, "wiped": { "type": "boolean", "example": false } } }, "controllers.Chassis": { "type": "object", "properties": { "assetTag": { "type": "string", "example": "" }, "model": { "type": "string", "example": "" }, "serialNumber": { "type": "string", "example": "7X9KQ3" }, "type": { "type": "string", "example": "23" }, "typeDescription": { "type": "string", "example": "Rack Mount Chassis" }, "vendor": { "type": "string", "example": "Dell Inc." }, "version": { "type": "string", "example": "" } } }, "controllers.ClaimHostRequest": { "type": "object", "properties": { "flotilla_id": { "type": "string", "minLength": 1, "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, "location": { "$ref": "#/definitions/controllers.LocationCoordinates" }, "name": { "type": "string", "minLength": 1, "example": "edge-device-01" }, "pairing_key": { "type": "string", "minLength": 1, "example": "PK-ABCDEF123456" }, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.Tag" } } } }, "controllers.ClaimHostResponse": { "type": "object", "properties": { "host_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "edge-device-01" }, "status": { "type": "string", "enum": [ "claimed", "provisioning", "online", "offline" ], "example": "claimed" }, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.Tag" } } } }, "controllers.ClearHostConfigurationResponse": { "type": "object", "properties": { "has_override": { "type": "boolean", "example": false }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "updated_at": { "type": "string", "example": "2024-09-12T14:30:00Z" } } }, "controllers.ClientNetworkConfigRequest": { "type": "object", "required": [ "ssid" ], "properties": { "hidden": { "type": "boolean" }, "interface_mac": { "type": "string" }, "ip": { "$ref": "#/definitions/controllers.IPSettingsRequest" }, "priority": { "type": "integer" }, "psk": { "type": "string" }, "ssid": { "type": "string", "minLength": 1 } } }, "controllers.ConfigSpecRequest": { "type": "object", "properties": { "config_id": { "type": "string" }, "config_version": { "type": "integer" } } }, "controllers.ConfigurationWithLatestVersionResponse": { "type": "object", "properties": { "configuration": { "$ref": "#/definitions/configuration.Configuration" }, "latest_spec": { "$ref": "#/definitions/configuration.ConfigurationSpec" }, "version_info": { "$ref": "#/definitions/configuration.ConfigurationVersion" } } }, "controllers.ConflictResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "A resource with this identifier already exists" }, "success": { "type": "boolean", "example": false } } }, "controllers.ContainerStats": { "type": "object", "properties": { "block_read_bytes": { "type": "integer", "example": 268435456 }, "block_write_bytes": { "type": "integer", "example": 134217728 }, "container_id": { "type": "string", "example": "abc123def456" }, "container_name": { "type": "string", "example": "nginx-prod" }, "cpu_percent": { "type": "number", "example": 15.5 }, "image": { "type": "string", "example": "nginx:latest" }, "memory_limit_bytes": { "type": "integer", "example": 2147483648 }, "memory_percent": { "type": "number", "example": 25 }, "memory_used_bytes": { "type": "integer", "example": 536870912 }, "network_rx_bytes": { "type": "integer", "example": 1073741824 }, "network_tx_bytes": { "type": "integer", "example": 536870912 }, "pids": { "type": "integer", "example": 5 }, "status": { "type": "string", "enum": [ "running", "paused", "exited", "restarting", "dead" ], "example": "running" } } }, "controllers.CreateConfigurationRequest": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string", "minLength": 1, "example": "edge-nginx" }, "spec": { "$ref": "#/definitions/configuration.ConfigurationSpec" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "controllers.CreateCredentialRequest": { "type": "object", "required": [ "name", "registry" ], "properties": { "auth": { "type": "string" }, "aws_access_key_id": { "type": "string" }, "aws_region": { "type": "string" }, "aws_secret_access_key": { "type": "string" }, "aws_session_token": { "type": "string" }, "description": { "type": "string" }, "identity_token": { "type": "string" }, "name": { "type": "string" }, "password": { "type": "string" }, "registry": { "type": "string" }, "registry_token": { "type": "string" }, "type": { "type": "string" }, "username": { "type": "string" } } }, "controllers.CreateDeviceImageRequest": { "type": "object", "properties": { "image_name": { "type": "string", "minLength": 1, "example": "docker.io/library/nginx:latest" } } }, "controllers.CreateFleetRequest": { "type": "object", "required": [ "name" ], "properties": { "configuration_id": { "type": "string", "format": "uuid", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, "description": { "type": "string", "example": "Primary production fleet for region AU-SE" }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "example": [ "550e8400-e29b-41d4-a716-446655440000" ] }, "location": { "type": "string", "example": "Sydney, AU" }, "name": { "type": "string", "minLength": 1, "example": "production-fleet" }, "signaturePolicy": { "description": "SignaturePolicy is the fleet's image-signature policy override. See\nSignaturePolicy docs: Required is OR-ed with the org and configuration\nlevels; trust roots come from the most specific level that has any.", "allOf": [ { "$ref": "#/definitions/container.SignaturePolicy" } ] }, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.FleetTag" } }, "update_window": { "$ref": "#/definitions/controllers.UpdateWindowRequest" } } }, "controllers.CreateProvisioningProfileRequest": { "type": "object", "properties": { "expires_at": { "type": "string" }, "name": { "type": "string" }, "preload_workload": { "type": "boolean" }, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.ProfileTag" } }, "target_fleet_id": { "type": "string" } } }, "controllers.CreateRolloutRequest": { "type": "object", "properties": { "batch_size": { "type": "integer", "minimum": 0, "example": 10 }, "config_spec": { "$ref": "#/definitions/controllers.ConfigSpecRequest" }, "description": { "type": "string" }, "fleet_ids": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "minLength": 1, "example": "prod-config-rollout" }, "reboot_spec": { "$ref": "#/definitions/controllers.RebootSpecRequest" }, "restart_workload_spec": { "$ref": "#/definitions/controllers.RestartWorkloadRequest" }, "scheduled_at": { "type": "string" }, "strategy": { "description": "Strategy replaces batch_size (batch_size alone still maps to\nstrategy.maxInFlight). Omitted fields take the defaults: canary 1,\nmaxInFlight 50 (or batch_size), maxUnavailable 2,\nfailureThreshold 0.1, progressDeadline 30m.", "allOf": [ { "$ref": "#/definitions/controllers.StrategyRequest" } ] }, "system_update_spec": { "$ref": "#/definitions/controllers.SystemUpdateSpecRequest" }, "type": { "type": "string", "minLength": 1, "enum": [ "config", "reboot", "restart_workload", "system_update" ], "example": "config" } } }, "controllers.CreateTicketRequest": { "type": "object", "properties": { "attachDiagnostics": { "description": "AttachDiagnostics requests a diagnostics bundle (device subjects only).", "type": "boolean" }, "description": { "type": "string" }, "priority": { "type": "integer" }, "subject": { "description": "Subject optionally ties the ticket to a fleet, configuration or device.", "allOf": [ { "$ref": "#/definitions/controllers.TicketSubjectRequest" } ] }, "supportType": { "type": "string" }, "title": { "type": "string" } } }, "controllers.CreateTicketResponse": { "type": "object", "properties": { "createdAt": { "type": "string" }, "diagnostics": { "$ref": "#/definitions/helpdesk.Diagnostics" }, "diagnosticsBundleId": { "description": "DiagnosticsBundleID is the diagnostics bundle requested with the ticket.", "type": "string" }, "id": { "type": "string" }, "orgId": { "type": "string" }, "orgName": { "type": "string" }, "previewText": { "type": "string" }, "priority": { "$ref": "#/definitions/helpdesk.Priority" }, "raisedByEmail": { "type": "string" }, "raisedByName": { "type": "string" }, "raisedByUserId": { "type": "string" }, "ref": { "type": "string" }, "slackChannel": { "description": "Slack coordinates for the ticket's root thread message.", "type": "string" }, "slackThreadTs": { "type": "string" }, "status": { "$ref": "#/definitions/helpdesk.Status" }, "statusChangedAt": { "type": "string" }, "subject": { "description": "Subject is the fleet, configuration or device the ticket is about.", "allOf": [ { "$ref": "#/definitions/helpdesk.Subject" } ] }, "supportType": { "$ref": "#/definitions/helpdesk.SupportType" }, "title": { "type": "string" }, "updatedAt": { "type": "string" } } }, "controllers.CreateVolumeRequest": { "type": "object", "properties": { "name": { "type": "string", "example": "data-vol" }, "path": { "type": "string", "example": "/var/lib/admiral/volumes/data-vol" }, "quotaBytes": { "type": "integer", "example": 10737418240 } } }, "controllers.CustomMetricsResponse": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true } } }, "controllers.DeleteDeviceImageRequest": { "type": "object", "properties": { "force": { "type": "boolean", "example": false }, "image": { "type": "string", "example": "nginx:latest" } } }, "controllers.DeleteFleetTagsRequest": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "string" }, "example": [ "environment", "region" ] } } }, "controllers.DeleteHostResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "message": { "type": "string", "example": "Device has been unpaired and removed from the system" } } }, "controllers.DeleteVolumeRequest": { "type": "object", "properties": { "name": { "type": "string", "example": "data-vol" }, "path": { "type": "string", "example": "/var/lib/admiral/volumes/data-vol" }, "secureDelete": { "type": "boolean", "example": false } } }, "controllers.DeviceControlRequest": { "type": "object", "properties": { "force": { "type": "boolean", "example": false } } }, "controllers.DeviceHealthSummary": { "type": "object", "properties": { "health_score": { "type": "number", "example": 95.5 }, "issues": { "type": "array", "items": { "type": "string" }, "example": [ "Disk /var at 95% capacity" ] }, "last_metric_time": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "overall_status": { "type": "string", "enum": [ "healthy", "warning", "critical" ], "example": "healthy" }, "warnings": { "type": "array", "items": { "type": "string" }, "example": [ "High memory usage" ] } } }, "controllers.DeviceImageOperationResponse": { "type": "object", "properties": { "host_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "message": { "type": "string", "example": "Image pull request sent for nginx:latest" }, "operation": { "type": "string", "enum": [ "create_image", "delete_image" ], "example": "create_image" }, "status": { "type": "string", "enum": [ "sent" ], "example": "sent" }, "timestamp": { "type": "string", "example": "2024-01-15T10:30:00Z" } } }, "controllers.DeviceInfo": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "lastSeen": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "name": { "type": "string", "example": "prod-server-01" }, "status": { "type": "string", "enum": [ "online", "offline", "claimed", "pending", "error" ], "example": "online" } } }, "controllers.DeviceOperationResponse": { "type": "object", "properties": { "device_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "force": { "type": "boolean", "example": false }, "operation": { "type": "string", "enum": [ "reboot", "shutdown" ], "example": "reboot" } } }, "controllers.DevicePermissions": { "type": "object", "properties": { "airdetect": { "type": "boolean" }, "assign": { "type": "boolean" }, "delete": { "type": "boolean" }, "device_policy": { "type": "boolean" }, "diagnose": { "type": "boolean" }, "edit": { "type": "boolean" }, "network": { "type": "boolean" }, "operate": { "type": "boolean" }, "recover": { "type": "boolean" }, "screen_control": { "type": "boolean" }, "screen_view": { "type": "boolean" }, "security": { "type": "boolean" }, "shell": { "type": "boolean" }, "telemetry": { "type": "boolean" }, "update_os": { "type": "boolean" }, "view": { "type": "boolean" }, "volumes": { "type": "boolean" }, "workload_exec": { "type": "boolean" } } }, "controllers.DeviceSecurityResponse": { "type": "object", "properties": { "compliance": { "type": "string" }, "encryption": { "$ref": "#/definitions/device.EncryptionState" }, "policy": { "$ref": "#/definitions/controllers.SecurityPolicyRequirements" }, "recovery_key_escrowed": { "type": "boolean" }, "recovery_key_staged_at": { "type": "string" }, "reported": { "description": "Reported is true when the agent sent Specification.Security. Old\nagents report false: \"not reported\", never \"absent\".", "type": "boolean" }, "secure_boot": { "$ref": "#/definitions/device.SecureBootState" }, "tpm": { "$ref": "#/definitions/device.TPMState" }, "violations": { "type": "array", "items": { "$ref": "#/definitions/security.Violation" } } } }, "controllers.DeviceSpecificationResponse": { "type": "object", "properties": { "accelerators": { "type": "array", "items": { "$ref": "#/definitions/controllers.Accelerator" } }, "baseboard": { "$ref": "#/definitions/controllers.Baseboard" }, "bios": { "$ref": "#/definitions/controllers.BIOS" }, "bootSlot": { "type": "string", "example": "a" }, "canBuses": { "description": "CANBuses lists SocketCAN interfaces; omitted when none reported.", "type": "array", "items": { "$ref": "#/definitions/controllers.CANBus" } }, "chassis": { "$ref": "#/definitions/controllers.Chassis" }, "collectedAt": { "description": "CollectedAt is when the backend received this specification from the\ndevice. Absent for stored specs that predate the timestamp.", "type": "string", "example": "2026-10-07T01:02:03Z" }, "cpus": { "type": "array", "items": { "$ref": "#/definitions/controllers.CPU" } }, "disks": { "type": "array", "items": { "$ref": "#/definitions/controllers.Disk" } }, "displays": { "type": "array", "items": { "$ref": "#/definitions/controllers.Display" } }, "gpus": { "type": "array", "items": { "$ref": "#/definitions/controllers.GPU" } }, "hostId": { "type": "string", "example": "dev_01HZX9K3M2" }, "memory": { "type": "array", "items": { "$ref": "#/definitions/controllers.Memory" } }, "network": { "type": "array", "items": { "$ref": "#/definitions/controllers.NetworkInterface" } }, "partitions": { "description": "boot disk layout; omitted when not reported", "type": "array", "items": { "$ref": "#/definitions/controllers.Partition" } }, "pci": { "type": "array", "items": { "$ref": "#/definitions/controllers.PCIDevice" } }, "product": { "$ref": "#/definitions/controllers.Product" }, "secureBoot": { "description": "Trust posture, passed through from the agent's report.", "allOf": [ { "$ref": "#/definitions/device.SecureBootState" } ] }, "security": { "$ref": "#/definitions/device.SecurityPosture" }, "source": { "description": "Source is \"live\" (just read from the device) or \"stored\" (last\nspecification the device reported to the backend).", "type": "string", "example": "live" }, "topology": { "$ref": "#/definitions/controllers.TopologyInfo" }, "versions": { "$ref": "#/definitions/controllers.SystemVersions" } } }, "controllers.DeviceStateResponse": { "type": "object", "properties": { "deviceId": { "type": "string" }, "presence": { "$ref": "#/definitions/devicestate.Presence" }, "protocol": { "type": "integer" }, "receivedAt": { "description": "ReceivedAt is when the backend stored the document (now for live).", "type": "string" }, "source": { "description": "Source is \"stored\" or \"live\".", "type": "string" }, "state": { "$ref": "#/definitions/state.DeviceState" }, "stateRev": { "type": "string" } } }, "controllers.DeviceStatsResponse": { "type": "object", "properties": { "battery": { "$ref": "#/definitions/controllers.BatteryStats" }, "container": { "$ref": "#/definitions/controllers.ContainerStats" }, "cpu": { "$ref": "#/definitions/controllers.CPUStats" }, "device_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "disk": { "$ref": "#/definitions/controllers.DiskStats" }, "fleet_id": { "type": "string", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, "gpu": { "$ref": "#/definitions/controllers.GPUStats" }, "health": { "$ref": "#/definitions/controllers.DeviceHealthSummary" }, "memory": { "$ref": "#/definitions/controllers.MemoryStats" }, "network": { "$ref": "#/definitions/controllers.NetworkStats" }, "processes": { "$ref": "#/definitions/controllers.ProcessStats" }, "timestamp": { "type": "string", "example": "2024-01-15T10:30:00Z" } } }, "controllers.DeviceUpdateOperationResponse": { "type": "object", "properties": { "device_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "image_id": { "type": "string", "example": "ubuntu-22.04-v1.2.3" }, "operation": { "type": "string", "enum": [ "update" ], "example": "update" }, "partition": { "type": "string", "enum": [ "A", "B" ], "example": "A" } } }, "controllers.DeviceUpdateRequest": { "type": "object", "properties": { "force": { "type": "boolean", "example": false }, "image_id": { "type": "string", "example": "ubuntu-22.04-v1.2.3" }, "partition": { "type": "string", "enum": [ "A", "B" ], "example": "A" } } }, "controllers.DiscardLocalOverrideRequest": { "type": "object", "properties": { "paths": { "description": "Paths to drop; [\"*\"] (the default) clears everything.", "type": "array", "items": { "type": "string" } } } }, "controllers.DiscardLocalOverrideResponse": { "type": "object", "properties": { "deviceId": { "type": "string" }, "paths": { "type": "array", "items": { "type": "string" } }, "sent": { "type": "boolean" } } }, "controllers.Disk": { "type": "object", "properties": { "bus": { "type": "string", "example": "nvme" }, "media": { "type": "string", "enum": [ "nvme", "emmc", "sd", "usb", "sata", "scsi", "virtio" ], "example": "nvme" }, "model": { "type": "string", "example": "Samsung SSD 970 EVO Plus 1TB" }, "name": { "description": "Additive: kernel block device name, media class and removable flag (empty on agents that predate them).", "type": "string", "example": "nvme0n1" }, "removable": { "type": "boolean", "example": false }, "serial_number": { "type": "string", "example": "S4EUNG0N123456" }, "size": { "type": "integer", "example": 1000204886016 } } }, "controllers.DiskStats": { "type": "object", "properties": { "partitions": { "type": "array", "items": { "$ref": "#/definitions/controllers.PartitionStats" } }, "total_usage_percent": { "type": "number", "example": 72.3 } } }, "controllers.Display": { "type": "object", "properties": { "disconnected": { "description": "Additive: connector present but nothing attached. Absent means connected.", "type": "boolean", "example": false }, "name": { "type": "string", "example": "DP-1" }, "refreshRate": { "type": "string", "example": "60Hz" }, "resolution": { "type": "string", "example": "3840x2160" } } }, "controllers.EdgeWireConnectionDevice": { "type": "object", "properties": { "deviceId": { "type": "string" }, "deviceName": { "type": "string" }, "fleetId": { "type": "string" }, "fleetName": { "type": "string" }, "maxSessions": { "type": "integer" }, "online": { "type": "boolean" }, "reportedAt": { "type": "string" }, "reporting": { "type": "boolean" }, "sessions": { "type": "array", "items": { "$ref": "#/definitions/controllers.EdgeWireConnectionSession" } } } }, "controllers.EdgeWireConnectionSession": { "type": "object", "properties": { "application": { "description": "Application is \"ssh\", \"exec\", \"debug\" or \"workload\".", "type": "string" }, "bytesRx": { "type": "integer" }, "bytesTx": { "description": "BytesTx/BytesRx are wire bytes summed over paths, local view.", "type": "integer" }, "flows": { "type": "integer" }, "kind": { "description": "Kind is \"rescue\" or \"customer\".", "type": "string" }, "localAddr": { "description": "Local/RemoteAddr are ip:port; the backend redacts them for non-admins.", "type": "string" }, "localCandidate": { "description": "Local/RemoteCandidate are ICE candidate types: host, srflx, prflx, relay.", "type": "string" }, "mine": { "type": "boolean" }, "openStreams": { "description": "OpenStreams and Flows are the current counts.", "type": "integer" }, "path": { "description": "Path is direct, relay_udp, relay_tls, nats or other.", "type": "string" }, "pathChangedAt": { "type": "string" }, "remoteAddr": { "type": "string" }, "remoteCandidate": { "type": "string" }, "rttMs": { "type": "number" }, "sessionId": { "type": "string" }, "startedAt": { "type": "string" }, "userEmail": { "type": "string" }, "userId": { "type": "string" } } }, "controllers.EdgeWireConnectionsResponse": { "type": "object", "properties": { "asOf": { "type": "string" }, "devices": { "type": "array", "items": { "$ref": "#/definitions/controllers.EdgeWireConnectionDevice" } }, "enabled": { "type": "boolean" }, "relay": { "type": "boolean" }, "truncated": { "type": "boolean" } } }, "controllers.EdgeWireTargetsBody": { "type": "object", "properties": { "targets": { "type": "array", "items": { "$ref": "#/definitions/host.EdgeWireTarget" } } } }, "controllers.EdgeWireTrustKey": { "type": "object", "properties": { "ed25519": { "type": "string" }, "kid": { "type": "string" }, "mldsa65": { "type": "string" }, "scope": { "type": "string" } } }, "controllers.EffectiveNetworkConfigurationResponse": { "type": "object", "properties": { "configuration": { "$ref": "#/definitions/github_com_qdynamicsco_admiral_src_domain_network.NetworkConfiguration" }, "source": { "type": "string", "enum": [ "device", "fleet" ], "example": "device" } } }, "controllers.EffectiveTag": { "type": "object", "properties": { "fleet_value": { "type": "string", "example": "staging" }, "key": { "type": "string", "example": "environment" }, "source": { "type": "string", "enum": [ "device", "fleet", "overridden" ], "example": "fleet" }, "value": { "type": "string", "example": "production" } } }, "controllers.EthernetConfigRequest": { "type": "object", "properties": { "ip": { "$ref": "#/definitions/controllers.IPSettingsRequest" } } }, "controllers.EventResponse": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "string" } }, "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "event": { "type": "string", "example": "device_online" }, "fleetId": { "type": "string", "example": "f1e2d3c4-b5a6-7890-1234-567890abcdef" }, "source": { "type": "string", "enum": [ "system", "agent", "user", "workload", "rollout" ], "example": "system" }, "timestamp": { "type": "string", "example": "2024-01-15T10:30:00Z" } } }, "controllers.EventsListResponse": { "type": "object", "properties": { "count": { "type": "integer", "example": 25 }, "events": { "type": "array", "items": { "$ref": "#/definitions/controllers.EventResponse" } }, "hasMore": { "type": "boolean", "example": true }, "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 }, "totalCount": { "type": "integer", "example": 156 } } }, "controllers.FailureBreakdownDTO": { "type": "object", "properties": { "image_pull_failed": { "type": "integer", "example": 1 }, "network_failed": { "type": "integer", "example": 0 }, "other_failed": { "type": "integer", "example": 0 }, "timeout_failed": { "type": "integer", "example": 0 }, "validation_failed": { "type": "integer", "example": 1 } } }, "controllers.FleetAccessPointConfigRequest": { "type": "object", "required": [ "ssid" ], "properties": { "channel": { "type": "integer" }, "hidden": { "type": "boolean" }, "ip": { "$ref": "#/definitions/controllers.FleetIPSettingsRequest" }, "psk": { "type": "string" }, "security": { "type": "string" }, "ssid": { "type": "string", "minLength": 1 } } }, "controllers.FleetBridgeConfigRequest": { "type": "object", "required": [ "member_macs", "name" ], "properties": { "ip": { "$ref": "#/definitions/controllers.FleetIPSettingsRequest" }, "member_macs": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "minLength": 1 } } }, "controllers.FleetClientNetworkConfigRequest": { "type": "object", "required": [ "ssid" ], "properties": { "hidden": { "type": "boolean" }, "interface_mac": { "type": "string" }, "ip": { "$ref": "#/definitions/controllers.FleetIPSettingsRequest" }, "priority": { "type": "integer" }, "psk": { "type": "string" }, "ssid": { "type": "string", "minLength": 1 } } }, "controllers.FleetConfigurationAssignedResponse": { "type": "object", "properties": { "config_version": { "type": "integer", "example": 2 }, "configuration_id": { "type": "string", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "updated_at": { "type": "string", "example": "2024-09-12T14:30:00Z" } } }, "controllers.FleetCreatedResponse": { "type": "object", "properties": { "config_version": { "type": "integer", "example": 1 }, "configuration_id": { "type": "string", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, "created_at": { "type": "string", "example": "2024-09-12T14:30:00Z" }, "description": { "type": "string", "example": "Primary production fleet for region AU-SE" }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "location": { "type": "string", "example": "Sydney, AU" }, "name": { "type": "string", "example": "production-fleet" }, "signaturePolicy": { "$ref": "#/definitions/container.SignaturePolicy" }, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.FleetTag" } }, "update_window": { "$ref": "#/definitions/controllers.UpdateWindowRequest" } } }, "controllers.FleetDeletedResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "message": { "type": "string", "example": "Fleet has been deleted" }, "unpair_devices": { "type": "boolean", "example": false } } }, "controllers.FleetDevicesListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/controllers.HostListResponse" } }, "message": { "type": "string", "example": "Success" }, "pagination": { "$ref": "#/definitions/controllers.PaginationInfo" }, "success": { "type": "boolean", "example": true } } }, "controllers.FleetEthernetConfigRequest": { "type": "object", "properties": { "ip": { "$ref": "#/definitions/controllers.FleetIPSettingsRequest" } } }, "controllers.FleetIPSettingsRequest": { "type": "object", "properties": { "proxy": { "$ref": "#/definitions/controllers.ProxyRequest" } } }, "controllers.FleetInfoShort": { "type": "object", "properties": { "id": { "type": "string", "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, "name": { "type": "string", "example": "production-fleet" } } }, "controllers.FleetInterfaceConfigRequest": { "type": "object", "required": [ "match_mac", "type" ], "properties": { "enabled": { "type": "boolean", "example": true }, "ethernet": { "$ref": "#/definitions/controllers.FleetEthernetConfigRequest" }, "match_mac": { "type": "string", "minLength": 1, "example": "aa:bb:cc:dd:ee:ff" }, "type": { "type": "string", "enum": [ "wifi", "ethernet", "bridge" ], "example": "wifi" }, "wifi": { "$ref": "#/definitions/controllers.FleetWifiDeviceRequest" } } }, "controllers.FleetListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/controllers.FleetResponse" } }, "message": { "type": "string", "example": "Success" }, "pagination": { "$ref": "#/definitions/controllers.PaginationInfo" }, "success": { "type": "boolean", "example": true } } }, "controllers.FleetResponse": { "type": "object", "properties": { "compliance": { "type": "string", "enum": [ "good", "warning", "poor", "unknown" ], "example": "good" }, "complianceScore": { "type": "integer", "example": 95 }, "config_version": { "type": "integer", "example": 3 }, "configuration_id": { "type": "string", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, "createdAt": { "type": "string", "example": "2024-01-15T10:00:00Z" }, "custom_metrics_enabled": { "type": "boolean" }, "description": { "type": "string", "example": "Primary production fleet for region AU-SE" }, "deviceList": { "type": "array", "items": { "$ref": "#/definitions/controllers.DeviceInfo" } }, "devices": { "type": "integer", "example": 42 }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "lastUpdate": { "type": "string", "example": "2024-09-12T14:30:00Z" }, "location": { "type": "string", "example": "Sydney, AU" }, "name": { "type": "string", "example": "production-fleet" }, "offline": { "type": "integer", "example": 2 }, "online": { "type": "integer", "example": 40 }, "signaturePolicy": { "$ref": "#/definitions/container.SignaturePolicy" }, "sshEnabled": { "type": "boolean", "example": true }, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.FleetTag" } }, "update_window": { "$ref": "#/definitions/controllers.UpdateWindowRequest" } } }, "controllers.FleetSSHResponse": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true } } }, "controllers.FleetTag": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "maxLength": 63, "minLength": 1, "example": "environment" }, "value": { "type": "string", "maxLength": 255, "example": "production" } } }, "controllers.FleetTagKeysResponse": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/definitions/controllers.TagKeyEntry" } }, "total_devices": { "type": "integer", "example": 42 } } }, "controllers.FleetTagsRequest": { "type": "object", "required": [ "tags" ], "properties": { "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.FleetTag" } } } }, "controllers.FleetTagsResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.FleetTag" } } } }, "controllers.FleetUpdateAllowedResponse": { "type": "object", "properties": { "checked_at": { "type": "string", "example": "2024-09-12T14:30:00Z" }, "fleet_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "updates_allowed": { "type": "boolean", "example": true } } }, "controllers.FleetUpdateWindowUpdatedResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "update_window": { "$ref": "#/definitions/controllers.UpdateWindowRequest" }, "updated_at": { "type": "string", "example": "2024-09-12T14:30:00Z" } } }, "controllers.FleetUpdatedResponse": { "type": "object", "properties": { "description": { "type": "string", "example": "Primary production fleet for region AU-SE" }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "location": { "type": "string", "example": "Sydney, AU" }, "name": { "type": "string", "example": "production-fleet" }, "signaturePolicy": { "$ref": "#/definitions/container.SignaturePolicy" }, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.FleetTag" } }, "update_window": { "$ref": "#/definitions/controllers.UpdateWindowRequest" }, "updated_at": { "type": "string", "example": "2024-09-12T14:30:00Z" } } }, "controllers.FleetUserResponse": { "type": "object", "properties": { "email": { "type": "string", "example": "jane@example.com" }, "first_name": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "role": { "type": "string", "enum": [ "admin", "editor", "viewer" ], "example": "editor" }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "editor", "viewer" ] }, "user_id": { "type": "string", "example": "oafrHUx6ZbftN340XV4JiA982Mo1" } } }, "controllers.FleetWifiDeviceRequest": { "type": "object", "required": [ "mode" ], "properties": { "access_point": { "$ref": "#/definitions/controllers.FleetAccessPointConfigRequest" }, "country_code": { "type": "string" }, "mode": { "type": "string", "example": "client" }, "powersave": { "type": "boolean" } } }, "controllers.ForbiddenResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 403 }, "msg": { "type": "string", "example": "Access denied" } } }, "controllers.GPU": { "type": "object", "properties": { "cudaVersion": { "type": "string", "example": "13.4" }, "driver": { "type": "string", "example": "nvgpu" }, "driverVersion": { "description": "DriverVersion and CUDAVersion are reported for discrete NVIDIA GPUs.", "type": "string", "example": "615.78.08" }, "integrated": { "description": "Integrated is true for SoC-integrated GPUs (not enumerated on PCI).", "type": "boolean", "example": true }, "model": { "type": "string", "example": "GeForce RTX 3090" }, "node": { "type": "string", "example": "/sys/devices/platform/17000000.gpu" }, "pci_device": { "$ref": "#/definitions/controllers.PCIDevice" }, "vendor": { "type": "string", "example": "NVIDIA" } } }, "controllers.GPUStat": { "type": "object", "properties": { "index": { "type": "integer", "example": 0 }, "memory_total_bytes": { "type": "integer", "example": 8589934592 }, "memory_used_bytes": { "type": "integer", "example": 1048576 }, "power_limit_watts": { "type": "number", "example": 215 }, "power_watts": { "type": "number", "example": 42 }, "temperature_celsius": { "type": "number", "example": 41.5 }, "utilization_percent": { "type": "number", "example": 7 } } }, "controllers.GPUStats": { "type": "object", "properties": { "gpus": { "type": "array", "items": { "$ref": "#/definitions/controllers.GPUStat" } } } }, "controllers.GatewayTimeoutResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 504 }, "msg": { "type": "string", "example": "Upstream request timed out" } } }, "controllers.GetNetworkStatusResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "" }, "host_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "interfaces": { "type": "array", "items": { "$ref": "#/definitions/controllers.InterfaceStatusResponse" } }, "reported_at": { "type": "string", "example": "2024-09-12T14:30:00Z" } } }, "controllers.HostDetailResponse": { "type": "object", "properties": { "assignedAt": { "type": "string", "example": "2024-01-20T08:15:00Z" }, "config_version": { "type": "integer", "example": 7 }, "configuration_id": { "type": "string", "example": "cfg-3f7a2b1e" }, "createdAt": { "type": "string", "example": "2024-01-15T10:00:00Z" }, "effective_tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.EffectiveTag" } }, "fleet": { "$ref": "#/definitions/controllers.FleetInfoShort" }, "fleet_tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.Tag" } }, "hardwareType": { "type": "string", "example": "NVIDIA Jetson Orin Nano" }, "has_override": { "type": "boolean", "example": false }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "imageID": { "type": "string", "example": "ubuntu-22.04-v1.2.3" }, "lastMaintenanceDate": { "type": "string", "example": "2024-09-12T14:30:00Z" }, "location": { "$ref": "#/definitions/controllers.LocationInfo" }, "name": { "type": "string", "example": "edge-device-01" }, "networkInterfaces": {}, "notes": { "type": "string", "example": "Rack 3, shelf 2" }, "onlineStatus": { "$ref": "#/definitions/controllers.OnlineStatusInfo" }, "permissions": { "description": "Permissions are the caller's remote-access rights on this device.\nThe dashboard gates the Terminal view on permissions.workload_exec and\nthe Debug toggle on permissions.shell.", "allOf": [ { "$ref": "#/definitions/controllers.DevicePermissions" } ] }, "remote_unlock_waiting_until": { "description": "RemoteUnlockWaitingUntil is set while the device sits at its recovery\nscreen polling for a grant. The dashboard raises the unlock alert while\nit is in the future. Omitted when no device is waiting.", "type": "string" }, "screenshots_disabled": { "description": "ScreenshotsDisabled is true when on-demand screenshots are turned off\nfor the device. Always present.", "type": "boolean", "example": false }, "security": { "description": "Security is the TPM / secure boot / disk encryption posture and its\ncompliance with the fleet's security policy (device_security.go).", "allOf": [ { "$ref": "#/definitions/controllers.DeviceSecurityResponse" } ] }, "status": { "type": "string", "enum": [ "online", "offline", "provisioning", "error", "unknown" ], "example": "online" }, "systemSpec": {}, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.Tag" } }, "updatedAt": { "type": "string", "example": "2024-09-12T14:30:00Z" } } }, "controllers.HostListResponse": { "type": "object", "properties": { "compliance": { "description": "Compliance is the worst of presence compliance and the fleet security\npolicy compliance; ComplianceReason names the cause.", "type": "string" }, "compliance_reason": { "type": "string" }, "fleet": { "$ref": "#/definitions/controllers.FleetInfoShort" }, "hardwareType": { "type": "string", "example": "NVIDIA Jetson Orin Nano" }, "has_override": { "type": "boolean", "example": false }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "ipAddress": { "type": "string", "example": "10.1.1.100" }, "isOnline": { "$ref": "#/definitions/controllers.OnlineStatusInfo" }, "location": { "$ref": "#/definitions/controllers.LocationInfo" }, "name": { "type": "string", "example": "edge-device-01" }, "operations": { "description": "Operations are the in-flight operations (image pulls, OTA, slot writes)\nof an online device. Omitted when there are none.", "type": "array", "items": { "$ref": "#/definitions/state.Operation" } }, "status": { "type": "string", "enum": [ "online", "offline", "provisioning", "claimed", "pending", "error", "unknown" ], "example": "online" } } }, "controllers.IPConfigRequest": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "minLength": 1 }, "dns": { "type": "array", "items": { "type": "string" } }, "gateway": { "type": "string" } } }, "controllers.IPSettingsRequest": { "type": "object", "properties": { "dhcp_v4": { "type": "boolean", "example": true }, "ipv4": { "$ref": "#/definitions/controllers.IPConfigRequest" }, "ipv6": { "$ref": "#/definitions/controllers.IPConfigRequest" }, "proxy": { "$ref": "#/definitions/controllers.ProxyRequest" } } }, "controllers.ImageProxyStatusResponse": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true }, "enabled_at": { "type": "string", "example": "2026-10-02T14:30:00Z" }, "fleet_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } }, "controllers.ImageProxyUsageResponse": { "type": "object", "properties": { "daily": { "type": "array", "items": { "$ref": "#/definitions/imageproxyusagerepo.DayUsage" } }, "devices": { "type": "array", "items": { "$ref": "#/definitions/imageproxyusagerepo.DeviceUsage" } }, "fleet_id": { "type": "string" }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "totals": { "$ref": "#/definitions/imageproxyusagerepo.Totals" } } }, "controllers.ImageResponse": { "type": "object", "properties": { "created": { "type": "string", "example": "2024-01-15T10:00:00Z" }, "id": { "type": "string", "example": "sha256:abc123..." }, "pinned": { "type": "boolean", "example": false }, "size": { "type": "integer", "example": 142893456 }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "nginx:latest", "nginx:1.21" ] } } }, "controllers.InterfaceConfigRequest": { "type": "object", "required": [ "match_mac", "type" ], "properties": { "enabled": { "type": "boolean", "example": true }, "ethernet": { "$ref": "#/definitions/controllers.EthernetConfigRequest" }, "match_mac": { "type": "string", "minLength": 1, "example": "aa:bb:cc:dd:ee:ff" }, "type": { "type": "string", "enum": [ "wifi", "ethernet", "bridge" ], "example": "wifi" }, "wifi": { "$ref": "#/definitions/controllers.WifiDeviceRequest" } } }, "controllers.InterfaceStats": { "type": "object", "properties": { "ip_address": { "type": "string", "example": "192.168.1.100" }, "is_up": { "type": "boolean", "example": true }, "mac_address": { "type": "string", "example": "aa:bb:cc:dd:ee:ff" }, "mtu": { "type": "integer", "example": 1500 }, "name": { "type": "string", "example": "eth0" }, "rx_bytes": { "type": "integer", "example": 10737418240 }, "rx_dropped": { "type": "integer", "example": 0 }, "rx_errors": { "type": "integer", "example": 0 }, "rx_packets": { "type": "integer", "example": 8388608 }, "speed_mbps": { "type": "integer", "example": 1000 }, "tx_bytes": { "type": "integer", "example": 5368709120 }, "tx_dropped": { "type": "integer", "example": 0 }, "tx_errors": { "type": "integer", "example": 0 }, "tx_packets": { "type": "integer", "example": 4194304 }, "updated_at": { "type": "string", "example": "2024-01-15T10:30:00Z" } } }, "controllers.InterfaceStatusResponse": { "type": "object", "properties": { "ap_state": { "$ref": "#/definitions/controllers.WifiStatusResponse" }, "client_state": { "$ref": "#/definitions/controllers.WifiStatusResponse" }, "ips": { "type": "array", "items": { "$ref": "#/definitions/controllers.AddressStatusResponse" } }, "mac": { "type": "string", "example": "aa:bb:cc:dd:ee:ff" }, "name": { "type": "string", "example": "wlan0" }, "state": { "type": "string", "enum": [ "up", "down", "unknown" ], "example": "up" }, "type": { "type": "string", "enum": [ "wifi", "ethernet", "bridge", "loopback" ], "example": "wifi" } } }, "controllers.InternalServerErrorResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 500 }, "msg": { "type": "string", "example": "Internal server error" } } }, "controllers.ListConfigurationsEnvelope": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/definitions/configservice.ConfigurationSummary" } }, "msg": { "type": "string", "example": "Success" }, "pagination": { "$ref": "#/definitions/controllers.PaginationInfo" } } }, "controllers.ListCredentialsEnvelope": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/definitions/registrycredential.RegistryCredential" } }, "msg": { "type": "string", "example": "Success" }, "pagination": { "$ref": "#/definitions/controllers.PaginationInfo" } } }, "controllers.ListDeviceImagesResponse": { "type": "object", "properties": { "host_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "images": { "type": "array", "items": { "$ref": "#/definitions/controllers.ImageResponse" } } } }, "controllers.ListHostsCountsInfo": { "type": "object", "properties": { "offline": { "type": "integer", "example": 12 }, "online": { "type": "integer", "example": 30 }, "total": { "type": "integer", "example": 42 } } }, "controllers.ListHostsEnvelope": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "counts": { "$ref": "#/definitions/controllers.ListHostsCountsInfo" }, "data": { "type": "array", "items": { "$ref": "#/definitions/controllers.HostListResponse" } }, "msg": { "type": "string", "example": "Success" }, "pagination": { "$ref": "#/definitions/controllers.PaginationInfo" } } }, "controllers.LocationCoordinates": { "type": "object", "properties": { "latitude": { "type": "number", "example": 51.5074 }, "longitude": { "type": "number", "example": -0.1278 } } }, "controllers.LocationInfo": { "type": "object", "properties": { "latitude": { "type": "number", "example": 51.5074 }, "longitude": { "type": "number", "example": -0.1278 } } }, "controllers.MCUNode": { "type": "object", "properties": { "bootloaderVersion": { "type": "string", "example": "1.0.2" }, "chip": { "type": "string", "example": "STM32G474" }, "firmwareImage": { "type": "string", "example": "motor-fw-2.3.0.bin" }, "firmwareVersion": { "type": "string", "example": "2.3.0" }, "name": { "type": "string", "example": "motor-controller" }, "nodeId": { "type": "integer", "example": 17 }, "state": { "type": "string", "enum": [ "app", "bootloader", "updating", "unresponsive" ], "example": "app" } } }, "controllers.Memory": { "type": "object", "properties": { "model": { "type": "string", "example": "M393A4K40DB3-CWE" }, "serialNumber": { "type": "string", "example": "4231AB12" }, "sizeBytes": { "type": "integer", "example": 34359738368 }, "speedMTs": { "type": "integer", "example": 3200 }, "type": { "type": "string", "example": "DDR4" } } }, "controllers.MemoryStats": { "type": "object", "properties": { "available_bytes": { "type": "integer", "example": 6442450944 }, "buffered_bytes": { "type": "integer", "example": 536870912 }, "cached_bytes": { "type": "integer", "example": 1073741824 }, "free_bytes": { "type": "integer", "example": 5411459072 }, "swap_free": { "type": "integer", "example": 3758096384 }, "swap_total": { "type": "integer", "example": 4294967296 }, "swap_used": { "type": "integer", "example": 536870912 }, "total_bytes": { "type": "integer", "example": 17179869184 }, "usage_percent": { "type": "number", "example": 68.5 }, "used_bytes": { "type": "integer", "example": 11768410112 } } }, "controllers.MemoryTestCancelRequest": { "type": "object", "properties": { "runId": { "type": "string" } } }, "controllers.MemoryTestErrorBody": { "type": "object", "properties": { "device_id": { "type": "string" }, "error": { "type": "string", "example": "operator_required" }, "message": { "type": "string" }, "status": { "$ref": "#/definitions/memtest.Status" } } }, "controllers.MemoryTestResultResponse": { "type": "object", "properties": { "deviceId": { "type": "string" }, "result": { "$ref": "#/definitions/memtest.Result" } } }, "controllers.MemoryTestResultsResponse": { "type": "object", "properties": { "deviceId": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/definitions/memtest.Result" } } } }, "controllers.MemoryTestRunResponse": { "type": "object", "properties": { "deviceId": { "type": "string" }, "runId": { "type": "string" }, "status": { "$ref": "#/definitions/memtest.Status" } } }, "controllers.MemoryTestStartRequest": { "type": "object", "properties": { "bitFade": { "type": "boolean" }, "holdOnFailure": { "type": "boolean" }, "impact": { "enum": [ "running", "stopped" ], "allOf": [ { "$ref": "#/definitions/memtest.Impact" } ], "example": "running" }, "kernelPasses": { "type": "integer", "example": 4 }, "maxBytes": { "type": "integer" }, "passes": { "type": "integer", "example": 1 }, "placement": { "enum": [ "online", "offline" ], "allOf": [ { "$ref": "#/definitions/memtest.Placement" } ], "example": "online" }, "quick": { "type": "boolean" }, "timeBudgetSeconds": { "type": "integer", "example": 7200 } } }, "controllers.MemoryTestStatusResponse": { "type": "object", "properties": { "deviceId": { "type": "string" }, "health": { "$ref": "#/definitions/memtest.Health" }, "healthReportedAt": { "description": "HealthReportedAt is when a stored health snapshot was taken (stored only).", "type": "string" }, "history": { "type": "array", "items": { "$ref": "#/definitions/memtest.Result" } }, "source": { "description": "Source is live (the device answered now) or stored (offline, no\nresponder or the device did not answer).", "type": "string", "enum": [ "live", "stored" ] }, "status": { "$ref": "#/definitions/memtest.Status" }, "supported": { "description": "Supported is false when the device is online but its firmware has no\nmemory test.", "type": "boolean" } } }, "controllers.NUMANode": { "type": "object", "properties": { "id": { "type": "integer", "example": 0 }, "memory": { "type": "integer", "example": 17179869184 }, "processors": { "type": "array", "items": { "type": "integer" }, "example": [ 0, 1, 2, 3 ] } } }, "controllers.NetworkInterface": { "type": "object", "properties": { "ipV4Address": { "type": "string", "example": "192.168.1.42" }, "ipV6Address": { "type": "string", "example": "fe80::b27b:25ff:fe11:2233" }, "macAddress": { "type": "string", "example": "b0:7b:25:11:22:33" }, "name": { "type": "string", "example": "eno1" } } }, "controllers.NetworkStats": { "type": "object", "properties": { "interfaces": { "type": "array", "items": { "$ref": "#/definitions/controllers.InterfaceStats" } }, "total_rx_bytes": { "type": "integer", "example": 10737418240 }, "total_rx_dropped": { "type": "integer", "example": 0 }, "total_rx_errors": { "type": "integer", "example": 0 }, "total_rx_packets": { "type": "integer", "example": 8388608 }, "total_tx_bytes": { "type": "integer", "example": 5368709120 }, "total_tx_dropped": { "type": "integer", "example": 0 }, "total_tx_errors": { "type": "integer", "example": 0 }, "total_tx_packets": { "type": "integer", "example": 4194304 } } }, "controllers.NotFoundResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 404 }, "msg": { "type": "string", "example": "Resource not found" } } }, "controllers.NotificationSettings": { "type": "object", "properties": { "emailAlerts": { "type": "boolean", "example": true }, "smsAlerts": { "type": "boolean", "example": false } } }, "controllers.OAuthErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_client" }, "error_description": { "type": "string", "example": "invalid client credentials" } } }, "controllers.OnlineStatusInfo": { "type": "object", "properties": { "isOnline": { "type": "boolean", "example": true }, "lastSeen": { "type": "string", "example": "2024-09-12T14:30:00Z" }, "latencyMs": { "type": "number", "example": 23.4 } } }, "controllers.OrgSignaturePolicyRequest": { "type": "object", "properties": { "signaturePolicy": { "$ref": "#/definitions/container.SignaturePolicy" } } }, "controllers.PCIDevice": { "type": "object", "properties": { "address": { "type": "string", "example": "0000:65:00.0" }, "class": { "type": "string", "example": "0x0300" }, "className": { "type": "string", "example": "Display controller" }, "driver": { "type": "string", "example": "nvidia" }, "product": { "type": "string", "example": "0x20b0" }, "productName": { "type": "string", "example": "GA100 [A100 SXM4 40GB]" }, "revision": { "type": "string", "example": "0xa1" }, "subclassName": { "type": "string", "example": "VGA compatible controller" }, "vendor": { "type": "string", "example": "0x10de" }, "vendorName": { "type": "string", "example": "NVIDIA Corporation" } } }, "controllers.PaginatedProfilesResponse": { "type": "object", "properties": { "limit": { "type": "integer" }, "page": { "type": "integer" }, "profiles": { "type": "array", "items": { "$ref": "#/definitions/provisioning.ProvisioningProfile" } }, "total": { "type": "integer" } } }, "controllers.PaginationInfo": { "type": "object", "properties": { "limit": { "type": "integer", "example": 10 }, "page": { "type": "integer", "example": 1 }, "total": { "type": "integer", "example": 42 }, "totalPages": { "type": "integer", "example": 5 } } }, "controllers.Partition": { "type": "object", "properties": { "disk": { "type": "string", "example": "mmcblk0" }, "label": { "type": "string", "example": "boot-a" }, "name": { "type": "string", "example": "mmcblk0p2" }, "number": { "type": "integer", "example": 2 }, "role": { "type": "string", "enum": [ "esp", "boot-a", "boot-b", "app", "admrl", "other" ], "example": "boot-a" }, "roleFrom": { "type": "string", "enum": [ "label", "position" ], "example": "label" }, "sizeBytes": { "type": "integer", "example": 536870912 }, "slot": { "type": "string", "enum": [ "A", "B" ], "example": "A" } } }, "controllers.PartitionStats": { "type": "object", "properties": { "device": { "type": "string", "example": "/dev/sda1" }, "free_bytes": { "type": "integer", "example": 29779435520 }, "fs_type": { "type": "string", "enum": [ "ext4", "xfs", "btrfs", "zfs", "vfat", "ntfs" ], "example": "ext4" }, "inodes_free": { "type": "integer", "example": 6029312 }, "inodes_total": { "type": "integer", "example": 6553600 }, "inodes_used": { "type": "integer", "example": 524288 }, "mount_point": { "type": "string", "example": "/" }, "read_bytes": { "type": "integer", "example": 1073741824 }, "read_ops": { "type": "integer", "example": 123456 }, "total_bytes": { "type": "integer", "example": 107374182400 }, "usage_percent": { "type": "number", "example": 72.3 }, "used_bytes": { "type": "integer", "example": 77594746880 }, "write_bytes": { "type": "integer", "example": 2147483648 }, "write_ops": { "type": "integer", "example": 234567 } } }, "controllers.ProbeReport": { "type": "object", "properties": { "durationMs": { "type": "integer" }, "error": { "description": "Error is set when the probe could not run at all; Sections may still be\npartial.", "type": "string" }, "generatedAt": { "description": "GeneratedAt is the device clock when the probe finished.", "type": "string" }, "networkVerdict": { "$ref": "#/definitions/networkverdict.Verdict" }, "sections": { "type": "array", "items": { "$ref": "#/definitions/diagnostics.Section" } }, "worst": { "description": "Worst is the highest Level across every item (ok|info|warn|error).", "type": "string" } } }, "controllers.ProbeRequest": { "type": "object", "properties": { "sections": { "type": "array", "items": { "type": "string" } }, "timeoutMs": { "type": "integer" } } }, "controllers.ProcessStats": { "type": "object", "properties": { "running_processes": { "type": "integer", "example": 3 }, "sleeping_processes": { "type": "integer", "example": 240 }, "stopped_processes": { "type": "integer", "example": 2 }, "total_processes": { "type": "integer", "example": 245 }, "zombie_processes": { "type": "integer", "example": 0 } } }, "controllers.Product": { "type": "object", "properties": { "family": { "type": "string", "example": "PowerEdge" }, "name": { "type": "string", "example": "PowerEdge R750" }, "serialNumber": { "type": "string", "example": "7X9KQ3" }, "uuid": { "type": "string", "example": "4c4c4544-0058-3910-804b-b4c04f513333" }, "vendor": { "type": "string", "example": "Dell Inc." }, "version": { "type": "string", "example": "01" } } }, "controllers.ProfileListData": { "type": "object", "properties": { "profiles": { "type": "array", "items": { "$ref": "#/definitions/iam.ProfileView" } }, "roles": { "type": "array", "items": { "$ref": "#/definitions/iam.ProfileView" } } } }, "controllers.ProfileTag": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "controllers.ProxyRequest": { "type": "object", "properties": { "ignore_tls": { "type": "boolean" }, "server": { "type": "string" } } }, "controllers.RebootSpecRequest": { "type": "object", "properties": { "force": { "type": "boolean" } } }, "controllers.RepositorySettings": { "type": "object", "properties": { "connected": { "type": "boolean", "example": false }, "url": { "type": "string", "example": "https://github.com/org/repo" } } }, "controllers.ResetDeviceResponse": { "type": "object", "properties": { "device_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "force": { "type": "boolean", "example": false }, "operation": { "type": "string", "enum": [ "reset" ], "example": "reset" }, "warning": { "type": "string", "example": "This is a destructive operation that will restore the device to factory settings" } } }, "controllers.Response": { "type": "object", "properties": { "code": { "type": "integer" }, "data": {}, "msg": { "type": "string" }, "success": { "type": "boolean" } } }, "controllers.RestartWorkloadRequest": { "type": "object", "properties": { "container_target": { "type": "string" } } }, "controllers.RollbackConfigurationRequest": { "type": "object", "properties": { "reason": { "type": "string" }, "target_version": { "type": "integer" } } }, "controllers.RollbackConfigurationResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "latest_version": { "type": "integer", "example": 8 }, "rolled_back_to": { "type": "integer", "example": 5 }, "updated_at": { "type": "string", "example": "2024-09-12T14:30:00Z" } } }, "controllers.RolloutControlRequest": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500, "example": "image crashes on rev B boards" } } }, "controllers.RolloutControlResponse": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "pause", "resume", "cancel", "rollback" ] }, "previousStatus": { "type": "string" }, "rolloutId": { "type": "string" }, "status": { "type": "string", "enum": [ "signalled" ] } } }, "controllers.RolloutCreatedAcceptedResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } }, "controllers.RolloutDTO": { "type": "object", "properties": { "completed_at": { "type": "string", "example": "2024-09-12T15:02:48Z" }, "config": { "type": "string", "example": "7c1f2a8b-3d4e-4f5a-9b0c-1d2e3f4a5b6c" }, "config_name": { "type": "string", "example": "prod-base-config" }, "counts": { "$ref": "#/definitions/rollout.Counts" }, "created_at": { "type": "string", "example": "2024-09-12T14:29:00Z" }, "description": { "type": "string", "example": "Deploys 1.4.2 across the production fleet" }, "duration": { "type": "string", "example": "31m43s" }, "failure_breakdown": { "$ref": "#/definitions/controllers.FailureBreakdownDTO" }, "fleet_ids": { "type": "array", "items": { "type": "string" } }, "fleet_names": { "type": "object", "additionalProperties": { "type": "string" } }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "is_disruptive": { "type": "boolean", "example": true }, "name": { "type": "string", "example": "Q3 firmware rollout" }, "pausedAt": { "type": "string" }, "pausedReason": { "type": "string", "enum": [ "operator", "failure_threshold", "max_unavailable", "canary_failed", "canary_stuck" ] }, "progress_pct": { "type": "integer", "example": 73 }, "scheduled_at": { "type": "string", "example": "2024-09-12T14:30:00Z" }, "stage": { "description": "Stage is the canary stage while strategy.canary \u003e 0 (\"canary\" until\nevery canary device converged, then \"rollout\"); \"\" without canary.\nStatus stays in_progress throughout.", "type": "string", "enum": [ "canary", "rollout", "" ], "example": "canary" }, "started_at": { "type": "string", "example": "2024-09-12T14:31:05Z" }, "stats": { "$ref": "#/definitions/controllers.RolloutStatsDTO" }, "status": { "type": "string", "enum": [ "pending", "scheduled", "in_progress", "completed", "failed", "cancelled", "paused" ], "example": "in_progress" }, "strategy": { "description": "Convergence scheduler (ADDENDUM-A §A3).", "allOf": [ { "$ref": "#/definitions/rollout.Strategy" } ] }, "system_update_spec": { "$ref": "#/definitions/rollout.SystemUpdateSpec" }, "target_image": { "type": "string", "example": "registry.example.com/admiral/agent:1.4.2" }, "type": { "type": "string", "enum": [ "config", "system_update", "initram_update", "kernel_update", "modules_update", "reboot", "restart_workload" ], "example": "system_update" }, "updated_at": { "type": "string", "example": "2024-09-12T15:02:48Z" }, "version": { "type": "integer", "example": 7 }, "workflow_info": { "$ref": "#/definitions/controllers.WorkflowInfoDTO" } } }, "controllers.RolloutDeviceDTO": { "type": "object", "properties": { "admittedAt": { "description": "Convergence scheduler: Phase above carries the derived phase\n(waiting_online, assigned, pulling_image, extracting, downloading,\ninstalling, verifying, staged, starting, converged, failed, unknown).", "type": "string" }, "completed_at": { "type": "string", "example": "2024-09-12T14:43:22Z" }, "convergedAt": { "type": "string" }, "device_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "device_name": { "type": "string", "example": "warehouse-edge-07" }, "duration": { "type": "string", "example": "12m17s" }, "error": { "type": "string", "example": "image pull failed: unauthorized" }, "error_type": { "type": "string", "enum": [ "image_pull_failed", "timeout_failed", "validation_failed", "network_failed", "other_failed" ], "example": "image_pull_failed" }, "id": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-1234567890ef" }, "isCanary": { "description": "IsCanary: the device was admitted in the canary stage.", "type": "boolean" }, "lastProgress": { "$ref": "#/definitions/rollout.ProgressSnapshot" }, "last_event_time": { "type": "string", "example": "2024-09-12T14:42:18Z" }, "last_event_type": { "type": "string", "example": "phase_changed" }, "phase": { "type": "string", "enum": [ "queued", "downloading", "validating", "applying", "rebooting", "completed" ], "example": "downloading" }, "started_at": { "type": "string", "example": "2024-09-12T14:31:05Z" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "success", "failed", "skipped", "cancelled" ], "example": "in_progress" }, "stuckSince": { "type": "string" }, "update_progress": { "$ref": "#/definitions/rollout.UpdateProgress" }, "updated_at": { "type": "string", "example": "2024-09-12T14:43:22Z" } } }, "controllers.RolloutDevicesEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/controllers.RolloutDeviceDTO" } }, "message": { "type": "string", "example": "Success" }, "pagination": { "$ref": "#/definitions/controllers.PaginationInfo" }, "success": { "type": "boolean", "example": true } } }, "controllers.RolloutSettings": { "type": "object", "properties": { "trigger": { "type": "string", "enum": [ "automatic", "manual" ], "example": "manual" } } }, "controllers.RolloutStatsDTO": { "type": "object", "properties": { "active": { "type": "integer", "example": 4 }, "failed": { "type": "integer", "example": 2 }, "pending": { "type": "integer", "example": 6 }, "success": { "type": "integer", "example": 30 }, "total": { "type": "integer", "example": 42 } } }, "controllers.RunningWorkload": { "type": "object", "properties": { "configurationName": { "type": "string", "example": "nginx-micro-auth" }, "image": { "type": "string", "example": "ghcr.io/acme/app:1.2.3" }, "version": { "type": "integer", "example": 7 } } }, "controllers.ScanWifiResponse": { "type": "object", "properties": { "host_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "interface_mac": { "type": "string", "example": "aa:bb:cc:dd:ee:ff" }, "networks": { "type": "array", "items": { "$ref": "#/definitions/controllers.ScannedNetworkResponse" } }, "scanned_at": { "type": "string", "example": "2024-09-12T14:30:00Z" } } }, "controllers.ScannedNetworkResponse": { "type": "object", "properties": { "security": { "type": "string", "enum": [ "open", "wep", "wpa", "wpa2", "wpa3" ], "example": "wpa2" }, "ssid": { "type": "string", "example": "corp-wifi" }, "strength": { "type": "integer", "example": -58 } } }, "controllers.ScreenshotCreateRequest": { "type": "object", "properties": { "display": { "type": "integer", "example": 0 }, "format": { "type": "string", "enum": [ "png", "jpeg" ], "example": "jpeg" }, "maxWidth": { "type": "integer", "example": 1280 }, "quality": { "type": "integer", "example": 80 }, "source": { "type": "string", "enum": [ "auto", "display", "virtual" ], "example": "auto" } } }, "controllers.ScreenshotMeta": { "type": "object", "properties": { "code": { "type": "string", "example": "busy" }, "createdAt": { "type": "string", "example": "2026-10-07T10:30:00Z" }, "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "error": { "type": "string", "example": "" }, "expiresAt": { "type": "string", "example": "2026-10-07T10:45:00Z" }, "format": { "type": "string", "example": "jpeg" }, "height": { "type": "integer", "example": 1080 }, "id": { "type": "string", "example": "3f2a9c1e5b7d4e8a9c0b1d2e3f4a5b6c" }, "imageUrl": { "type": "string", "example": "/v1/devices/550e8400-e29b-41d4-a716-446655440000/screenshots/3f2a9c1e5b7d4e8a9c0b1d2e3f4a5b6c/image" }, "organisationId": { "type": "string", "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, "readyAt": { "type": "string", "example": "2026-10-07T10:30:01Z" }, "requestedBy": { "type": "string", "example": "user-123" }, "sha256": { "type": "string", "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }, "size": { "type": "integer", "example": 183422 }, "source": { "type": "string", "example": "display" }, "status": { "type": "string", "enum": [ "pending", "ready", "failed" ], "example": "ready" }, "timings": { "$ref": "#/definitions/controllers.ScreenshotTimings" }, "transport": { "type": "string", "enum": [ "v1", "v2" ], "example": "v2" }, "width": { "type": "integer", "example": 1920 } } }, "controllers.ScreenshotResponse": { "type": "object", "properties": { "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "format": { "type": "string", "enum": [ "png", "jpeg" ], "example": "jpeg" }, "height": { "type": "integer", "example": 1080 }, "imageData": { "type": "string", "example": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==" }, "message": { "description": "Message is a human sentence for non-ok statuses or fallback notes.", "type": "string", "example": "" }, "screen": { "description": "Screen names the console screen shown (virtual source only).", "type": "string", "example": "home" }, "source": { "type": "string", "enum": [ "display", "virtual" ], "example": "display" }, "status": { "type": "string", "enum": [ "ok", "disabled", "no_display", "capture_failed", "busy", "too_large", "bad_request" ], "example": "ok" }, "timestamp": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "width": { "type": "integer", "example": 1920 } } }, "controllers.ScreenshotTimings": { "type": "object", "properties": { "ackMs": { "type": "integer", "example": 12 }, "assembleMs": { "type": "integer", "example": 35 }, "captureMs": { "type": "integer", "example": 180 }, "encodeMs": { "type": "integer", "example": 95 }, "publishMs": { "type": "integer", "example": 140 }, "totalMs": { "type": "integer", "example": 520 }, "v1RoundTripMs": { "type": "integer", "example": 0 } } }, "controllers.SecurityPolicyRequirements": { "type": "object", "properties": { "require_disk_encryption": { "type": "boolean" }, "require_recovery_key_escrow": { "type": "boolean" }, "require_secure_boot": { "type": "boolean" }, "require_tpm": { "type": "boolean" } } }, "controllers.ServiceDiscoveryResponse": { "type": "object", "properties": { "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "services": { "type": "array", "items": { "$ref": "#/definitions/controllers.ServiceInfoResponse" } } } }, "controllers.ServiceInfoResponse": { "type": "object", "properties": { "port": { "type": "integer", "example": 22 }, "protocol": { "type": "string", "enum": [ "tcp", "udp" ], "example": "tcp" } } }, "controllers.ServiceUnavailableResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 503 }, "msg": { "type": "string", "example": "Service temporarily unavailable" } } }, "controllers.SetAirdetectRequest": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true } } }, "controllers.SetCustomMetricsRequest": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true } } }, "controllers.SetDeviceCacheManifestRequest": { "type": "object", "properties": { "image_names": { "type": "array", "items": { "type": "string" }, "example": [ "nginx:latest", "redis:alpine", "postgres:14" ] } } }, "controllers.SetDeviceCacheManifestResponse": { "type": "object", "properties": { "host_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "image_count": { "type": "integer", "example": 3 }, "message": { "type": "string", "example": "Cache manifest with 3 images sent successfully" }, "status": { "type": "string", "enum": [ "sent" ], "example": "sent" }, "timestamp": { "type": "string", "example": "2024-01-15T10:30:00Z" } } }, "controllers.SetDeviceImagePinRequest": { "type": "object", "properties": { "image": { "type": "string", "example": "nginx:latest" }, "pinned": { "type": "boolean", "example": true } } }, "controllers.SetFeatureRequest": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true } } }, "controllers.SetFleetNetworkConfigurationRequest": { "type": "object", "required": [ "interfaces" ], "properties": { "bridges": { "type": "array", "items": { "$ref": "#/definitions/controllers.FleetBridgeConfigRequest" } }, "client_networks": { "type": "array", "items": { "$ref": "#/definitions/controllers.FleetClientNetworkConfigRequest" } }, "interfaces": { "type": "array", "items": { "$ref": "#/definitions/controllers.FleetInterfaceConfigRequest" } }, "nameservers": { "type": "array", "items": { "type": "string" } } } }, "controllers.SetFleetSSHRequest": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true } } }, "controllers.SetImageProxyRequest": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true } } }, "controllers.SetNetworkConfigurationRequest": { "type": "object", "required": [ "interfaces" ], "properties": { "bridges": { "type": "array", "items": { "$ref": "#/definitions/controllers.BridgeConfigRequest" } }, "client_networks": { "type": "array", "items": { "$ref": "#/definitions/controllers.ClientNetworkConfigRequest" } }, "interfaces": { "type": "array", "items": { "$ref": "#/definitions/controllers.InterfaceConfigRequest" } }, "nameservers": { "type": "array", "items": { "type": "string" } } } }, "controllers.SettingsResponse": { "type": "object", "properties": { "cicd": { "$ref": "#/definitions/controllers.CICDSettings" }, "notifications": { "$ref": "#/definitions/controllers.NotificationSettings" }, "rollouts": { "$ref": "#/definitions/controllers.RolloutSettings" }, "terraform": { "$ref": "#/definitions/controllers.TerraformSettings" } } }, "controllers.StateStreamEvent": { "type": "object", "properties": { "at": { "type": "string" }, "deviceId": { "type": "string" }, "kind": { "type": "string" }, "state": { "$ref": "#/definitions/state.DeviceState" } } }, "controllers.StrategyRequest": { "type": "object", "properties": { "canary": { "type": "integer", "minimum": 0, "example": 1 }, "failureThreshold": { "type": "number", "maximum": 1, "minimum": 0, "example": 0.1 }, "maxInFlight": { "type": "integer", "minimum": 1, "example": 50 }, "maxUnavailable": { "type": "integer", "minimum": 0, "example": 2 }, "progressDeadline": { "description": "ProgressDeadline is a duration (\"30m\") or a number of seconds.", "type": "string", "example": "30m" } } }, "controllers.SystemServicesResponse": { "type": "object", "properties": { "collectedAt": { "description": "CollectedAt is unix milliseconds on the device clock.", "type": "integer" }, "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "error": { "description": "Error is set when the report could not be produced (no scan dir, unknown\nservice name, ...). Services may still hold partial data.", "type": "string" }, "services": { "type": "array", "items": { "$ref": "#/definitions/services.Service" } }, "summary": { "$ref": "#/definitions/services.Summary" }, "supervisor": { "description": "Supervisor is the init supervisor the data came from (\"s6\").", "type": "string" } } }, "controllers.SystemUpdateSpecRequest": { "type": "object", "properties": { "final_action": { "type": "string" }, "use_current_versions": { "type": "boolean" }, "version_ids": { "type": "array", "items": { "type": "string" } } } }, "controllers.SystemVersions": { "type": "object", "properties": { "initVersion": { "type": "string", "example": "1.4.0" }, "kernelVersion": { "type": "string", "example": "5.15.136-tegra" }, "modulesVersion": { "type": "string", "example": "5.15.0-89" }, "rootfsVersion": { "type": "string", "example": "2023.10.1" } } }, "controllers.Tag": { "type": "object", "properties": { "key": { "type": "string", "example": "environment" }, "value": { "type": "string", "example": "production" } } }, "controllers.TagKeyEntry": { "type": "object", "properties": { "count": { "type": "integer", "example": 42 }, "key": { "type": "string", "example": "environment" }, "sample_values": { "type": "array", "items": { "type": "string" }, "example": [ "production", "staging", "development" ] } } }, "controllers.TerraformSettings": { "type": "object", "properties": { "connected": { "type": "boolean", "example": false } } }, "controllers.TicketSubjectRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "fleet", "configuration", "device" ] } } }, "controllers.TokenResponse": { "type": "object", "properties": { "access_token": { "type": "string", "example": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNhLWtleS0x..." }, "expires_at": { "type": "integer", "example": 1780637469 }, "expires_in": { "type": "integer", "example": 3600 }, "token_type": { "type": "string", "example": "Bearer" } } }, "controllers.TopologyInfo": { "type": "object", "properties": { "architecture": { "type": "string", "example": "x86_64" }, "caches": { "type": "array", "items": { "$ref": "#/definitions/controllers.Cache" } }, "numa_nodes": { "type": "array", "items": { "$ref": "#/definitions/controllers.NUMANode" } } } }, "controllers.UnauthorizedResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 401 }, "msg": { "type": "string", "example": "Authentication required" } } }, "controllers.UnpairDeviceResponse": { "type": "object", "properties": { "device_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "force": { "type": "boolean", "example": false }, "operation": { "type": "string", "enum": [ "unpair" ], "example": "unpair" }, "warning": { "type": "string", "example": "This device will be removed from the control plane" } } }, "controllers.UpdateConfigurationRequestBody": { "type": "object", "properties": { "change_reason": { "type": "string", "example": "Bumped agent reconnect interval" }, "description": { "type": "string", "example": "Baseline configuration for production fleet" }, "name": { "type": "string", "example": "prod-base-config" }, "spec": { "$ref": "#/definitions/configuration.ConfigurationSpec" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "production", "baseline" ] } } }, "controllers.UpdateConfigurationSpecRequest": { "type": "object", "properties": { "change_reason": { "type": "string", "example": "Bumped image tag" }, "spec": { "$ref": "#/definitions/configuration.ConfigurationSpec" } } }, "controllers.UpdateConfigurationStatusRequest": { "type": "object", "properties": { "status": { "minLength": 1, "enum": [ "Draft", "Active", "Testing", "Deprecated", "Archived" ], "allOf": [ { "$ref": "#/definitions/configuration.ConfigStatus" } ], "example": "Active" } } }, "controllers.UpdateCredentialRequest": { "type": "object", "properties": { "auth": { "type": "string" }, "aws_access_key_id": { "type": "string" }, "aws_region": { "type": "string" }, "aws_secret_access_key": { "type": "string" }, "aws_session_token": { "type": "string" }, "description": { "type": "string" }, "identity_token": { "type": "string" }, "name": { "type": "string" }, "password": { "type": "string" }, "registry": { "type": "string" }, "registry_token": { "type": "string" }, "username": { "type": "string" } } }, "controllers.UpdateFleetRequest": { "type": "object", "properties": { "description": { "type": "string", "example": "Primary production fleet for region AU-SE" }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "example": [ "550e8400-e29b-41d4-a716-446655440000" ] }, "location": { "type": "string", "example": "Sydney, AU" }, "name": { "type": "string", "example": "production-fleet" }, "signaturePolicy": { "description": "SignaturePolicy replaces the fleet's image-signature policy when\npresent. Absent/null leaves it unchanged; send {} (or an object with\nrequired=false and no roots) to clear it.", "allOf": [ { "$ref": "#/definitions/container.SignaturePolicy" } ] }, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.FleetTag" } }, "update_window": { "$ref": "#/definitions/controllers.UpdateWindowRequest" } } }, "controllers.UpdateHostConfigurationRequest": { "type": "object", "properties": { "change_reason": { "description": "ChangeReason is accepted as an alias of reason (the field name used in\nthe configuration history and by the CLI); reason wins when both are set.", "type": "string", "example": "Custom environment variables for this device" }, "override": { "$ref": "#/definitions/host.ConfigurationOverride" }, "reason": { "type": "string", "example": "Custom environment variables for this device" } } }, "controllers.UpdateHostConfigurationResponse": { "type": "object", "properties": { "configuration_override": { "$ref": "#/definitions/host.ConfigurationOverride" }, "has_override": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "overridden_paths": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string", "example": "2024-09-12T14:30:00Z" } } }, "controllers.UpdateHostRequest": { "type": "object", "properties": { "location": { "$ref": "#/definitions/controllers.LocationCoordinates" }, "name": { "type": "string" }, "notes": { "type": "string" }, "screenshots_disabled": { "description": "ScreenshotsDisabled turns on-demand screenshots off (true) or on (false).", "type": "boolean" }, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.Tag" } } } }, "controllers.UpdateHostResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "location": { "$ref": "#/definitions/controllers.LocationInfo" }, "name": { "type": "string", "example": "edge-device-01" }, "notes": { "type": "string", "example": "Rack 3, shelf 2" }, "screenshots_disabled": { "description": "ScreenshotsDisabled is the device's current screenshot switch. Always present.", "type": "boolean", "example": false }, "tags": { "type": "array", "items": { "$ref": "#/definitions/controllers.Tag" } }, "updated_at": { "type": "string", "example": "2024-09-12T14:30:00Z" } } }, "controllers.UpdatePolicyRequest": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "latest", "pinned" ], "example": "pinned" }, "targets": { "type": "array", "items": { "$ref": "#/definitions/controllers.UpdateTargetRequest" } }, "update_window": { "description": "UpdateWindow is optional. When present, it sets the fleet's auto-update\nschedule in the same call. Omit to leave the existing window unchanged.", "allOf": [ { "$ref": "#/definitions/controllers.UpdateWindowRequest" } ] } } }, "controllers.UpdateProfileStatusRequest": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "controllers.UpdateSettingsRequest": { "type": "object", "properties": { "notifications": { "$ref": "#/definitions/controllers.NotificationSettings" }, "rollouts": { "$ref": "#/definitions/controllers.RolloutSettings" }, "terraform": { "$ref": "#/definitions/controllers.TerraformSettings" } } }, "controllers.UpdateTargetRequest": { "type": "object", "properties": { "architecture": { "type": "string", "example": "arm64" }, "board": { "type": "string", "example": "jetson-orin-nano" }, "initram_version_id": { "type": "string" }, "system_version_id": { "type": "string" } } }, "controllers.UpdateUserFleetRoleRequest": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "admin", "editor", "viewer" ], "example": "admin" } } }, "controllers.UpdateWindowRequest": { "type": "object", "required": [ "days", "end_time", "start_time", "timezone" ], "properties": { "days": { "type": "array", "items": { "type": "string", "enum": [ "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday" ] }, "example": [ "Monday", "Tuesday", "Wednesday" ] }, "enabled": { "type": "boolean", "example": true }, "end_time": { "type": "string", "example": "06:00" }, "start_time": { "type": "string", "example": "02:00" }, "timezone": { "type": "string", "minLength": 1, "example": "Australia/Sydney" } } }, "controllers.UsbInventoryResponse": { "type": "object", "properties": { "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "report": { "type": "object" } } }, "controllers.UsbPolicyRequest": { "type": "object", "properties": { "allow": { "type": "array", "items": { "$ref": "#/definitions/usbpolicy.Rule" } }, "mode": { "type": "string", "enum": [ "off", "block_storage_hid", "allowlist" ], "example": "block_storage_hid" } } }, "controllers.ValidatePairingKeyRequest": { "type": "object", "properties": { "pairing_key": { "type": "string", "minLength": 1, "example": "ABCDEF1" } } }, "controllers.ValidatePairingKeyResponse": { "type": "object", "properties": { "pairing_key": { "type": "string", "example": "PK-ABCDEF123456" }, "valid": { "type": "boolean", "example": true } } }, "controllers.VolumeBackupCommandResponse": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "DELETE_BACKUP", "DELETE_BACKUPS" ], "example": "DELETE_BACKUP" }, "backup": { "type": "string", "example": "20260510225937" }, "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "error": { "type": "string", "example": "" }, "success": { "type": "boolean", "example": true }, "timestamp": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "volume": { "type": "string", "example": "data-vol" } } }, "controllers.VolumeBackupResponse": { "type": "object", "properties": { "createdAt": { "type": "string", "example": "2026-05-10T22:59:37Z" }, "name": { "type": "string", "example": "20260510225937" }, "usageBytes": { "type": "integer", "example": 524288000 } } }, "controllers.VolumeCommandResponse": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "CREATE", "DELETE", "LIST" ], "example": "CREATE" }, "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "error": { "type": "string", "example": "" }, "name": { "type": "string", "example": "data-vol" }, "success": { "type": "boolean", "example": true }, "timestamp": { "type": "string", "example": "2024-01-15T10:30:00Z" } } }, "controllers.VolumeInfoResponse": { "type": "object", "properties": { "backups": { "description": "Backups lists backup snapshots, newest first. Absent on agents that predate it.", "type": "array", "items": { "$ref": "#/definitions/controllers.VolumeBackupResponse" } }, "createdAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "hash": { "description": "Hash is the on-disk volume id; use it to address volumes with no name.", "type": "string", "example": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b" }, "id": { "type": "integer", "example": 257 }, "inUse": { "description": "InUse is true when the device's current configuration references the volume.", "type": "boolean", "example": true }, "name": { "type": "string", "example": "data-vol" }, "parentId": { "type": "integer", "example": 5 }, "path": { "type": "string", "example": "/var/lib/admiral/volumes/data-vol" }, "quotaBytes": { "type": "integer", "example": 10737418240 }, "readOnly": { "type": "boolean", "example": false }, "usageBytes": { "type": "integer", "example": 524288000 } } }, "controllers.VolumeListResponse": { "type": "object", "properties": { "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "volumes": { "type": "array", "items": { "$ref": "#/definitions/controllers.VolumeInfoResponse" } } } }, "controllers.WAFBlockedData": { "type": "object", "properties": { "error": { "type": "string", "example": "waf_blocked" }, "request_id": { "type": "string", "example": "456f77ef-4aee-483f-8059-816a783a86a7" } } }, "controllers.WAFBlockedResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/controllers.WAFBlockedData" }, "message": { "type": "string", "example": "Command Injection Pattern" } } }, "controllers.WifiDeviceRequest": { "type": "object", "required": [ "mode" ], "properties": { "access_point": { "$ref": "#/definitions/controllers.AccessPointConfigRequest" }, "country_code": { "type": "string" }, "mode": { "type": "string", "example": "client" }, "powersave": { "type": "boolean" } } }, "controllers.WifiStatusResponse": { "type": "object", "properties": { "channel": { "type": "integer", "example": 6 }, "rssi": { "type": "integer", "example": -58 }, "ssid": { "type": "string", "example": "corp-wifi" } } }, "controllers.WipeDeviceRequest": { "type": "object", "properties": { "images": { "description": "Images clears cached/pulled container images.", "type": "boolean", "example": true }, "secure": { "description": "Secure requests a secure (unrecoverable) wipe where supported.", "type": "boolean", "example": false }, "volumes": { "description": "Volumes clears BTRFS payload subvolumes.", "type": "boolean", "example": true } } }, "controllers.WipeDeviceResponse": { "type": "object", "properties": { "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "images": { "type": "boolean", "example": true }, "operation": { "type": "string", "example": "wipe" }, "secure": { "type": "boolean", "example": false }, "status": { "type": "string", "enum": [ "sent" ], "example": "sent" }, "timestamp": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "volumes": { "type": "boolean", "example": true } } }, "controllers.WipeOptions": { "type": "object", "properties": { "images": { "description": "Images clears cached/pulled container images on the device.", "type": "boolean", "example": true }, "secure": { "description": "Secure requests a secure erase (slower) rather than a logical delete.", "type": "boolean", "example": false }, "volumes": { "description": "Volumes clears BTRFS data subvolumes (application/persistent data).", "type": "boolean", "example": true } } }, "controllers.WorkflowInfoDTO": { "type": "object", "properties": { "run_id": { "type": "string", "example": "4e2c8f10-9b3a-4d61-8c6a-1f2e3d4c5b6a" }, "workflow_id": { "type": "string", "example": "rollout-550e8400-e29b-41d4-a716-446655440000" } } }, "controllers.WorkloadCommandRequest": { "type": "object", "properties": { "action": { "type": "string", "minLength": 1, "enum": [ "START", "STOP", "RESTART", "DELETE" ], "example": "START" } } }, "controllers.WorkloadCommandResponse": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "START", "STOP", "RESTART", "DELETE" ], "example": "START" }, "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "error": { "type": "string", "example": "" }, "success": { "type": "boolean", "example": true }, "timestamp": { "type": "string", "example": "2024-01-15T10:30:00Z" } } }, "controllers.WorkloadPushResponse": { "type": "object", "properties": { "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "message": { "type": "string", "example": "Workload configuration pushed successfully" }, "network": { "description": "Network is the result of pushing the network configuration alongside the\nworkload: \"applied\" (the device accepted it) or \"failed\".", "type": "string", "enum": [ "applied", "failed" ], "example": "applied" }, "operation": { "type": "string", "example": "push_workload_config" }, "status": { "type": "string", "enum": [ "sent", "queued", "failed" ], "example": "sent" }, "timestamp": { "type": "string", "example": "2024-01-15T10:30:00Z" } } }, "controllers.WorkloadReportConfiguration": { "type": "object", "properties": { "command": { "type": "array", "items": { "type": "string" } }, "configurationName": { "type": "string", "example": "kiosk-primary" }, "desiredState": { "type": "string", "enum": [ "RUNNING", "STOPPED" ], "example": "RUNNING" }, "env": { "type": "object", "additionalProperties": { "type": "string" } }, "image": { "type": "string", "example": "ghcr.io/acme/app:1.2.3" }, "name": { "type": "string", "example": "my-workload" }, "updatedAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "version": { "type": "integer", "example": 7 } } }, "controllers.WorkloadReportStatus": { "type": "object", "properties": { "error": { "type": "string", "example": "" }, "signature": { "$ref": "#/definitions/container.SignatureStatus" }, "startedAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "state": { "type": "string", "enum": [ "RUNNING", "STOPPED", "ERROR", "CRASHING" ], "example": "RUNNING" }, "transition": { "$ref": "#/definitions/controllers.WorkloadTransition" } } }, "controllers.WorkloadReportSummary": { "type": "object", "properties": { "configuration": { "$ref": "#/definitions/controllers.WorkloadReportConfiguration" }, "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "receivedAt": { "type": "string", "example": "2024-01-15T10:30:01Z" }, "reportedAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "status": { "$ref": "#/definitions/controllers.WorkloadReportStatus" } } }, "controllers.WorkloadStatusResponse": { "type": "object", "properties": { "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "error": { "type": "string", "example": "" }, "lastSeenAt": { "description": "LastSeenAt is the last heartbeat.", "type": "string" }, "latestReport": { "$ref": "#/definitions/controllers.WorkloadReportSummary" }, "online": { "description": "Online is the backend presence view at response time.", "type": "boolean" }, "reportedAt": { "description": "ReportedAt is when the device sent the data shown (stored), or now\n(live).", "type": "string" }, "running": { "$ref": "#/definitions/controllers.RunningWorkload" }, "signature": { "description": "Signature is the device-reported image-signature verification outcome\nfor the applied (or last attempted) image. Absent on devices that do not\nreport it or when no policy applies.", "allOf": [ { "$ref": "#/definitions/container.SignatureStatus" } ] }, "source": { "description": "Source is \"stored\" (last device report, the default) or \"live\"\n(?live=1, or no stored report yet).", "type": "string", "enum": [ "stored", "live" ] }, "startedAt": { "type": "string", "example": "2024-01-15T10:30:00Z" }, "state": { "type": "string", "enum": [ "running", "stopped", "starting", "stopping", "exited", "unknown", "error" ], "example": "running" }, "transition": { "$ref": "#/definitions/controllers.WorkloadTransition" }, "updatedAt": { "type": "string", "example": "2024-01-15T10:31:42Z" } } }, "controllers.WorkloadTransition": { "type": "object", "properties": { "message": { "type": "string", "example": "Downloading layer 2/5" }, "state": { "description": "\"resolving\", \"downloading\", \"extracting\", \"preparing\", \"staged\", \"starting\"", "type": "string", "example": "downloading" }, "targetVersion": { "type": "integer", "example": 8 } } }, "controllers.cliClientPub": { "type": "object", "properties": { "ed25519": { "type": "string" }, "mldsa65": { "type": "string" } } }, "controllers.cliEdgeWireRenewRequest": { "type": "object", "properties": { "nats_pub": { "type": "string" }, "signed_grant": { "$ref": "#/definitions/grant.SignedGrant" } } }, "controllers.cliEdgeWireRenewResponse": { "type": "object", "properties": { "expires_at": { "type": "string" }, "nats_jwt": { "type": "string" }, "signed_grant": { "$ref": "#/definitions/grant.SignedGrant" } } }, "controllers.cliEdgeWireRequest": { "type": "object", "properties": { "client_pub": { "$ref": "#/definitions/controllers.cliClientPub" }, "device_id": { "type": "string" }, "nats_pub": { "type": "string" }, "overrides": { "$ref": "#/definitions/grant.TransportParams" }, "preset": { "type": "string" }, "targets": { "type": "array", "items": { "type": "string" } } } }, "controllers.cliEdgeWireResponse": { "type": "object", "properties": { "device_ice": { "$ref": "#/definitions/signal.ICEInfo" }, "device_id": { "type": "string" }, "device_name": { "type": "string" }, "expires_at": { "type": "string" }, "inbox_prefix": { "type": "string" }, "nats_jwt": { "type": "string" }, "nats_urls": { "type": "array", "items": { "type": "string" } }, "org_id": { "type": "string" }, "session_id": { "type": "string" }, "signed_grant": { "$ref": "#/definitions/grant.SignedGrant" } } }, "controllers.edgeWireTokenRequest": { "type": "object", "properties": { "devices": { "type": "array", "items": { "type": "string" } }, "targets": { "type": "array", "items": { "type": "string" } }, "ttl_seconds": { "type": "integer" } } }, "controllers.edgeWireTokenResponse": { "type": "object", "properties": { "expires_at": { "type": "string" }, "id": { "description": "ID names the token for DELETE /edgewire/token/{id} and in audit records.", "type": "string" }, "scope": { "$ref": "#/definitions/controllers.edgeWireTokenScope" }, "subject": { "$ref": "#/definitions/iam.Subject" }, "token": { "description": "Token is the bearer token (admrl_ew_...) for the EdgeWire session endpoints.", "type": "string" } } }, "controllers.edgeWireTokenScope": { "type": "object", "properties": { "devices": { "type": "array", "items": { "type": "string" } }, "organisation_id": { "type": "string" }, "targets": { "type": "array", "items": { "type": "string" } } } }, "controllers.mcpAuthorizeRequestView": { "type": "object", "properties": { "client": { "$ref": "#/definitions/controllers.mcpClientView" }, "organisations": { "type": "array", "items": { "$ref": "#/definitions/controllers.mcpOrgView" } }, "resource": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/definitions/controllers.mcpScopeView" } } } }, "controllers.mcpClientView": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_name": { "type": "string" }, "client_uri": { "type": "string" }, "logo_uri": { "type": "string" }, "redirect_host": { "type": "string" } } }, "controllers.mcpDecisionBody": { "type": "object", "properties": { "approve": { "type": "boolean" }, "client_id": { "type": "string" }, "code_challenge": { "type": "string" }, "code_challenge_method": { "type": "string" }, "organization_id": { "type": "string" }, "redirect_uri": { "type": "string" }, "resource": { "type": "string" }, "response_type": { "type": "string" }, "scope": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string" } } }, "controllers.mcpOrgView": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "controllers.mcpScopeView": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "required": { "type": "boolean" } } }, "controllers.oauthErrorBody": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } }, "desired.BackupRetention": { "type": "object", "properties": { "days": { "type": "integer" }, "months": { "type": "integer" }, "recentEvery": { "type": "string" }, "weeks": { "type": "integer" } } }, "desired.ConnectivityPolicy": { "type": "object", "properties": { "breakGlassAfter": { "description": "BreakGlassAfter: reset all backoffs and reconnect from scratch every\nthis long while the backend is unreachable.", "type": "string" }, "dnsServers": { "description": "DNSServers (ip or ip:port) used when the system resolver fails; the\nbuilt-in public resolvers are appended.", "type": "array", "items": { "type": "string" } }, "heartbeatInterval": { "description": "HeartbeatInterval: how often the device checks in. The link probe runs\nat half this interval. The backend marks the device offline after 2.5x.", "type": "string" }, "highLatency": { "description": "HighLatency: a slower successful probe counts as a degraded link.", "type": "string" }, "ntpServers": { "description": "NTPServers are tried first; the built-in pools are always appended.", "type": "array", "items": { "type": "string" } }, "probeTargets": { "description": "ProbeTargets (host:port) for \"is the internet up\"; the backend host\nalways comes first and public anycast targets are appended.", "type": "array", "items": { "type": "string" } }, "probeTimeout": { "description": "ProbeTimeout: how long one link probe waits for the backend.", "type": "string" }, "rebuildAfter": { "description": "RebuildAfter: after this long unreachable, discard and rebuild the\nwhole connection client (no reboot), at the next half-way point\nbetween two break-glass resets.", "type": "string" } } }, "desired.DevicePolicy": { "type": "object", "properties": { "connectivity": { "$ref": "#/definitions/desired.ConnectivityPolicy" }, "health": { "$ref": "#/definitions/desired.HealthPolicy" }, "maintenance": { "$ref": "#/definitions/desired.MaintenancePolicy" }, "telemetry": { "$ref": "#/definitions/desired.TelemetryPolicy" } } }, "desired.HealthPolicy": { "type": "object", "properties": { "bootConnectivityBudget": { "description": "BootConnectivityBudget: reboot if no backend connection within this long\nof kernel boot. Reaching the backend also commits an OS A/B trial.", "type": "string" }, "crashBackoffMax": { "description": "CrashBackoffMax caps the delay between workload restarts. Workloads are\nrestarted forever; this only bounds how fast.", "type": "string" }, "kernelFatalCount": { "description": "KernelFatalCount kernel oopses within KernelFatalWindow trigger an\nemergency reboot.", "type": "integer" }, "kernelFatalWindow": { "type": "string" }, "maxOffline": { "description": "MaxOffline (deadman): reboot after losing the backend for this long.", "type": "string" }, "osTrialBoots": { "description": "OSTrialBoots: boots an OS update gets to reach the backend before the\nbootloader falls back to the previous slot. Applied when the next trial\nis armed.", "type": "integer" }, "watchdogStall": { "description": "WatchdogStall: stop feeding the hardware watchdog (board resets) when\nthe agent's own heartbeat has stalled this long.", "type": "string" }, "workloadTrialBoots": { "type": "integer" }, "workloadTrialFailures": { "description": "Workload rollback trial: a new configuration rolls back after\nWorkloadTrialFailures crashes, or WorkloadTrialBoots reboots, before it\nhas run WorkloadTrialProbation without failing.", "type": "integer" }, "workloadTrialProbation": { "type": "string" } } }, "desired.MaintenancePolicy": { "type": "object", "properties": { "backupRetention": { "$ref": "#/definitions/desired.BackupRetention" }, "filesystemScrubInterval": { "type": "string" }, "integrityScrubInterval": { "type": "string" }, "trimInterval": { "type": "string" }, "updateCheckInterval": { "description": "UpdateCheckInterval: fallback OS update poll when no window is set\n(updates are normally pushed).", "type": "string" }, "volumeBackupInterval": { "type": "string" } } }, "desired.TelemetryPolicy": { "type": "object", "properties": { "eventsInterval": { "type": "string" }, "logsInterval": { "type": "string" }, "metricsInterval": { "type": "string" }, "offlineBufferFiles": { "description": "OfflineBufferFiles caps the on-disk backlog per stream while offline.", "type": "integer" }, "stateRecheckInterval": { "type": "string" } } }, "device.EncryptionState": { "type": "object", "properties": { "cipher": { "type": "string" }, "enabled": { "type": "boolean" }, "keyProtector": { "description": "KeyProtector is how the volume opens unattended. See KeyProtector*.", "type": "string" }, "recoveryKeyPending": { "description": "RecoveryKeyPending is true while a staged recovery key has not yet been\nacknowledged by the backend. Escrow itself is confirmed backend-side.", "type": "boolean" }, "scheme": { "description": "Scheme is the container format, e.g. \"luks2\".", "type": "string" }, "sealedPcrs": { "description": "SealedPCRs are the PCR indices the TPM policy binds to.", "type": "array", "items": { "type": "integer" } } } }, "device.SecureBootState": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "enrolled": { "description": "[\"PK\", \"KEK\", \"db\", \"dbx\"]", "type": "array", "items": { "type": "string" } }, "mechanism": { "description": "Mechanism names what Enabled was read from. See SecureBootMechanism*.", "type": "string" }, "mode": { "description": "\"setup\" | \"user\" | \"custom\" | \"disabled\"", "type": "string" }, "setupMode": { "type": "boolean" }, "supported": { "description": "Supported is false when the platform has no verifiable secure boot\nmechanism the agent can read (e.g. U-Boot boards without FIT signing).\nAgents that predate the field send false; read it together with Mechanism.", "type": "boolean" } } }, "device.SecurityPosture": { "type": "object", "properties": { "encryption": { "$ref": "#/definitions/device.EncryptionState" }, "tpm": { "$ref": "#/definitions/device.TPMState" } } }, "device.SystemVersions": { "type": "object", "properties": { "initVersion": { "type": "string" }, "kernelVersion": { "type": "string" }, "modulesVersion": { "type": "string" }, "rootfsVersion": { "type": "string" } } }, "device.TPMState": { "type": "object", "properties": { "firmwareVersion": { "type": "string" }, "interface": { "type": "string" }, "kind": { "type": "string" }, "manufacturer": { "description": "Manufacturer is the TPM2_PT_MANUFACTURER vendor ID, e.g. \"INTC\", \"IFX\", \"NTC\".", "type": "string" }, "present": { "description": "Present is true when the kernel registered a TPM 2.0 device.", "type": "boolean" }, "specVersion": { "type": "string" }, "usable": { "description": "Usable is true when the agent can talk to it (resource manager node and\ntooling available). A present but unusable TPM cannot seal keys.", "type": "boolean" } } }, "devicepolicyservice.FieldSource": { "type": "object", "properties": { "level": { "$ref": "#/definitions/devicepolicyservice.Level" }, "path": { "description": "e.g. \"health.maxOffline\"", "type": "string" } } }, "devicepolicyservice.Level": { "type": "string", "enum": [ "default", "organisation", "fleet", "device" ], "x-enum-varnames": [ "LevelDefault", "LevelOrganisation", "LevelFleet", "LevelDevice" ] }, "devicepolicyservice.Resolved": { "type": "object", "properties": { "device": { "$ref": "#/definitions/desired.DevicePolicy" }, "effective": { "description": "Effective is Policy with defaults filled and clamps applied (what a\ncurrent agent will run), every field populated.", "allOf": [ { "$ref": "#/definitions/desired.DevicePolicy" } ] }, "fleet": { "$ref": "#/definitions/desired.DevicePolicy" }, "organisation": { "description": "Layers are the raw inputs, least specific first (nil = unset).", "allOf": [ { "$ref": "#/definitions/desired.DevicePolicy" } ] }, "policy": { "description": "Policy is what the renderer puts in Bundle.System.Policy: only fields\nsome layer set (nil when no layer sets anything).", "allOf": [ { "$ref": "#/definitions/desired.DevicePolicy" } ] }, "sources": { "description": "Sources lists, for every field set by some layer, the winning layer.\nFields absent here are LevelDefault.", "type": "array", "items": { "$ref": "#/definitions/devicepolicyservice.FieldSource" } } } }, "devicestate.CommsErrorBody": { "type": "object", "properties": { "detail": { "type": "string" }, "device_id": { "type": "string" }, "error": { "type": "string" } } }, "devicestate.Presence": { "type": "object", "properties": { "lastSeenAt": { "type": "string" }, "latencyMs": { "type": "integer" }, "transport": { "type": "string" } } }, "diagnostics.Item": { "type": "object", "properties": { "hint": { "description": "Hint is a one-line remediation suggestion when Level is warn/error.", "type": "string" }, "key": { "description": "Key is a stable machine identifier (e.g. \"dns.resolve\", \"tcp.latency.avg\").", "type": "string" }, "label": { "type": "string" }, "level": { "type": "string" }, "sensitive": { "description": "Sensitive marks values the backend redacts for non-support principals\n(hostnames, SSIDs, public keys, kernel cmdline).", "type": "boolean" }, "value": { "type": "string" } } }, "diagnostics.Section": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/diagnostics.Item" } }, "key": { "type": "string" }, "title": { "type": "string" } } }, "documentservice.AdoptResult": { "type": "object", "properties": { "adopted": { "type": "array", "items": { "type": "string" } }, "document": { "$ref": "#/definitions/documentservice.DeviceDocument" }, "notAdopted": { "type": "array", "items": { "$ref": "#/definitions/documentservice.FieldIssue" } }, "push": { "type": "string" } } }, "documentservice.Condition": { "type": "object", "properties": { "lastHeartbeat": { "type": "string" }, "lastTransition": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string" }, "type": { "type": "string" } } }, "documentservice.ConfigFleetUsage": { "type": "object", "properties": { "devices": { "type": "integer" }, "followsLatest": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "online": { "type": "integer" }, "version": { "description": "Version is the pinned version (absent when following latest).", "type": "integer" } } }, "documentservice.ConfigurationDocument": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "kind": { "type": "string" }, "metadata": { "$ref": "#/definitions/documentservice.Metadata" }, "spec": { "$ref": "#/definitions/configuration.ConfigurationSpec" }, "status": { "$ref": "#/definitions/documentservice.ConfigurationStatus" } } }, "documentservice.ConfigurationRenderResult": { "type": "object", "properties": { "diff": { "type": "array", "items": { "$ref": "#/definitions/documentservice.DiffEntry" } }, "fleets": { "type": "array", "items": { "type": "string" } }, "revision": { "type": "string" }, "spec": { "$ref": "#/definitions/configuration.ConfigurationSpec" } } }, "documentservice.ConfigurationStatus": { "type": "object", "properties": { "devicesByVersion": { "type": "object", "additionalProperties": { "type": "integer" } }, "fleetUsage": { "description": "FleetUsage details Fleets. Saving a new version is pushed at once to\nevery fleet that follows the latest version; pinned fleets keep theirs.", "type": "array", "items": { "$ref": "#/definitions/documentservice.ConfigFleetUsage" } }, "fleets": { "type": "array", "items": { "type": "string" } }, "latestVersion": { "type": "integer" }, "versions": { "type": "array", "items": { "$ref": "#/definitions/documentservice.VersionSummary" } } } }, "documentservice.DeviceDocument": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "kind": { "type": "string" }, "metadata": { "$ref": "#/definitions/documentservice.Metadata" }, "spec": { "$ref": "#/definitions/documentservice.DeviceSpec" }, "status": { "$ref": "#/definitions/documentservice.DeviceStatus" } } }, "documentservice.DevicePolicyStatus": { "type": "object", "properties": { "clamped": { "description": "Clamped lists policy paths the device replaced because the requested\nvalue was out of range. Never null.", "type": "array", "items": { "type": "string" } }, "reported": { "description": "Reported is the policy in force that the device reported (nil when\nthe device predates device policy or has not reported).", "allOf": [ { "$ref": "#/definitions/desired.DevicePolicy" } ] }, "requested": { "description": "Requested is the backend's resolution (org \u003c fleet \u003c device) with\nper-field provenance. Nil when no policy service is wired.", "allOf": [ { "$ref": "#/definitions/devicepolicyservice.Resolved" } ] } } }, "documentservice.DeviceSpec": { "type": "object", "properties": { "fleet": { "description": "Fleet is the fleet id; changing it moves the device.", "type": "string" }, "network": { "description": "Network is the device-level network configuration (null = inherit\nthe fleet's). Wifi passwords are never returned; omit psk to keep it.", "allOf": [ { "$ref": "#/definitions/networkservice.NetworkConfigurationInput" } ] }, "policy": { "description": "Policy is this device's own device-policy layer (null/absent = inherit\nthe fleet's and organisation's). Writable.", "allOf": [ { "$ref": "#/definitions/desired.DevicePolicy" } ] }, "secrets": { "description": "Secrets lists secret-file references in effect (read-only here).", "type": "array", "items": { "$ref": "#/definitions/documentservice.SecretRef" } }, "system": { "$ref": "#/definitions/documentservice.SystemSpec" }, "workload": { "$ref": "#/definitions/documentservice.WorkloadSpec" } } }, "documentservice.DeviceStatus": { "type": "object", "properties": { "boot": { "$ref": "#/definitions/state.Boot" }, "bootReasons": { "type": "array", "items": { "$ref": "#/definitions/state.BootReason" } }, "conditions": { "type": "array", "items": { "$ref": "#/definitions/documentservice.Condition" } }, "deadlines": { "description": "Deadlines are the device's own check-in and self-restart timers (nil\non agents that predate device policy).", "allOf": [ { "$ref": "#/definitions/state.Deadlines" } ] }, "localOverride": { "$ref": "#/definitions/state.LocalOverride" }, "network": { "$ref": "#/definitions/network.NetworkStatus" }, "observedGeneration": { "type": "integer" }, "policy": { "description": "Policy is the device-policy view: what the backend resolves for this\ndevice, what the device reports running, and what it clamped.", "allOf": [ { "$ref": "#/definitions/documentservice.DevicePolicyStatus" } ] }, "presence": { "$ref": "#/definitions/documentservice.Presence" }, "protocol": { "type": "integer" }, "renderedRevision": { "type": "string" }, "reportedAt": { "description": "ReportedAt is when the backend last received observed state.", "type": "string" }, "runtime": { "$ref": "#/definitions/state.WorkloadRuntime" }, "storage": { "type": "array", "items": { "$ref": "#/definitions/state.Filesystem" } }, "system": { "$ref": "#/definitions/state.System" }, "time": { "type": "string" }, "transport": { "$ref": "#/definitions/state.Transport" }, "workload": { "$ref": "#/definitions/container.ContainerStatus" } } }, "documentservice.Diagnosis": { "type": "object", "properties": { "deviceId": { "type": "string" }, "issues": { "type": "array", "items": { "$ref": "#/definitions/documentservice.Issue" } }, "lastReboot": { "$ref": "#/definitions/documentservice.LastReboot" }, "schedule": { "description": "Schedule is when the device last checked in, is due next, and will\nrestart itself if it stays offline. Null for a device never seen.", "allOf": [ { "$ref": "#/definitions/documentservice.Schedule" } ] }, "signals": { "$ref": "#/definitions/documentservice.Signals" }, "verdict": { "$ref": "#/definitions/documentservice.Verdict" } } }, "documentservice.DiffEntry": { "type": "object", "properties": { "from": {}, "path": { "type": "string" }, "to": {} } }, "documentservice.EventDigest": { "type": "object", "properties": { "count": { "type": "integer" }, "kinds": { "type": "object", "additionalProperties": { "type": "integer" } }, "notable": { "type": "array", "items": { "$ref": "#/definitions/documentservice.NotableEvent" } }, "sources": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "documentservice.FieldIssue": { "type": "object", "properties": { "message": { "type": "string" }, "path": { "type": "string" } } }, "documentservice.FleetConfigurationRef": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "$ref": "#/definitions/documentservice.VersionRef" } } }, "documentservice.FleetDeviceCounts": { "type": "object", "properties": { "converged": { "type": "integer" }, "crashing": { "type": "integer" }, "online": { "type": "integer" }, "stuck": { "type": "integer" }, "total": { "type": "integer" } } }, "documentservice.FleetDocument": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "kind": { "type": "string" }, "metadata": { "$ref": "#/definitions/documentservice.Metadata" }, "spec": { "$ref": "#/definitions/documentservice.FleetSpec" }, "status": { "$ref": "#/definitions/documentservice.FleetStatus" } } }, "documentservice.FleetFeatures": { "type": "object", "properties": { "airdetect": { "type": "boolean" }, "customMetrics": { "type": "boolean" }, "imageProxy": { "type": "boolean" }, "remoteSupport": { "type": "boolean" } } }, "documentservice.FleetRenderDevice": { "type": "object", "properties": { "deviceId": { "type": "string" }, "diff": { "type": "array", "items": { "$ref": "#/definitions/documentservice.DiffEntry" } }, "error": { "type": "string" }, "name": { "type": "string" }, "revision": { "type": "string" } } }, "documentservice.FleetRenderResult": { "type": "object", "properties": { "devices": { "type": "array", "items": { "$ref": "#/definitions/documentservice.FleetRenderDevice" } }, "specDiff": { "type": "array", "items": { "$ref": "#/definitions/documentservice.DiffEntry" } }, "total": { "type": "integer" }, "truncated": { "type": "boolean" } } }, "documentservice.FleetSpec": { "type": "object", "properties": { "configuration": { "$ref": "#/definitions/documentservice.FleetConfigurationRef" }, "features": { "$ref": "#/definitions/documentservice.FleetFeatures" }, "network": { "$ref": "#/definitions/github_com_qdynamicsco_admiral_src_domain_network.NetworkConfiguration" }, "policy": { "description": "Policy is the fleet's own device-policy layer (null/absent = none).\nWritable.", "allOf": [ { "$ref": "#/definitions/desired.DevicePolicy" } ] }, "security": { "$ref": "#/definitions/fleet.SecurityPolicy" }, "signaturePolicy": { "$ref": "#/definitions/container.SignaturePolicy" }, "updates": { "$ref": "#/definitions/documentservice.UpdatesSpec" }, "usbPolicy": { "$ref": "#/definitions/usbpolicy.Policy" } } }, "documentservice.FleetStatus": { "type": "object", "properties": { "devices": { "$ref": "#/definitions/documentservice.FleetDeviceCounts" }, "policy": { "description": "Policy is the effective fleet policy (org \u003c fleet) with provenance.", "allOf": [ { "$ref": "#/definitions/devicepolicyservice.Resolved" } ] } } }, "documentservice.HealthDigest": { "type": "object", "properties": { "cpu": { "type": "number" }, "disk": { "type": "number" }, "issues": { "type": "array", "items": { "type": "string" } }, "lastMetricTime": { "type": "string" }, "memory": { "type": "number" }, "overall": { "type": "string" }, "score": { "type": "number" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "documentservice.Issue": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "string" } }, "severity": { "type": "string" }, "since": { "type": "string" }, "title": { "type": "string" } } }, "documentservice.LastReboot": { "type": "object", "properties": { "at": { "type": "string" }, "detail": { "type": "string" }, "kind": { "type": "string" } } }, "documentservice.LogDigest": { "type": "object", "properties": { "count": { "type": "integer" }, "crashLike": { "type": "integer" }, "hasMore": { "type": "boolean" }, "levels": { "type": "object", "additionalProperties": { "type": "integer" } }, "samples": { "type": "array", "items": { "$ref": "#/definitions/documentservice.LogSample" } }, "sources": { "type": "object", "additionalProperties": { "type": "integer" } }, "topSignatures": { "type": "array", "items": { "$ref": "#/definitions/documentservice.Signature" } }, "window": { "$ref": "#/definitions/documentservice.LogWindow" } } }, "documentservice.LogSample": { "type": "object", "properties": { "level": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "string" }, "timestamp": { "type": "string" } } }, "documentservice.LogWindow": { "type": "object", "properties": { "count": { "type": "integer" }, "first": { "type": "string" }, "last": { "type": "string" } } }, "documentservice.Metadata": { "type": "object", "properties": { "createdAt": { "type": "string" }, "fleet": { "type": "string" }, "generation": { "type": "integer" }, "id": { "type": "string" }, "labels": { "type": "object", "additionalProperties": { "type": "string" } }, "name": { "type": "string" }, "organisation": { "type": "string" }, "resourceVersion": { "type": "string" }, "updatedAt": { "type": "string" } } }, "documentservice.NotableEvent": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "string" } }, "event": { "type": "string" }, "source": { "type": "string" }, "timestamp": { "type": "string" } } }, "documentservice.OrganisationDocument": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "kind": { "type": "string" }, "metadata": { "$ref": "#/definitions/documentservice.Metadata" }, "spec": { "$ref": "#/definitions/documentservice.OrganisationSpec" }, "status": { "$ref": "#/definitions/documentservice.OrganisationStatus" } } }, "documentservice.OrganisationSpec": { "type": "object", "properties": { "policy": { "description": "Policy is the organisation default device policy (null = none).", "allOf": [ { "$ref": "#/definitions/desired.DevicePolicy" } ] } } }, "documentservice.OrganisationStatus": { "type": "object", "properties": { "defaults": { "description": "Defaults is what a device runs when no layer sets a field.", "allOf": [ { "$ref": "#/definitions/desired.DevicePolicy" } ] }, "fleets": { "description": "Fleets is the number of fleets visible to the caller in the organisation.", "type": "integer" } } }, "documentservice.PolicyValidationError": { "type": "object", "properties": { "issues": { "type": "array", "items": { "$ref": "#/definitions/documentservice.FieldIssue" } } } }, "documentservice.Presence": { "type": "object", "properties": { "lastSeenAt": { "type": "string" }, "latencyMs": { "type": "integer" }, "online": { "type": "boolean" }, "transport": { "type": "string" } } }, "documentservice.RenderResult": { "type": "object", "properties": { "bundle": {}, "candidate": { "description": "Candidate renders (a Device document in the request body) only.\nCandidate is true; SpecDiff is the candidate spec against the stored\nspec; CurrentRevision/CurrentDiff compare the candidate render with\nthe current render; RenderedRevision is status.renderedRevision\n(Converged compares the candidate revision with it); NotRendered\nlists bundle sections served as stored because the renderer cannot\nderive them from the candidate.", "type": "boolean" }, "converged": { "description": "Converged is true when the device already reports this revision.", "type": "boolean" }, "currentDiff": { "type": "array", "items": { "$ref": "#/definitions/documentservice.DiffEntry" } }, "currentRevision": { "type": "string" }, "diff": { "type": "array", "items": { "$ref": "#/definitions/documentservice.DiffEntry" } }, "notRendered": { "description": "NotRendered is always present ([] when every section was rendered).", "type": "array", "items": { "type": "string" } }, "pushed": { "description": "Pushed is true when the render was pushed (dryRun=0).", "type": "boolean" }, "renderedRevision": { "type": "string" }, "revision": { "type": "string" }, "specDiff": { "type": "array", "items": { "$ref": "#/definitions/documentservice.DiffEntry" } } } }, "documentservice.Schedule": { "type": "object", "properties": { "heartbeatIntervalMs": { "type": "integer" }, "lastCheckInAt": { "type": "string" }, "limits": { "$ref": "#/definitions/documentservice.ScheduleLimits" }, "nextCheckInDueAt": { "type": "string" }, "offlineAfter": { "type": "string" }, "overdue": { "type": "boolean" }, "presenceWindowMs": { "type": "integer" }, "restart": { "description": "Restart is the next self-restart the device will perform; null while\nthe device is online and its boot is committed.", "allOf": [ { "$ref": "#/definitions/documentservice.ScheduledRestart" } ] }, "source": { "description": "Source says where the interval and limits came from: \"device\" (the\ndevice reported them), \"policy\" (resolved backend policy) or\n\"default\" (built-in).", "type": "string" } } }, "documentservice.ScheduleLimits": { "type": "object", "properties": { "bootBudgetMs": { "type": "integer" }, "maxOfflineMs": { "type": "integer" }, "watchdogStallMs": { "type": "integer" } } }, "documentservice.ScheduledRestart": { "type": "object", "properties": { "at": { "type": "string" }, "basis": { "description": "Basis is \"device\" (the device reported the deadline) or \"projected\"\n(computed by the backend because the device cannot be heard).", "type": "string" }, "detail": { "type": "string" }, "reason": { "description": "Reason is \"boot_budget\" or \"deadman\".", "type": "string" }, "thenEveryMs": { "description": "ThenEveryMs: after this restart the device restarts every this long\nuntil it reconnects (the boot connectivity budget).", "type": "integer" } } }, "documentservice.SecretRef": { "type": "object", "properties": { "path": { "type": "string" }, "ref": { "type": "string" } } }, "documentservice.Signals": { "type": "object", "properties": { "events": { "$ref": "#/definitions/documentservice.EventDigest" }, "failedUpdates": { "type": "array", "items": { "$ref": "#/definitions/state.FailedUpdate" } }, "floorBreach": { "$ref": "#/definitions/system.FloorBreachRecord" }, "health": { "$ref": "#/definitions/documentservice.HealthDigest" }, "lastSeenAt": { "type": "string" }, "logs": { "$ref": "#/definitions/documentservice.LogDigest" }, "pendingTrial": { "$ref": "#/definitions/state.Trial" }, "protocol": { "type": "integer" }, "stateReceivedAt": { "type": "string" }, "storage": { "type": "array", "items": { "$ref": "#/definitions/state.Filesystem" } }, "time": { "type": "string" }, "transport": { "$ref": "#/definitions/state.Transport" } } }, "documentservice.Signature": { "type": "object", "properties": { "count": { "type": "integer" }, "message": { "type": "string" } } }, "documentservice.SystemSpec": { "type": "object", "properties": { "screenshots": { "description": "Screenshots is \"enabled\" or \"disabled\".", "type": "string" }, "updates": { "description": "Updates mirrors the fleet's update window/policy (read-only here).", "allOf": [ { "$ref": "#/definitions/documentservice.UpdatesSpec" } ] }, "usbPolicy": { "description": "UsbPolicy is the device override (null = inherit the fleet's).", "allOf": [ { "$ref": "#/definitions/usbpolicy.Policy" } ] } } }, "documentservice.UpdatesSpec": { "type": "object", "properties": { "policy": { "$ref": "#/definitions/fleet.UpdatePolicy" }, "window": { "$ref": "#/definitions/fleet.UpdateWindow" } } }, "documentservice.ValidationError": { "type": "object", "properties": { "issues": { "type": "array", "items": { "$ref": "#/definitions/documentservice.FieldIssue" } } } }, "documentservice.Verdict": { "type": "object", "properties": { "healthScore": { "type": "number" }, "online": { "type": "boolean" }, "since": { "type": "string" }, "topIssue": { "description": "TopIssue is the code of the most severe issue (null when healthy).", "type": "string" }, "transitionAge": { "description": "TransitionAge is the age of the in-flight workload transition in\nseconds (null when none).", "type": "integer" }, "workloadState": { "type": "string" } } }, "documentservice.VersionRef": { "type": "object", "properties": { "latest": { "type": "boolean" }, "number": { "type": "integer" } } }, "documentservice.VersionSummary": { "type": "object", "properties": { "changeReason": { "type": "string" }, "changedBy": { "type": "string" }, "createdAt": { "type": "string" }, "version": { "type": "integer" } } }, "documentservice.WorkloadFrom": { "type": "object", "properties": { "configuration": { "type": "string" }, "pinned": { "description": "Pinned is true while a rollout admission pins this device to the\nversion above, ahead of its fleet. Read-only.", "type": "boolean" }, "version": { "$ref": "#/definitions/documentservice.VersionRef" } } }, "documentservice.WorkloadSpec": { "type": "object", "properties": { "expiresAt": { "description": "ExpiresAt clears Override automatically once passed.", "type": "string" }, "from": { "description": "From is derived from the fleet (read-only on the device document).", "allOf": [ { "$ref": "#/definitions/documentservice.WorkloadFrom" } ] }, "override": { "description": "Override is merged over the rendered configuration.", "allOf": [ { "$ref": "#/definitions/host.ConfigurationOverride" } ] } } }, "edgewireusagerepo.DailyTotals": { "type": "object", "properties": { "date": { "type": "string" }, "direct": { "type": "string" }, "nats": { "type": "string" }, "other": { "type": "string" }, "relay": { "type": "string" }, "totalBytes": { "type": "string" } } }, "edgewireusagerepo.PathTotals": { "type": "object", "properties": { "otherDirectionBytes": { "type": "string" }, "rxBytes": { "type": "string" }, "totalBytes": { "type": "string" }, "txBytes": { "type": "string" } } }, "edgewireusagerepo.Summary": { "type": "object", "properties": { "asOf": { "type": "string" }, "attribution": { "type": "string" }, "byPath": { "type": "object", "additionalProperties": { "$ref": "#/definitions/edgewireusagerepo.PathTotals" } }, "daily": { "description": "Daily has one row per UTC day from the day of From to the day of To.", "type": "array", "items": { "$ref": "#/definitions/edgewireusagerepo.DailyTotals" } }, "from": { "type": "string" }, "measurement": { "type": "string" }, "organisationId": { "type": "string" }, "pricingImplemented": { "type": "boolean" }, "signatureVerified": { "type": "boolean" }, "source": { "type": "string" }, "to": { "type": "string" }, "totalBytes": { "type": "string" } } }, "fleet.SecurityPolicy": { "type": "object", "properties": { "require_disk_encryption": { "type": "boolean" }, "require_recovery_key_escrow": { "type": "boolean" }, "require_secure_boot": { "type": "boolean" }, "require_tpm": { "type": "boolean" }, "updated_at": { "type": "string" } } }, "fleet.UpdatePolicy": { "type": "object", "properties": { "mode": { "$ref": "#/definitions/fleet.UpdatePolicyMode" }, "targets": { "type": "array", "items": { "$ref": "#/definitions/fleet.UpdateTarget" } }, "update_required": { "description": "UpdateRequired, when true, instructs devices to apply updates\nimmediately and ignore the maintenance window (OOTB/forced rollout).\nDefault false = respect the window (good UX, e.g. Canva Cast).", "type": "boolean" } } }, "fleet.UpdatePolicyMode": { "type": "string", "enum": [ "latest", "pinned" ], "x-enum-varnames": [ "UpdateModeLatest", "UpdateModePinned" ] }, "fleet.UpdateTarget": { "type": "object", "properties": { "architecture": { "type": "string" }, "board": { "type": "string" }, "initram_version_id": { "type": "string" }, "system_version_id": { "type": "string" } } }, "fleet.UpdateWindow": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "end_time": { "type": "string" }, "start_time": { "type": "string" }, "timezone": { "type": "string" } } }, "fleetservice.ComponentUniformity": { "type": "object", "properties": { "category": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "uniformity_percent": { "description": "UniformityPercent is the probability (0-100) that two devices picked\nat random from the analysed set carry an identical component.", "type": "number" }, "variants": { "type": "array", "items": { "$ref": "#/definitions/fleetservice.UniformityVariant" } } } }, "fleetservice.DuplicateFleetRequest": { "type": "object", "properties": { "copyConfiguration": { "description": "CopyConfiguration links the new fleet to the source's configuration\n(and pinned version). Absent = true. Devices are never copied.", "type": "boolean" }, "description": { "description": "Description of the new fleet; absent = the source's.", "type": "string" }, "name": { "description": "Name of the new fleet (1-100 characters).", "type": "string" } } }, "fleetservice.DuplicateFleetResult": { "type": "object", "properties": { "copied": { "type": "array", "items": { "type": "string" } }, "fleet": { "$ref": "#/definitions/fleetservice.DuplicatedFleet" }, "skipped": { "type": "array", "items": { "$ref": "#/definitions/fleetservice.SkippedField" } } } }, "fleetservice.DuplicatedFleet": { "type": "object", "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } } }, "fleetservice.FleetConfigDevices": { "type": "object", "properties": { "on_target": { "description": "OnTarget counts devices reporting the fleet's configuration and\nresolved version (devices admitted by a rollout run the rollout's).", "type": "integer" }, "online": { "type": "integer" }, "total": { "type": "integer" } } }, "fleetservice.FleetConfigurationHistory": { "type": "object", "properties": { "assigned_at": { "type": "string" }, "assigned_by": { "type": "string" }, "config_version": { "type": "integer" }, "configuration_id": { "type": "string" }, "fleet_id": { "type": "string" }, "reason": { "type": "string" } } }, "fleetservice.FleetConfigurationResponse": { "type": "object", "properties": { "active_rollouts": { "description": "ActiveRollouts are unfinished config rollouts on the fleet.", "type": "array", "items": { "$ref": "#/definitions/fleetservice.FleetRolloutRef" } }, "config_version": { "type": "integer" }, "configuration": { "$ref": "#/definitions/configuration.Configuration" }, "configuration_id": { "type": "string" }, "configuration_spec": { "$ref": "#/definitions/configuration.ConfigurationSpec" }, "devices": { "description": "Devices is what a configuration change reaches (omitted when the\ndevice count is unavailable).", "allOf": [ { "$ref": "#/definitions/fleetservice.FleetConfigDevices" } ] }, "fleet_id": { "type": "string" }, "is_pinned": { "type": "boolean" }, "updated_at": { "type": "string" } } }, "fleetservice.FleetRolloutRef": { "type": "object", "properties": { "config_version": { "type": "integer" }, "configuration_id": { "type": "string" }, "configuration_name": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "$ref": "#/definitions/rollout.RolloutStatus" } } }, "fleetservice.FleetUniformity": { "type": "object", "properties": { "analysed_count": { "type": "integer" }, "components": { "type": "array", "items": { "$ref": "#/definitions/fleetservice.ComponentUniformity" } }, "device_count": { "description": "DeviceCount is every device in the fleet; AnalysedCount is the subset\nthat has reported a hardware inventory.", "type": "integer" }, "fleet_id": { "type": "string" }, "hardware_percent": { "description": "HardwarePercent is the unweighted mean of the hardware components.\nNil when fewer than one device has reported (nothing to compare).", "type": "number" }, "software_percent": { "description": "SoftwarePercent scores system software versions (init, rootfs, kernel,\nmodules) separately: they converge through rollouts, hardware does not.", "type": "number" } } }, "fleetservice.SkippedField": { "type": "object", "properties": { "field": { "type": "string" }, "reason": { "type": "string" } } }, "fleetservice.UniformityVariant": { "type": "object", "properties": { "count": { "type": "integer" }, "device_ids": { "type": "array", "items": { "type": "string" } }, "device_ids_truncated": { "description": "DeviceIDsTruncated is true when DeviceIDs holds fewer than Count ids.", "type": "boolean" }, "percent": { "type": "number" }, "signature": { "type": "string" } } }, "github_com_qdynamicsco_admiral_src_domain_network.NetworkConfiguration": { "type": "object", "properties": { "bridges": { "description": "Virtual bridges", "type": "array", "items": { "$ref": "#/definitions/network.BridgeConfiguration" } }, "client_networks": { "description": "Global client networks (WiFi SSIDs to connect to)", "type": "array", "items": { "$ref": "#/definitions/network.ClientNetworkConfiguration" } }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "fleet_id": { "type": "string" }, "host_id": { "type": "string" }, "id": { "type": "string" }, "interfaces": { "description": "Hardware configuration", "type": "array", "items": { "$ref": "#/definitions/network.InterfaceConfiguration" } }, "nameservers": { "description": "Global DNS", "type": "array", "items": { "type": "string" } }, "organisation_id": { "type": "string" }, "scope": { "description": "\"fleet\" or \"device\"", "allOf": [ { "$ref": "#/definitions/network.NetworkConfigurationScope" } ] }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" }, "version": { "type": "integer" } } }, "github_com_qdynamicsco_admrl-core_api_network.NetworkConfiguration": { "type": "object", "properties": { "bridges": { "description": "3. Virtual Bridges", "type": "array", "items": { "$ref": "#/definitions/network.BridgeConfig" } }, "clientNetworks": { "description": "2. Global Client List: \"Connect to these if you see them\"\nAny Interface enabled with Type=Wifi \u0026 Mode=Client will use these.", "type": "array", "items": { "$ref": "#/definitions/network.ClientNetwork" } }, "interfaces": { "description": "1. Hardware Definition: \"Turn these things on/off and set modes\"", "type": "array", "items": { "$ref": "#/definitions/network.InterfaceConfig" } }, "nameservers": { "description": "4. Global DNS (Fallback)", "type": "array", "items": { "type": "string" } }, "updatedAt": { "type": "string" }, "version": { "type": "integer" } } }, "grant.SignedGrant": { "type": "object", "properties": { "grant": { "type": "array", "items": { "type": "integer" } }, "kid": { "type": "string" }, "sig_ed25519": { "type": "array", "items": { "type": "integer" } }, "sig_mldsa65": { "type": "array", "items": { "type": "integer" } } } }, "grant.TransportParams": { "type": "object", "properties": { "conn_win_max": { "type": "integer" }, "keepalive_ms": { "type": "integer" }, "max_idle_ms": { "type": "integer" }, "max_streams": { "type": "integer" }, "stream_win_init": { "type": "integer" }, "stream_win_max": { "type": "integer" } } }, "helpdesk.Diagnostics": { "type": "object", "properties": { "bundleId": { "type": "string" }, "reason": { "type": "string" }, "status": { "$ref": "#/definitions/helpdesk.DiagnosticsStatus" } } }, "helpdesk.DiagnosticsStatus": { "type": "string", "enum": [ "requested", "unavailable" ], "x-enum-varnames": [ "DiagnosticsRequested", "DiagnosticsUnavailable" ] }, "helpdesk.Priority": { "type": "integer", "enum": [ 0, 1, 2, 3 ], "x-enum-comments": { "PriorityUrgent": "Sev1 — fires PagerDuty" }, "x-enum-descriptions": [ "Sev1 — fires PagerDuty", "", "", "" ], "x-enum-varnames": [ "PriorityUrgent", "PriorityHigh", "PriorityNormal", "PriorityLow" ] }, "helpdesk.Status": { "type": "string", "enum": [ "TODO", "SNOOZED", "DONE" ], "x-enum-varnames": [ "StatusTodo", "StatusSnoozed", "StatusDone" ] }, "helpdesk.Subject": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "$ref": "#/definitions/helpdesk.SubjectType" } } }, "helpdesk.SubjectType": { "type": "string", "enum": [ "fleet", "configuration", "device" ], "x-enum-varnames": [ "SubjectFleet", "SubjectConfiguration", "SubjectDevice" ] }, "helpdesk.SupportType": { "type": "string", "enum": [ "BILLING", "TECHNICAL", "IMPLEMENTATION" ], "x-enum-varnames": [ "SupportTypeBilling", "SupportTypeTechnical", "SupportTypeImplementation" ] }, "host.ConfigurationOverride": { "type": "object", "properties": { "command": { "type": "array", "items": { "type": "string" } }, "desiredState": { "description": "DesiredState overrides the configuration's desired state for this device\n(\"RUNNING\" | \"STOPPED\"). Nil = inherit. Lets an operator stop one device's\nworkload without editing the fleet configuration (admrl override --set\ndesiredState=STOPPED, document spec.workload.override.desiredState).", "type": "string" }, "environment": { "type": "object", "additionalProperties": { "type": "string" } }, "image": { "type": "string" }, "mounts": { "type": "array", "items": { "$ref": "#/definitions/configuration.Mount" } }, "options": { "$ref": "#/definitions/host.OptionsOverride" }, "ports": { "type": "array", "items": { "$ref": "#/definitions/configuration.Port" } }, "registry_credential_id": { "type": "string" }, "volumes": { "type": "object", "additionalProperties": { "$ref": "#/definitions/configuration.VolumeMount" } } } }, "host.EdgeWireTarget": { "type": "object", "properties": { "address": { "type": "string" }, "allow_lan": { "description": "AllowLAN permits a non-loopback address.", "type": "boolean" }, "id": { "type": "string" }, "kind": { "description": "tcp|udp|unix", "type": "string" } } }, "host.ImageCleaningOverride": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "interval_hours": { "type": "integer" }, "max_age_days": { "type": "integer" }, "prune_dangling": { "type": "boolean" }, "prune_on_update": { "type": "boolean" }, "retention_count": { "type": "integer" } } }, "host.OptionsOverride": { "type": "object", "properties": { "all_devices_allowed": { "type": "boolean" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "cgroup": { "type": "string" }, "devices": { "type": "array", "items": { "type": "string" } }, "disableHostBluetooth": { "type": "boolean" }, "ephemeral_root": { "type": "boolean" }, "exposeDBus": { "type": "boolean" }, "host_hosts_file": { "type": "boolean" }, "host_namespaces": { "type": "array", "items": { "type": "string" } }, "host_resolvconf": { "type": "boolean" }, "image_cleaning": { "$ref": "#/definitions/host.ImageCleaningOverride" }, "masked_paths": { "type": "array", "items": { "type": "string" } }, "new_privileges": { "type": "boolean" }, "parent_cgroup_devices": { "type": "boolean" }, "privileged": { "type": "boolean" }, "read_only_root": { "type": "boolean" }, "readonly_paths": { "type": "array", "items": { "type": "string" } }, "tty": { "type": "boolean" } } }, "hostservice.DeletedResult": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "reason": { "type": "string" } } }, "hostservice.HostConfigurationResponse": { "type": "object", "properties": { "base_config": { "$ref": "#/definitions/configuration.ConfigurationSpec" }, "config_version": { "type": "integer" }, "configuration_id": { "type": "string" }, "configuration_info": { "$ref": "#/definitions/configuration.Configuration" }, "configuration_override": { "$ref": "#/definitions/host.ConfigurationOverride" }, "fleet_id": { "type": "string" }, "has_override": { "type": "boolean" }, "host_id": { "type": "string" }, "host_override": { "$ref": "#/definitions/host.ConfigurationOverride" }, "host_version": { "type": "integer" }, "is_pinned": { "type": "boolean" }, "merged_config": { "$ref": "#/definitions/configuration.ConfigurationSpec" }, "overridden_paths": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string" } } }, "iam.AssignmentView": { "type": "object", "properties": { "assigned_at": { "type": "string" }, "assigned_by": { "type": "string" }, "assigned_by_display": { "type": "string" }, "id": { "type": "string" }, "profile_id": { "type": "string" }, "profile_name": { "type": "string" }, "role_id": { "type": "string" }, "role_name": { "type": "string" }, "scope": { "$ref": "#/definitions/iam.Scope" }, "skipped": { "type": "array", "items": { "$ref": "#/definitions/iam.SkippedCapability" } }, "subject": { "$ref": "#/definitions/iam.Subject" }, "system": { "description": "System is true for rows synthesized from structural FGA tuples (the\nzero-migration built-in roles). Such rows have no stored assignment.", "type": "boolean" } } }, "iam.CapabilitiesCatalogueResponse": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "$ref": "#/definitions/iam.Capability" } }, "groups": { "type": "array", "items": { "$ref": "#/definitions/iam.CapabilityGroup" } } } }, "iam.Capability": { "type": "object", "properties": { "description": { "type": "string" }, "group": { "type": "string" }, "id": { "type": "string" }, "implies": { "type": "array", "items": { "type": "string" } }, "label": { "type": "string" }, "risk": { "description": "\"low\", \"medium\", \"high\", \"critical\"", "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "iam.CapabilityGroup": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } } }, "iam.CreateAssignmentRequest": { "type": "object", "properties": { "profile_id": { "type": "string" }, "role_id": { "type": "string" }, "scope": { "$ref": "#/definitions/iam.Scope" }, "subject": { "$ref": "#/definitions/iam.Subject" } } }, "iam.CreateProfileRequest": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "name": { "type": "string" } } }, "iam.DuplicateProfileRequest": { "type": "object", "properties": { "name": { "type": "string" } } }, "iam.MyCapabilitiesResponse": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "string" } }, "is_admin": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "scope": { "$ref": "#/definitions/iam.Scope" } } }, "iam.ProfileView": { "type": "object", "properties": { "assignment_count": { "type": "integer" }, "builtin": { "type": "boolean" }, "builtin_key": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "created_by_display": { "type": "string" }, "description": { "type": "string" }, "effective_capabilities": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "name": { "type": "string" }, "updated_at": { "type": "string" } } }, "iam.Scope": { "type": "object", "properties": { "display": { "description": "NEW", "type": "string" }, "id": { "type": "string" }, "type": { "type": "string" } } }, "iam.SkippedCapability": { "type": "object", "properties": { "capability": { "type": "string" }, "reason": { "description": "\"organisation_only\", \"cannot_delegate\", \"cross_tenant\", \"not_grantable\"", "type": "string" } } }, "iam.Subject": { "type": "object", "properties": { "display": { "type": "string" }, "id": { "type": "string" }, "kind": { "$ref": "#/definitions/iam.SubjectKind" } } }, "iam.SubjectKind": { "type": "string", "enum": [ "user", "service_account", "group" ], "x-enum-varnames": [ "SubjectKindUser", "SubjectKindServiceAccount", "SubjectKindGroup" ] }, "iam.UpdateProfileRequest": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "name": { "type": "string" } } }, "imageproxyadminservice.FleetOverview": { "type": "object", "properties": { "bytes": { "type": "integer" }, "enabled": { "type": "boolean" }, "enabled_at": { "type": "string" }, "fleet_id": { "type": "string" }, "name": { "type": "string" }, "requests": { "type": "integer" } } }, "imageproxyadminservice.OrgOverview": { "type": "object", "properties": { "daily": { "type": "array", "items": { "$ref": "#/definitions/imageproxyusagerepo.DayUsage" } }, "enabled_fleets": { "type": "integer" }, "fleets": { "type": "array", "items": { "$ref": "#/definitions/imageproxyadminservice.FleetOverview" } }, "period_end": { "type": "string" }, "period_start": { "type": "string" }, "totals": { "$ref": "#/definitions/imageproxyusagerepo.Totals" } } }, "imageproxyusagerepo.DayUsage": { "type": "object", "properties": { "bytes": { "type": "integer" }, "day": { "type": "string" }, "requests": { "type": "integer" } } }, "imageproxyusagerepo.DeviceUsage": { "type": "object", "properties": { "bytes": { "type": "integer" }, "device_id": { "type": "string" }, "requests": { "type": "integer" } } }, "imageproxyusagerepo.Totals": { "type": "object", "properties": { "bytes": { "type": "integer" }, "cache_bytes": { "type": "integer" }, "devices": { "type": "integer" }, "requests": { "type": "integer" } } }, "mcpauthservice.RegisterRequest": { "type": "object", "properties": { "client_name": { "type": "string" }, "client_uri": { "type": "string" }, "grant_types": { "type": "array", "items": { "type": "string" } }, "logo_uri": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "response_types": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_method": { "type": "string" } } }, "mcpauthservice.TokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "scope": { "type": "string" }, "token_type": { "type": "string" } } }, "memtest.Capabilities": { "type": "object", "properties": { "edac": { "type": "boolean" }, "kernelMemtest": { "type": "boolean" }, "offline": { "type": "boolean" }, "offlineReason": { "description": "why Offline is false", "type": "string" }, "online": { "type": "boolean" }, "pagemap": { "type": "boolean" }, "softOffline": { "type": "boolean" } } }, "memtest.Health": { "type": "object", "properties": { "capabilities": { "$ref": "#/definitions/memtest.Capabilities" }, "edacCorrected": { "description": "-1 = not available", "type": "integer" }, "edacUncorrected": { "description": "-1 = not available", "type": "integer" }, "fault": { "type": "boolean" }, "faultReason": { "type": "string" }, "hardwareCorruptedBytes": { "type": "integer" }, "interrupted": { "$ref": "#/definitions/memtest.Interrupted" }, "kernel": { "description": "early memtest results found in this boot's kmsg", "allOf": [ { "$ref": "#/definitions/memtest.KernelSweep" } ] }, "kmsgHits": { "description": "recent memory-error kmsg lines, max 32", "type": "array", "items": { "type": "string" } }, "lastResult": { "description": "newest, Errors trimmed to 16", "allOf": [ { "$ref": "#/definitions/memtest.Result" } ] }, "retiredApplied": { "description": "applied this boot", "type": "integer" }, "retiredPages": { "type": "array", "items": { "type": "integer" } } } }, "memtest.Impact": { "type": "string", "enum": [ "running", "stopped" ], "x-enum-varnames": [ "ImpactRunning", "ImpactStopped" ] }, "memtest.Interrupted": { "type": "object", "properties": { "at": { "type": "string" }, "pass": { "type": "integer" }, "pattern": { "type": "string" }, "phase": { "$ref": "#/definitions/memtest.Phase" }, "runId": { "type": "string" } } }, "memtest.KernelSweep": { "type": "object", "properties": { "badRanges": { "type": "array", "items": { "$ref": "#/definitions/memtest.Range" } }, "passes": { "type": "integer" }, "ran": { "type": "boolean" }, "raw": { "description": "matching kmsg lines, max 32", "type": "array", "items": { "type": "string" } }, "sweptBytes": { "description": "SweptBytes is the physical memory the kernel sweep covered (sum of\nthe distinct ranges it reported for its first pattern); 0 = unknown.", "type": "integer" } } }, "memtest.MemError": { "type": "object", "properties": { "actual": { "type": "integer" }, "at": { "type": "string" }, "confirmed": { "type": "boolean" }, "expected": { "type": "integer" }, "mask": { "description": "Expected ^ Actual", "type": "integer" }, "pass": { "type": "integer" }, "pattern": { "type": "string" }, "physAddr": { "type": "integer" }, "tempMilliC": { "type": "integer" } } }, "memtest.MemoryHardware": { "type": "object", "properties": { "boardModel": { "type": "string" }, "boardSerial": { "type": "string" }, "boardVendor": { "type": "string" }, "cpuModel": { "type": "string" }, "firmwareInfo": { "description": "BIOS vendor/version/date", "type": "string" }, "modules": { "type": "array", "items": { "$ref": "#/definitions/memtest.MemoryModule" } }, "soldered": { "description": "RAM is not a replaceable module", "type": "boolean" }, "source": { "description": "\"smbios\" | \"devicetree\" | \"\"", "type": "string" } } }, "memtest.MemoryModule": { "type": "object", "properties": { "bank": { "type": "string" }, "dataWidth": { "type": "integer" }, "locator": { "type": "string" }, "manufacturer": { "type": "string" }, "partNumber": { "type": "string" }, "ranges": { "description": "physical address ranges, when firmware reports them", "type": "array", "items": { "$ref": "#/definitions/memtest.Range" } }, "serial": { "type": "string" }, "sizeBytes": { "type": "integer" }, "speedMTs": { "type": "integer" }, "type": { "description": "DDR4, LPDDR5 ...", "type": "string" } } }, "memtest.Outcome": { "type": "string", "enum": [ "pass", "fail", "cancelled", "interrupted", "error" ], "x-enum-varnames": [ "OutcomePass", "OutcomeFail", "OutcomeCancelled", "OutcomeInterrupted", "OutcomeError" ] }, "memtest.PageSummary": { "type": "object", "properties": { "confirmed": { "type": "boolean" }, "errors": { "description": "mismatches on this page", "type": "integer" }, "firstAt": { "type": "string" }, "lastAt": { "type": "string" }, "mask": { "description": "OR of every Expected^Actual on the page", "type": "integer" }, "maxTempMilliC": { "type": "integer" }, "minTempMilliC": { "type": "integer" }, "module": { "description": "MemoryModule.Locator when the address maps to one", "type": "string" }, "page": { "description": "physical page address (page-aligned)", "type": "integer" }, "passes": { "description": "1-based passes that saw an error here", "type": "array", "items": { "type": "integer" } }, "patterns": { "type": "array", "items": { "type": "string" } }, "retired": { "type": "boolean" }, "words": { "description": "distinct 64-bit words that failed", "type": "integer" } } }, "memtest.Phase": { "type": "string", "enum": [ "idle", "preparing", "stopping_workload", "rebooting", "kernel_sweep", "testing", "confirming", "retiring", "restoring", "done", "failed", "cancelled", "interrupted" ], "x-enum-varnames": [ "PhaseIdle", "PhasePreparing", "PhaseStoppingWorkload", "PhaseRebooting", "PhaseKernelSweep", "PhaseTesting", "PhaseConfirming", "PhaseRetiring", "PhaseRestoring", "PhaseDone", "PhaseFailed", "PhaseCancelled", "PhaseInterrupted" ] }, "memtest.Placement": { "type": "string", "enum": [ "online", "offline" ], "x-enum-varnames": [ "PlacementOnline", "PlacementOffline" ] }, "memtest.Plan": { "type": "object", "properties": { "bitFade": { "description": "nil = default (true for stopped/offline, false otherwise)", "type": "boolean" }, "holdOnFailure": { "description": "offline only: stay in maintenance (workload held) if the test fails", "type": "boolean" }, "impact": { "description": "workload impact: running or stopped", "allOf": [ { "$ref": "#/definitions/memtest.Impact" } ] }, "kernelPasses": { "description": "offline only; 0 = board default 4; clamp 1..17 (kernel memtest= value)", "type": "integer" }, "maxBytes": { "description": "optional cap in bytes, 0 = mode default", "type": "integer" }, "passes": { "description": "0 = default (running 1, stopped 2, offline 2); clamp 1..20", "type": "integer" }, "placement": { "description": "online or offline", "allOf": [ { "$ref": "#/definitions/memtest.Placement" } ] }, "quick": { "description": "preset of online+running: min(25% MemAvailable, 512 MiB), 1 pass, no bit-fade", "type": "boolean" }, "timeBudget": { "description": "seconds; 0 = default 7200; clamp 60..43200", "type": "integer" } } }, "memtest.Range": { "type": "object", "properties": { "end": { "type": "integer" }, "start": { "type": "integer" } } }, "memtest.Result": { "type": "object", "properties": { "agentVersion": { "type": "string" }, "coverageBytes": { "type": "integer" }, "deviceId": { "type": "string" }, "errorCount": { "description": "total, including beyond the cap", "type": "integer" }, "errors": { "description": "capped at 256", "type": "array", "items": { "$ref": "#/definitions/memtest.MemError" } }, "fault": { "type": "boolean" }, "finishedAt": { "type": "string" }, "hardware": { "$ref": "#/definitions/memtest.MemoryHardware" }, "interrupted": { "description": "set when the outcome is interrupted", "allOf": [ { "$ref": "#/definitions/memtest.Interrupted" } ] }, "kernel": { "$ref": "#/definitions/memtest.KernelSweep" }, "kernelVersion": { "type": "string" }, "maxTempMilliC": { "type": "integer" }, "osVersion": { "type": "string" }, "outcome": { "$ref": "#/definitions/memtest.Outcome" }, "pages": { "description": "Report evidence (additive). Pages summarises EVERY mismatch per\nphysical page (Errors keeps only the first 256 raw rows), capped at\nMaxResultPages pages with PagesTruncated set beyond that.", "type": "array", "items": { "$ref": "#/definitions/memtest.PageSummary" } }, "pagesTruncated": { "type": "boolean" }, "passesCompleted": { "type": "integer" }, "patternsRun": { "type": "array", "items": { "type": "string" } }, "plan": { "$ref": "#/definitions/memtest.Plan" }, "requester": { "type": "string" }, "retired": { "description": "physical page addresses retired by this run", "type": "array", "items": { "type": "integer" } }, "runId": { "type": "string" }, "source": { "$ref": "#/definitions/memtest.Source" }, "startedAt": { "type": "string" }, "summary": { "type": "string" }, "testedBytes": { "type": "integer" }, "totalBytes": { "type": "integer" }, "verdict": { "$ref": "#/definitions/memtest.Verdict" } } }, "memtest.Source": { "type": "string", "enum": [ "console", "remote" ], "x-enum-varnames": [ "SourceConsole", "SourceRemote" ] }, "memtest.Status": { "type": "object", "properties": { "confirmedErrors": { "type": "integer" }, "coverageBytes": { "description": "distinct physical bytes covered (pagemap) this run", "type": "integer" }, "errors": { "description": "raw mismatches seen", "type": "integer" }, "etaSeconds": { "type": "integer" }, "message": { "type": "string" }, "pass": { "type": "integer" }, "passes": { "type": "integer" }, "pattern": { "type": "string" }, "patternCount": { "type": "integer" }, "patternIndex": { "type": "integer" }, "phase": { "$ref": "#/definitions/memtest.Phase" }, "plan": { "$ref": "#/definitions/memtest.Plan" }, "rateBps": { "type": "integer" }, "runId": { "type": "string" }, "source": { "$ref": "#/definitions/memtest.Source" }, "startedAt": { "type": "string" }, "targetBytes": { "description": "this pass", "type": "integer" }, "tempMilliC": { "description": "hottest thermal zone now; 0 = unknown", "type": "integer" }, "testedBytes": { "description": "this pass", "type": "integer" }, "totalBytes": { "description": "MemTotal", "type": "integer" }, "updatedAt": { "type": "string" } } }, "memtest.Verdict": { "type": "string", "enum": [ "ok", "weak_cells", "data_line", "address_line", "thermal", "unknown" ], "x-enum-varnames": [ "VerdictOK", "VerdictWeakCells", "VerdictDataLine", "VerdictAddressLine", "VerdictThermal", "VerdictUnknown" ] }, "memtestreport.Analysis": { "type": "object", "properties": { "bitHistogram": { "type": "array", "items": { "$ref": "#/definitions/memtestreport.BitCount" } }, "byModule": { "type": "array", "items": { "$ref": "#/definitions/memtestreport.ModuleCount" } }, "byPattern": { "type": "array", "items": { "$ref": "#/definitions/memtestreport.PatternCount" } }, "byTemperature": { "type": "array", "items": { "$ref": "#/definitions/memtestreport.TemperatureCount" } }, "byteLanes": { "type": "array", "items": { "$ref": "#/definitions/memtestreport.LaneCount" } }, "cacheLineRuns": { "description": "CacheLineRuns counts runs of consecutive failing 8-byte words (raw rows)\nthat cover at least one whole 64-byte-aligned cache line.", "type": "integer" }, "confirmedErrors": { "type": "integer" }, "confirmedPages": { "type": "integer" }, "distinctPages": { "type": "integer" }, "distinctWords": { "type": "integer" }, "errorCount": { "type": "integer" }, "headline": { "type": "string" }, "intermittent": { "description": "Intermittent: errors were seen but none reproduced on re-test.", "type": "boolean" }, "laneConcentration": { "description": "LaneConcentration is set when one byte lane holds at least 90% of the\nfailing bits (weighted by errors).", "allOf": [ { "$ref": "#/definitions/memtestreport.LaneConcentration" } ] }, "notes": { "type": "array", "items": { "type": "string" } }, "pagesTruncated": { "type": "boolean" }, "ranges": { "type": "array", "items": { "$ref": "#/definitions/memtestreport.RangeSummary" } }, "recommendation": { "type": "string" }, "recurrence": { "$ref": "#/definitions/memtestreport.Recurrence" }, "retiredPages": { "type": "integer" }, "topPages": { "type": "array", "items": { "$ref": "#/definitions/memtest.PageSummary" } }, "verdictText": { "type": "string" } } }, "memtestreport.BitCount": { "type": "object", "properties": { "bit": { "type": "integer" }, "count": { "type": "integer" } } }, "memtestreport.IDName": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "memtestreport.LaneConcentration": { "type": "object", "properties": { "lane": { "type": "integer" }, "share": { "description": "0..1, four decimals", "type": "number" } } }, "memtestreport.LaneCount": { "type": "object", "properties": { "count": { "type": "integer" }, "lane": { "type": "integer" } } }, "memtestreport.ModuleCount": { "type": "object", "properties": { "count": { "type": "integer" }, "module": { "type": "string" }, "pages": { "type": "integer" } } }, "memtestreport.PatternCount": { "type": "object", "properties": { "count": { "type": "integer" }, "label": { "type": "string" }, "pattern": { "type": "string" } } }, "memtestreport.RangeSummary": { "type": "object", "properties": { "end": { "type": "integer" }, "errors": { "type": "integer" }, "pages": { "type": "integer" }, "start": { "type": "integer" } } }, "memtestreport.Recurrence": { "type": "object", "properties": { "pagesBothPasses": { "type": "integer" }, "pagesOnePass": { "type": "integer" } } }, "memtestreport.Report": { "type": "object", "properties": { "analysis": { "$ref": "#/definitions/memtestreport.Analysis" }, "device": { "$ref": "#/definitions/memtestreport.ReportDevice" }, "evidenceSha256": { "type": "string" }, "generatedAt": { "type": "string" }, "organisation": { "$ref": "#/definitions/memtestreport.IDName" }, "reportId": { "type": "string" }, "result": { "$ref": "#/definitions/memtest.Result" } } }, "memtestreport.ReportDevice": { "type": "object", "properties": { "fleet": { "$ref": "#/definitions/memtestreport.IDName" }, "hardware": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } } }, "memtestreport.TemperatureCount": { "type": "object", "properties": { "band": { "type": "string" }, "count": { "type": "integer" } } }, "network.AccessPointConfig": { "type": "object", "properties": { "channel": { "description": "0 = auto", "type": "integer" }, "hidden": { "type": "boolean" }, "ip": { "description": "The Gateway IP for the AP", "allOf": [ { "$ref": "#/definitions/network.IPSettings" } ] }, "psk": { "type": "string" }, "security": { "description": "\"psk\", \"none\"", "type": "string" }, "ssid": { "type": "string" } } }, "network.AccessPointConfiguration": { "type": "object", "properties": { "channel": { "type": "integer" }, "hidden": { "type": "boolean" }, "ip": { "description": "Gateway IP for the AP", "allOf": [ { "$ref": "#/definitions/network.IPSettingsConfiguration" } ] }, "security": { "description": "\"psk\", \"none\"", "type": "string" }, "ssid": { "type": "string" } } }, "network.AddressStatus": { "type": "object", "properties": { "address": { "type": "string" }, "version": { "description": "v4/v6", "type": "string" } } }, "network.BridgeConfig": { "type": "object", "properties": { "ip": { "$ref": "#/definitions/network.IPSettings" }, "memberMacs": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" } } }, "network.BridgeConfiguration": { "type": "object", "properties": { "ip": { "$ref": "#/definitions/network.IPSettingsConfiguration" }, "member_macs": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" } } }, "network.ClientNetwork": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "interfaceMac": { "description": "Optional: Lock this network to a specific interface if really needed.\nIf empty, any available Wifi interface can use it.", "type": "string" }, "ip": { "description": "How to behave once connected (DHCP vs Static)", "allOf": [ { "$ref": "#/definitions/network.IPSettings" } ] }, "priority": { "description": "Auto-connect order", "type": "integer" }, "psk": { "type": "string" }, "ssid": { "type": "string" } } }, "network.ClientNetworkConfiguration": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "interface_mac": { "description": "Optional: Lock to specific interface", "type": "string" }, "ip": { "description": "IP configuration for this network", "allOf": [ { "$ref": "#/definitions/network.IPSettingsConfiguration" } ] }, "priority": { "type": "integer" }, "ssid": { "type": "string" } } }, "network.EthernetConfig": { "type": "object", "properties": { "ip": { "description": "Ethernet is physically bound, so IP config usually lives here.", "allOf": [ { "$ref": "#/definitions/network.IPSettings" } ] } } }, "network.EthernetConfiguration": { "type": "object", "properties": { "ip": { "$ref": "#/definitions/network.IPSettingsConfiguration" } } }, "network.IPConfig": { "type": "object", "properties": { "address": { "description": "192.168.1.5/24", "type": "string" }, "dns": { "type": "array", "items": { "type": "string" } }, "gateway": { "type": "string" } } }, "network.IPConfiguration": { "type": "object", "properties": { "address": { "type": "string" }, "dns": { "type": "array", "items": { "type": "string" } }, "gateway": { "type": "string" } } }, "network.IPSettings": { "type": "object", "properties": { "dhcpV4": { "type": "boolean" }, "ipv4": { "$ref": "#/definitions/network.IPConfig" }, "ipv6": { "$ref": "#/definitions/network.IPConfig" }, "proxy": { "$ref": "#/definitions/network.ProxyConfig" } } }, "network.IPSettingsConfiguration": { "type": "object", "properties": { "dhcp_v4": { "type": "boolean" }, "ipv4": { "$ref": "#/definitions/network.IPConfiguration" }, "ipv6": { "$ref": "#/definitions/network.IPConfiguration" }, "proxy": { "$ref": "#/definitions/network.ProxyConfiguration" } } }, "network.InterfaceConfig": { "type": "object", "properties": { "enabled": { "description": "Power state", "type": "boolean" }, "ethernet": { "$ref": "#/definitions/network.EthernetConfig" }, "matchMac": { "type": "string" }, "type": { "description": "Type specific configurations", "type": "string" }, "wifi": { "$ref": "#/definitions/network.WifiDevice" } } }, "network.InterfaceConfiguration": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "ethernet": { "$ref": "#/definitions/network.EthernetConfiguration" }, "match_mac": { "type": "string" }, "type": { "description": "\"ethernet\", \"wifi\", \"modem\"", "type": "string" }, "wifi": { "description": "Type-specific configurations", "allOf": [ { "$ref": "#/definitions/network.WifiDeviceConfiguration" } ] } } }, "network.InterfaceStatus": { "type": "object", "properties": { "apState": { "description": "If running as AP:", "allOf": [ { "$ref": "#/definitions/network.WifiStatus" } ] }, "clientState": { "description": "If connected as a Client:", "allOf": [ { "$ref": "#/definitions/network.WifiStatus" } ] }, "ips": { "type": "array", "items": { "$ref": "#/definitions/network.AddressStatus" } }, "mac": { "type": "string" }, "name": { "type": "string" }, "state": { "description": "UP, DOWN", "type": "string" }, "type": { "type": "string" } } }, "network.NetworkConfigurationScope": { "type": "string", "enum": [ "fleet", "device" ], "x-enum-varnames": [ "ScopeFleet", "ScopeDevice" ] }, "network.NetworkStatus": { "type": "object", "properties": { "error": { "type": "string" }, "interfaces": { "type": "array", "items": { "$ref": "#/definitions/network.InterfaceStatus" } }, "reportedAt": { "type": "string" } } }, "network.ProxyConfig": { "type": "object", "properties": { "ignoreTls": { "type": "boolean" }, "server": { "type": "string" } } }, "network.ProxyConfiguration": { "type": "object", "properties": { "ignore_tls": { "type": "boolean" }, "server": { "type": "string" } } }, "network.WifiDevice": { "type": "object", "properties": { "accessPoint": { "description": "If Mode == \"ap\", this configuration is required.\n(AP mode is hardware-bound, unlike Client mode)", "allOf": [ { "$ref": "#/definitions/network.AccessPointConfig" } ] }, "country": { "description": "Regulatory domain", "type": "string" }, "mode": { "description": "\"client\" (station) or \"ap\" (access point)", "type": "string" }, "powersave": { "description": "Enable power management?", "type": "boolean" } } }, "network.WifiDeviceConfiguration": { "type": "object", "properties": { "access_point": { "description": "If Mode == \"ap\", this is required", "allOf": [ { "$ref": "#/definitions/network.AccessPointConfiguration" } ] }, "country_code": { "type": "string" }, "mode": { "description": "\"client\" (station) or \"ap\" (access point)", "type": "string" }, "powersave": { "type": "boolean" } } }, "network.WifiStatus": { "type": "object", "properties": { "channel": { "type": "integer" }, "rssi": { "type": "integer" }, "ssid": { "type": "string" } } }, "networkservice.AccessPointInput": { "type": "object", "properties": { "channel": { "type": "integer" }, "hidden": { "type": "boolean" }, "ip": { "$ref": "#/definitions/networkservice.IPSettingsInput" }, "psk": { "description": "Plain text - will be encrypted", "type": "string" }, "security": { "type": "string" }, "ssid": { "type": "string" } } }, "networkservice.BridgeInput": { "type": "object", "properties": { "ip": { "$ref": "#/definitions/networkservice.IPSettingsInput" }, "member_macs": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" } } }, "networkservice.ClientNetworkInput": { "type": "object", "properties": { "hidden": { "type": "boolean" }, "interface_mac": { "type": "string" }, "ip": { "$ref": "#/definitions/networkservice.IPSettingsInput" }, "priority": { "type": "integer" }, "psk": { "description": "Plain text - will be encrypted", "type": "string" }, "ssid": { "type": "string" } } }, "networkservice.EthernetInput": { "type": "object", "properties": { "ip": { "$ref": "#/definitions/networkservice.IPSettingsInput" } } }, "networkservice.IPInput": { "type": "object", "properties": { "address": { "type": "string" }, "dns": { "type": "array", "items": { "type": "string" } }, "gateway": { "type": "string" } } }, "networkservice.IPSettingsInput": { "type": "object", "properties": { "dhcp_v4": { "type": "boolean" }, "ipv4": { "$ref": "#/definitions/networkservice.IPInput" }, "ipv6": { "$ref": "#/definitions/networkservice.IPInput" }, "proxy": { "$ref": "#/definitions/networkservice.ProxyInput" } } }, "networkservice.InterfaceInput": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "ethernet": { "$ref": "#/definitions/networkservice.EthernetInput" }, "match_mac": { "type": "string" }, "type": { "type": "string" }, "wifi": { "$ref": "#/definitions/networkservice.WifiDeviceInput" } } }, "networkservice.NetworkConfigurationInput": { "type": "object", "properties": { "bridges": { "type": "array", "items": { "$ref": "#/definitions/networkservice.BridgeInput" } }, "client_networks": { "type": "array", "items": { "$ref": "#/definitions/networkservice.ClientNetworkInput" } }, "interfaces": { "type": "array", "items": { "$ref": "#/definitions/networkservice.InterfaceInput" } }, "nameservers": { "type": "array", "items": { "type": "string" } } } }, "networkservice.ProxyInput": { "type": "object", "properties": { "ignore_tls": { "type": "boolean" }, "server": { "type": "string" } } }, "networkservice.WifiDeviceInput": { "type": "object", "properties": { "access_point": { "$ref": "#/definitions/networkservice.AccessPointInput" }, "country_code": { "type": "string" }, "mode": { "type": "string" }, "powersave": { "type": "boolean" } } }, "networkverdict.Verdict": { "type": "object", "properties": { "cause": { "description": "Cause is a short human sentence naming the likely fault location.", "type": "string" }, "code": { "description": "Code is a stable identifier for Cause (local_link, upstream, ...).", "type": "string" }, "confidence": { "description": "Confidence is high, medium or low.", "type": "string" }, "evidence": { "description": "Evidence lists the probe items that support Cause.", "type": "array", "items": { "type": "string" } } } }, "notification.Notification": { "type": "object", "properties": { "action_text": { "type": "string" }, "action_url": { "type": "string" }, "archived_at": { "type": "string" }, "created_at": { "description": "Timestamps", "type": "string" }, "entity_id": { "description": "Related entity UUID", "type": "string" }, "entity_name": { "description": "Cached entity name", "type": "string" }, "entity_type": { "description": "Related entity information", "type": "string" }, "expires_at": { "type": "string" }, "group_key": { "description": "Grouping (for collapsing similar notifications)", "type": "string" }, "id": { "type": "string" }, "message": { "type": "string" }, "metadata": { "description": "Metadata", "type": "object", "additionalProperties": true }, "organization_id": { "description": "Organization context", "type": "string" }, "priority": { "$ref": "#/definitions/notification.NotificationPriority" }, "read_at": { "type": "string" }, "recipient_id": { "description": "Recipient information", "type": "string" }, "recipient_type": { "description": "\"user\", \"group\", \"organization\"", "type": "string" }, "status": { "$ref": "#/definitions/notification.NotificationStatus" }, "title": { "description": "Content", "type": "string" }, "type": { "$ref": "#/definitions/notification.NotificationType" } } }, "notification.NotificationPriority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ], "x-enum-varnames": [ "PriorityLow", "PriorityMedium", "PriorityHigh", "PriorityCritical" ] }, "notification.NotificationStats": { "type": "object", "properties": { "critical_count": { "type": "integer" }, "high_count": { "type": "integer" }, "total_count": { "type": "integer" }, "unread_count": { "type": "integer" } } }, "notification.NotificationStatus": { "type": "string", "enum": [ "unread", "read", "archived", "dismissed" ], "x-enum-varnames": [ "StatusUnread", "StatusRead", "StatusArchived", "StatusDismissed" ] }, "notification.NotificationType": { "type": "string", "enum": [ "device_offline", "device_online", "device_health_alert", "device_claimed", "fleet_created", "fleet_updated", "fleet_health_change", "rollout_started", "rollout_completed", "rollout_failed", "rollout_paused", "user_invited", "user_added_to_group", "permission_granted", "system_alert", "maintenance_window", "support_reply" ], "x-enum-varnames": [ "NotificationTypeDeviceOffline", "NotificationTypeDeviceOnline", "NotificationTypeDeviceHealthAlert", "NotificationTypeDeviceClaimed", "NotificationTypeFleetCreated", "NotificationTypeFleetUpdated", "NotificationTypeFleetHealthChange", "NotificationTypeRolloutStarted", "NotificationTypeRolloutCompleted", "NotificationTypeRolloutFailed", "NotificationTypeRolloutPaused", "NotificationTypeUserInvited", "NotificationTypeUserAddedToGroup", "NotificationTypePermissionGranted", "NotificationTypeSystemAlert", "NotificationTypeMaintenanceWindow", "NotificationTypeSupportReply" ] }, "provisioning.FlexibleBSONTag": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "provisioning.ProvisioningProfile": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2024-01-01T00:00:00Z" }, "created_by": { "type": "string", "example": "user-789" }, "description": { "type": "string", "example": "Profile for production devices" }, "enabled": { "type": "boolean", "example": true }, "expires_at": { "type": "string" }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "Production Profile" }, "organisation_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "tags": { "type": "array", "items": { "$ref": "#/definitions/provisioning.FlexibleBSONTag" } }, "target_fleet_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "updated_at": { "type": "string", "example": "2024-01-15T12:30:00Z" } } }, "registrycredential.CredentialType": { "type": "string", "enum": [ "basic", "aws_ecr" ], "x-enum-varnames": [ "CredentialTypeBasic", "CredentialTypeAWSECR" ] }, "registrycredential.RegistryCredential": { "type": "object", "properties": { "aws_access_key_id": { "type": "string" }, "aws_region": { "description": "--- AWS ECR auth ---\nRegion and AccessKeyID are not secrets; safe to surface to UIs.", "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "description": { "type": "string" }, "has_auth": { "type": "boolean" }, "has_aws_secret_access_key": { "type": "boolean" }, "has_aws_session_token": { "type": "boolean" }, "has_identity_token": { "type": "boolean" }, "has_password": { "type": "boolean" }, "has_registry_token": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "organisation_id": { "type": "string" }, "registry": { "type": "string" }, "type": { "$ref": "#/definitions/registrycredential.CredentialType" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" }, "username": { "description": "--- Basic (docker-style) auth ---", "type": "string" } } }, "rollout.ComponentUpdateStatus": { "type": "object", "properties": { "component": { "type": "string" }, "current_version": { "type": "string" }, "error_message": { "type": "string" }, "from_version": { "type": "string" }, "status": { "description": "pending | downloading | installed | verified | failed", "type": "string" }, "target_version": { "type": "string" } } }, "rollout.Counts": { "type": "object", "properties": { "admitted": { "type": "integer" }, "converged": { "type": "integer" }, "dropped": { "description": "Dropped counts targets that left the rollout's fleets; completion\nneeds converged == targets - dropped (plus, for offline-goal runs,\nthe never-admitted offline targets excluded; see scheduler.mayComplete).", "type": "integer" }, "failed": { "type": "integer" }, "inFlight": { "type": "integer" }, "pendingReconnect": { "type": "integer" }, "stuck": { "type": "integer" }, "targets": { "type": "integer" } } }, "rollout.ProgressSnapshot": { "type": "object", "properties": { "attempt": { "type": "integer" }, "bytesDone": { "type": "integer" }, "bytesTotal": { "type": "integer" }, "error": { "type": "string" }, "etaSeconds": { "type": "integer" }, "finishedAt": { "type": "string" }, "id": { "type": "string" }, "itemsDone": { "type": "integer" }, "itemsTotal": { "type": "integer" }, "kind": { "type": "string" }, "message": { "type": "string" }, "phase": { "type": "string" }, "rateBps": { "type": "integer" }, "startedAt": { "type": "string" }, "target": { "type": "string" }, "updatedAt": { "type": "string" } } }, "rollout.RolloutFinalAction": { "type": "string", "enum": [ "reboot", "none", "restart" ], "x-enum-varnames": [ "FinalActionReboot", "FinalActionNone", "FinalActionRestart" ] }, "rollout.RolloutStatus": { "type": "string", "enum": [ "paused", "rolled_back", "pending", "scheduled", "in_progress", "completed", "failed", "cancelled" ], "x-enum-comments": { "RolloutStatusScheduled": "NEW" }, "x-enum-descriptions": [ "", "", "", "NEW", "", "", "", "" ], "x-enum-varnames": [ "RolloutStatusPaused", "RolloutStatusRolledBack", "RolloutStatusPending", "RolloutStatusScheduled", "RolloutStatusInProgress", "RolloutStatusCompleted", "RolloutStatusFailed", "RolloutStatusCancelled" ] }, "rollout.Strategy": { "type": "object", "properties": { "admitRequiresOnline": { "description": "AdmitRequiresOnline is always true for now (offline devices are never\npre-assigned).", "type": "boolean" }, "canary": { "description": "Canary devices are admitted first; the window opens only after every\ncanary converged. 0 = no canary phase.", "type": "integer" }, "failureThreshold": { "description": "FailureThreshold (0-1) pauses the rollout when failed/admitted\nexceeds it.", "type": "number" }, "maxInFlight": { "description": "MaxInFlight bounds admitted devices that are neither converged nor\nfailed.", "type": "integer" }, "maxUnavailable": { "description": "MaxUnavailable pauses the rollout when more admitted devices than\nthis are failed or stuck.", "type": "integer" } } }, "rollout.SystemUpdateSpec": { "type": "object", "properties": { "components": { "description": "Components being targeted (derived from VersionIDs, stored for reporting)", "type": "array", "items": { "type": "string" } }, "final_action": { "description": "FinalAction — reboot / none / restart", "allOf": [ { "$ref": "#/definitions/rollout.RolloutFinalAction" } ] }, "use_current_versions": { "description": "UseCurrentVersions tells the executor to resolve current-marked versions at runtime.", "type": "boolean" }, "version_ids": { "description": "VersionIDs from systemrepo to install. Each maps to a component.", "type": "array", "items": { "type": "string" } } } }, "rollout.UpdateProgress": { "type": "object", "properties": { "components": { "description": "Per-component status", "type": "object", "additionalProperties": { "$ref": "#/definitions/rollout.ComponentUpdateStatus" } }, "download_completed_at": { "type": "string" }, "download_started_at": { "type": "string" }, "install_completed_at": { "type": "string" }, "install_started_at": { "type": "string" }, "manifest_sent_at": { "type": "string" }, "reboot_started_at": { "type": "string" }, "reconnect_attempts": { "description": "Retry tracking during the wait-for-reboot phase", "type": "integer" }, "reconnected_at": { "type": "string" }, "verified_at": { "type": "string" } } }, "rolloutservice.RolloutStreamSummary": { "type": "object", "properties": { "at": { "type": "string" }, "counts": { "$ref": "#/definitions/rollout.Counts" }, "pausedReason": { "type": "string" }, "rolloutId": { "type": "string" }, "stage": { "description": "Stage is \"canary\" or \"rollout\" while strategy.canary \u003e 0, else \"\".", "type": "string" }, "status": { "type": "string" } } }, "searchservice.AdvancedSearchParams": { "type": "object", "properties": { "filters": { "type": "object", "additionalProperties": true }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "query": { "type": "string" }, "sort_by": { "type": "string" }, "sort_order": { "type": "string" }, "types": { "type": "array", "items": { "type": "string" } } } }, "security.Violation": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string" } } }, "securityservice.PolicyRequest": { "type": "object", "properties": { "require_disk_encryption": { "type": "boolean" }, "require_recovery_key_escrow": { "type": "boolean" }, "require_secure_boot": { "type": "boolean" }, "require_tpm": { "type": "boolean" } } }, "securityservice.PolicyView": { "type": "object", "properties": { "can_manage": { "description": "CanManage is whether the caller may change the policy (the same gate as\nPUT), so clients can render read-only views instead of failing on save.", "type": "boolean" }, "devices_noncompliant": { "type": "integer" }, "devices_not_reported": { "type": "integer" }, "devices_total": { "type": "integer" }, "enforced": { "type": "boolean" }, "fleet_id": { "type": "string" }, "require_disk_encryption": { "type": "boolean" }, "require_recovery_key_escrow": { "type": "boolean" }, "require_secure_boot": { "type": "boolean" }, "require_tpm": { "type": "boolean" }, "updated_at": { "type": "string" } } }, "services.Death": { "type": "object", "properties": { "atUnix": { "type": "integer" }, "clean": { "description": "Clean is true for exit 0 or a plain SIGTERM (s6-svc -t, a managed restart).", "type": "boolean" }, "exitCode": { "description": "ExitCode is the process exit status; 128+N when killed by signal N.", "type": "integer" }, "signal": { "description": "Signal is the terminating signal, 0 for a normal exit.", "type": "integer" } } }, "services.Service": { "type": "object", "properties": { "crashes": { "type": "integer" }, "deaths": { "description": "Deaths is the retained death count (s6 keeps the last 100 by default);\nCrashes counts the unclean ones. The Recent* fields cover RecentWindowSeconds.", "type": "integer" }, "health": { "type": "string" }, "lastDeaths": { "description": "LastDeaths is newest first.", "type": "array", "items": { "$ref": "#/definitions/services.Death" } }, "name": { "type": "string" }, "normallyUp": { "type": "boolean" }, "pid": { "type": "integer" }, "ready": { "description": "Ready is false while a service with a notification-fd is still starting.", "type": "boolean" }, "reason": { "description": "Reason is a short human-readable explanation of a non-stable health.", "type": "string" }, "recentCrashes": { "type": "integer" }, "recentDeaths": { "type": "integer" }, "recentWindowSeconds": { "type": "integer" }, "sinceUnix": { "description": "SinceUnix is when the service entered its current state (unix seconds);\nUptimeSeconds is the time since then while up.", "type": "integer" }, "state": { "type": "string" }, "uptimeSeconds": { "type": "integer" }, "wantUp": { "description": "WantUp is what s6 is trying to do; NormallyUp is false for services\nthat ship a ./down file (they are expected to be down by default).", "type": "boolean" } } }, "services.Summary": { "type": "object", "properties": { "flapping": { "type": "integer" }, "restarting": { "type": "integer" }, "stable": { "type": "integer" }, "starting": { "type": "integer" }, "stopped": { "type": "integer" }, "total": { "type": "integer" }, "unavailable": { "type": "integer" }, "unstable": { "type": "integer" }, "unsupervised": { "type": "integer" } } }, "signal.ICEInfo": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "string" } }, "pwd": { "type": "string" }, "ufrag": { "type": "string" } } }, "signaturepolicyservice.View": { "type": "object", "properties": { "organisationId": { "type": "string" }, "signaturePolicy": { "$ref": "#/definitions/container.SignaturePolicy" }, "updatedAt": { "type": "string" }, "updatedBy": { "type": "string" } } }, "state.Boot": { "type": "object", "properties": { "activeSlot": { "type": "string" }, "bootedAt": { "description": "BootedAt is the kernel boot time (CLOCK_REALTIME at boot).", "type": "string" }, "bootloader": { "description": "Bootloader profile detected at runtime.", "allOf": [ { "$ref": "#/definitions/state.Bootloader" } ] }, "cmdline": { "description": "Cmdline is the kernel command line (support scope).", "type": "string" }, "failedUpdates": { "description": "FailedUpdates is the on-device blacklist of versions that rolled back.", "type": "array", "items": { "$ref": "#/definitions/state.FailedUpdate" } }, "kexec": { "description": "Kexec is non-nil when this boot was a kexec hop rather than a cold boot.", "allOf": [ { "$ref": "#/definitions/state.Kexec" } ] }, "knownGoodSlot": { "type": "string" }, "lastSlotRepair": { "description": "LastSlotRepair reports the most recent RepairSlotFromActive outcome.", "allOf": [ { "$ref": "#/definitions/state.SlotRepair" } ] }, "nextSlot": { "type": "string" }, "pendingTrial": { "description": "PendingTrial is set while an update is armed but not yet confirmed good.", "allOf": [ { "$ref": "#/definitions/state.Trial" } ] }, "secureBoot": { "$ref": "#/definitions/device.SecureBootState" }, "slotTries": { "description": "SlotTries is the bootloader's remaining/used try counter for the next\nslot, as the bootloader stores it.", "type": "integer" } } }, "state.BootReason": { "type": "object", "properties": { "action": { "description": "Action is what the agent did: reboot | poweroff | restart_init | kexec.", "type": "string" }, "actor": { "description": "Actor identifies who asked (support scope): user id for remote actions,\nempty for autonomous ones.", "type": "string" }, "agentVersion": { "description": "AgentVersion that recorded the entry.", "type": "string" }, "at": { "type": "string" }, "bootId": { "description": "BootID of the boot that ended.", "type": "string" }, "detail": { "type": "string" }, "kind": { "type": "string" }, "slot": { "type": "string" }, "uptimeSeconds": { "description": "Uptime of the boot that ended, in seconds.", "type": "integer" } } }, "state.Bootloader": { "type": "object", "properties": { "arch": { "type": "string" }, "kind": { "description": "grub | uboot | ...", "type": "string" }, "layout": { "type": "string" } } }, "state.Condition": { "type": "object", "properties": { "lastTransition": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string" }, "type": { "type": "string" } } }, "state.Deadlines": { "type": "object", "properties": { "bootBudgetExpiresAt": { "description": "BootBudgetExpiresAt is when the device reboots if the backend is still\nunreachable. Zero once committed.", "type": "string" }, "bootBudgetMs": { "type": "integer" }, "bootCommitted": { "description": "BootCommitted is true once this boot reached the backend (an OS trial,\nif any, is committed at the same moment).", "type": "boolean" }, "deadmanAt": { "description": "DeadmanAt is last backend contact + MaxOffline, set only while offline\nafter the boot was committed.", "type": "string" }, "heartbeatIntervalMs": { "description": "HeartbeatIntervalMs is the check-in interval in force.", "type": "integer" }, "maxOfflineMs": { "description": "MaxOfflineMs and BootBudgetMs are the limits in force, so the backend\ncan project restarts while it cannot hear the device.", "type": "integer" }, "nextCheckInAt": { "description": "NextCheckInAt is when the next heartbeat is due.", "type": "string" }, "offlineSince": { "description": "OfflineSince is when the current backend outage began. Zero when online.", "type": "string" }, "restartAt": { "description": "RestartAt / RestartReason: the earliest armed self-restart.\nRestartReason is \"boot_budget\" | \"deadman\" | \"\".", "type": "string" }, "restartReason": { "type": "string" } } }, "state.DeviceState": { "type": "object", "properties": { "boot": { "$ref": "#/definitions/state.Boot" }, "bootId": { "description": "BootID is /proc/sys/kernel/random/boot_id; it changes on every boot\n(including kexec) and lets the backend count reboots exactly.", "type": "string" }, "bootReasons": { "description": "BootReasons are the most recent entries of the persistent boot-reason\njournal (newest first, at most 10). The full journal also ships as\nevents on boot.", "type": "array", "items": { "$ref": "#/definitions/state.BootReason" } }, "collectedAt": { "description": "CollectedAt is the device clock when the snapshot was assembled.", "type": "string" }, "conditions": { "description": "Conditions are the device's own verdicts. The backend adds Online.", "type": "array", "items": { "$ref": "#/definitions/state.Condition" } }, "deadlines": { "description": "Deadlines are the device's own check-in and self-restart timers.\nNil on agents that predate device policy.", "allOf": [ { "$ref": "#/definitions/state.Deadlines" } ] }, "deviceId": { "type": "string" }, "edgewire": { "description": "EdgeWire lists the live EdgeWire sessions. Nil: the listener is not\nrunning (EdgeWire disabled on this device). Non-nil with no sessions:\nenabled and idle.", "allOf": [ { "$ref": "#/definitions/state.EdgeWire" } ] }, "localOverride": { "description": "LocalOverride is set while a device-side edit (TUI, BLE, console shell)\nis merged over the backend bundle. Only allow-listed paths can be\noverridden locally (network.*, system.diagnosticsMode, system.timezone,\nsystem.hostname); the device clears it automatically once the backend\nbundle renders the same effective result.", "allOf": [ { "$ref": "#/definitions/state.LocalOverride" } ] }, "network": { "$ref": "#/definitions/network.NetworkStatus" }, "observedGeneration": { "description": "ObservedGeneration is the backend document generation the device last\naccepted via the desired protocol. 0 for legacy devices.", "type": "integer" }, "policy": { "description": "Policy is the device policy in force after defaults and clamping,\nevery field populated (lists carry customer entries only; built-in\nfallbacks are always added on top). Nil on agents that predate it.", "allOf": [ { "$ref": "#/definitions/desired.DevicePolicy" } ] }, "policyClamped": { "description": "PolicyClamped lists policy paths whose requested value was out of range\nor malformed and was replaced on the device.", "type": "array", "items": { "type": "string" } }, "progress": { "description": "Progress is the current set of long-running operations (see progress.go).\nLive updates ride backend.\u003cid\u003e.progress; this is the snapshot.", "allOf": [ { "$ref": "#/definitions/state.Progress" } ] }, "renderedRevision": { "description": "RenderedRevision is the revision hash of the DesiredBundle the device\nlast applied. Empty for legacy devices.", "type": "string" }, "runtime": { "description": "Workload runtime detail that ContainerStatus does not carry.", "allOf": [ { "$ref": "#/definitions/state.WorkloadRuntime" } ] }, "schemaVersion": { "type": "integer" }, "storage": { "description": "Storage lists the filesystems the agent depends on (/, /admrl, /app and\nthe userdata volume). Always a list in JSON.", "type": "array", "items": { "$ref": "#/definitions/state.Filesystem" } }, "system": { "$ref": "#/definitions/state.System" }, "time": { "type": "string" }, "transport": { "$ref": "#/definitions/state.Transport" }, "workload": { "$ref": "#/definitions/container.ContainerStatus" } } }, "state.EdgeWire": { "type": "object", "properties": { "maxSessions": { "type": "integer" }, "rescueSlots": { "type": "integer" }, "sessions": { "description": "Sessions are the established sessions, oldest first. Always a JSON list.", "type": "array", "items": { "$ref": "#/definitions/state.EdgeWireSession" } } } }, "state.EdgeWireSession": { "type": "object", "properties": { "application": { "description": "Application is \"ssh\", \"exec\", \"debug\" or \"workload\".", "type": "string" }, "bytesRx": { "type": "integer" }, "bytesTx": { "description": "BytesTx/BytesRx are wire bytes summed over paths, local view.", "type": "integer" }, "flows": { "type": "integer" }, "kind": { "description": "Kind is \"rescue\" or \"customer\".", "type": "string" }, "localAddr": { "description": "Local/RemoteAddr are ip:port; the backend redacts them for non-admins.", "type": "string" }, "localCandidate": { "description": "Local/RemoteCandidate are ICE candidate types: host, srflx, prflx, relay.", "type": "string" }, "openStreams": { "description": "OpenStreams and Flows are the current counts.", "type": "integer" }, "path": { "description": "Path is direct, relay_udp, relay_tls, nats or other.", "type": "string" }, "pathChangedAt": { "type": "string" }, "remoteAddr": { "type": "string" }, "remoteCandidate": { "type": "string" }, "rttMs": { "type": "number" }, "sessionId": { "type": "string" }, "startedAt": { "type": "string" } } }, "state.FailedUpdate": { "type": "object", "properties": { "component": { "type": "string" }, "failedAt": { "type": "string" }, "reason": { "type": "string" }, "version": { "type": "string" } } }, "state.Filesystem": { "type": "object", "properties": { "device": { "type": "string" }, "expected": { "description": "Expected is the mount mode the agent wants (ro | rw); a mismatch with\nReadOnly is a fault.", "type": "string" }, "fsType": { "type": "string" }, "level": { "description": "Level is the device's own verdict against its thresholds: ok | warn | error.", "type": "string" }, "mount": { "type": "string" }, "readOnly": { "type": "boolean" }, "totalBytes": { "type": "integer" }, "usedBytes": { "type": "integer" } } }, "state.Kexec": { "type": "object", "properties": { "hop": { "type": "integer" } } }, "state.LocalOverride": { "type": "object", "properties": { "diagnosticsMode": { "description": "System holds the non-network overridden values.", "type": "boolean" }, "editedAt": { "type": "string" }, "hostname": { "type": "string" }, "network": { "description": "Network is the overriding network configuration with credentials\nredacted. Nil when no network path is overridden.", "allOf": [ { "$ref": "#/definitions/github_com_qdynamicsco_admrl-core_api_network.NetworkConfiguration" } ] }, "paths": { "description": "Paths are JSON-pointer-style paths that the override sets, e.g.\n\"network.wifi.ssid\", \"system.diagnosticsMode\".", "type": "array", "items": { "type": "string" } }, "reason": { "description": "Reason as typed by the person on site, if any.", "type": "string" }, "revision": { "type": "string" }, "source": { "description": "tui | ble | console | file", "type": "string" }, "timezone": { "type": "string" } } }, "state.Operation": { "type": "object", "properties": { "attempt": { "description": "Attempt counts retries of this operation (1 = first try).", "type": "integer" }, "bytesDone": { "description": "Byte progress when known (downloads, slot writes). Total 0 = unknown.", "type": "integer" }, "bytesTotal": { "type": "integer" }, "error": { "type": "string" }, "etaSeconds": { "type": "integer" }, "finishedAt": { "type": "string" }, "id": { "description": "ID is stable for the life of the operation (device-generated).", "type": "string" }, "itemsDone": { "description": "Item progress when the work is discrete (layers, files, secrets).", "type": "integer" }, "itemsTotal": { "type": "integer" }, "kind": { "type": "string" }, "message": { "description": "Message is a short human line (\"layer 3/5\", \"waiting for 01:00 window\").", "type": "string" }, "parent": { "description": "Parent links a sub-operation (one layer) to its parent (the pull);\nthe device normally reports only the parent.", "type": "string" }, "phase": { "type": "string" }, "rateBps": { "description": "RateBps is the recent throughput; EtaSeconds the device's estimate.", "type": "integer" }, "startedAt": { "type": "string" }, "target": { "description": "Target names what is being worked on: image reference, component\nversion (\"rootfs 1.4.2\"), configuration name/version.", "type": "string" }, "updatedAt": { "type": "string" } } }, "state.Progress": { "type": "object", "properties": { "operations": { "description": "Operations in flight or finished within the last 60 s (finished ones\ncarry Phase done|failed so a subscriber sees the terminal state once).", "type": "array", "items": { "$ref": "#/definitions/state.Operation" } }, "targetGeneration": { "description": "Generation/Revision the operations are working towards (0/\"\" for a\nlegacy push or an operation unrelated to desired state).", "type": "integer" }, "targetRevision": { "type": "string" }, "updatedAt": { "type": "string" } } }, "state.SlotRepair": { "type": "object", "properties": { "at": { "type": "string" }, "detail": { "type": "string" }, "durationMs": { "type": "integer" }, "result": { "description": "repaired | clean | failed | skipped", "type": "string" }, "slot": { "type": "string" } } }, "state.System": { "type": "object", "properties": { "agentStartedAt": { "description": "AgentStartedAt is when this admrl-init process started; compare with\nUptimeSeconds to spot an agent that restarted without a reboot.", "type": "string" }, "appWriteHolders": { "description": "AppWritable reports the refcounted /app RW lock: holders \u003e 0 means a\nwriter is active. LastRemountError is the most recent remount failure.", "type": "integer" }, "diagnosticsMode": { "description": "DiagnosticsMode is true when the workload is inhibited for servicing.", "type": "boolean" }, "hostname": { "description": "Hostname as the kernel reports it.", "type": "string" }, "lastRemountError": { "type": "string" }, "missingFirmware": { "type": "array", "items": { "type": "string" } }, "pendingAction": { "description": "PendingAction is the deferred lifecycle action (\"reboot\", \"poweroff\",\n\"restart_init\", \"\") the agent intends to take.", "type": "string" }, "powerMode": { "description": "e.g. Jetson nvpmodel name", "type": "string" }, "thermalZones": { "type": "array", "items": { "$ref": "#/definitions/state.ThermalZone" } }, "uptimeSeconds": { "type": "integer" }, "versions": { "$ref": "#/definitions/device.SystemVersions" }, "watchdogLastActivityAgeMs": { "description": "WatchdogLastActivityAgeMs is how long since the logger saw activity;\nthe hardware watchdog feeder stops when this goes stale.", "type": "integer" } } }, "state.ThermalZone": { "type": "object", "properties": { "celsius": { "type": "number" }, "level": { "description": "ok | warn | error", "type": "string" }, "name": { "type": "string" } } }, "state.Transport": { "type": "object", "properties": { "breakGlass": { "description": "BreakGlass is true while the periodic break-glass reconnect is active.", "type": "boolean" }, "connectedAt": { "description": "ConnectedAt is when the current connection came up.", "type": "string" }, "endpoint": { "description": "Endpoint is the host:port in use (support scope: redacted for customers).", "type": "string" }, "instability": { "description": "Instability is the agent's running instability counter.", "type": "integer" }, "jetStreamConnected": { "description": "JetStreamConnected reports whether telemetry publishing is live.", "type": "boolean" }, "kind": { "description": "Kind is the NATS transport in use: tcp | kcp | wss.", "type": "string" }, "lastBackendContact": { "description": "LastBackendContact is the last successful backend round-trip.", "type": "string" }, "latencyMs": { "description": "LatencyMs is the latest request/reply RTT to backend.api.status.", "type": "integer" }, "proxy": { "description": "Proxy is the HTTP(S) proxy in effect, if any (support scope).", "type": "string" }, "reconnects": { "description": "Reconnects since the agent started.", "type": "integer" }, "role": { "description": "Role is the NATS account role the credentials carry (legacy | strict).", "type": "string" } } }, "state.Trial": { "type": "object", "properties": { "armedAt": { "type": "string" }, "component": { "type": "string" }, "slot": { "type": "string" }, "version": { "type": "string" } } }, "state.WorkloadRuntime": { "type": "object", "properties": { "assignedConfigApplied": { "description": "AssignedConfigApplied is false when the config the backend assigned is\nnot the one running (pending, staged, rolled back).", "type": "boolean" }, "cniHealthy": { "description": "CNIHealthy reports the workload bridge health check.", "type": "boolean" }, "containerId": { "type": "string" }, "crunState": { "description": "CrunState is the raw runtime state string (created|running|stopped).", "type": "string" }, "exitCode": { "type": "integer" }, "failureCount": { "type": "integer" }, "imageDigest": { "description": "ImageDigest is the resolved digest of the image in use.", "type": "string" }, "lastExitAt": { "description": "LastExitAt is when the container last exited.", "type": "string" }, "oomEvents": { "type": "integer" }, "oomKilled": { "type": "boolean" }, "pid": { "type": "integer" } } }, "system.AvailableVersionsResponse": { "type": "object", "properties": { "architecture": { "type": "string" }, "available": { "type": "array", "items": { "$ref": "#/definitions/system.ComponentVersion" } }, "board": { "type": "string" }, "current": { "$ref": "#/definitions/system.ComponentVersions" }, "device_id": { "type": "string" }, "recommended": { "type": "array", "items": { "$ref": "#/definitions/system.ComponentVersion" } } } }, "system.ComponentFloorBreach": { "type": "object", "properties": { "component": { "$ref": "#/definitions/system.ComponentType" }, "minimum_version": { "type": "string" }, "reported_version": { "type": "string" }, "resolved_version": { "description": "ResolvedVersion is the artifact chosen to remediate, or \"\" when no\ncompatible artifact at-or-above the floor is registered.", "type": "string" } } }, "system.ComponentType": { "type": "string", "enum": [ "initram", "system", "rootfs", "modules" ], "x-enum-varnames": [ "ComponentInitram", "ComponentSystem", "ComponentRootfsLegacy", "ComponentModules" ] }, "system.ComponentVersion": { "type": "object", "properties": { "architecture": { "description": "Architecture is required. Artifacts are per-arch; there is no\n\"universal\" build. Values: \"amd64\" | \"arm64\".", "type": "string" }, "boards": { "description": "Boards is the set of boards this version applies to. An empty slice\nmeans \"any board on this architecture\". Values are free-form but\nmust match what the edge agent reports in SystemHeader.Board\n(e.g. \"rpi5\", \"jetson-orin-nano\").", "type": "array", "items": { "type": "string" } }, "component": { "$ref": "#/definitions/system.ComponentType" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "description": { "type": "string" }, "force": { "description": "Force causes the edge agent to apply even if the target version is\nalready installed.", "type": "boolean" }, "id": { "type": "string" }, "is_current": { "description": "IsCurrent is unique within (component, architecture, boards).\nMultiple versions can be \"current\" across the fleet — one per tuple.", "type": "boolean" }, "requires": { "description": "Requires maps to updates.UpdateOperation.Requires — component\ndependency constraints. Example: {\"rootfs\": \"\u003e=1.4.0\"}.", "type": "object", "additionalProperties": { "type": "string" } }, "sha256": { "type": "string" }, "updated_at": { "type": "string" }, "url": { "type": "string" }, "version": { "type": "string" } } }, "system.ComponentVersionSet": { "type": "object", "properties": { "available": { "type": "array", "items": { "$ref": "#/definitions/system.ComponentVersion" } }, "current": { "$ref": "#/definitions/system.ComponentVersion" }, "recommended": { "$ref": "#/definitions/system.ComponentVersion" } } }, "system.ComponentVersions": { "type": "object", "properties": { "architecture": { "type": "string" }, "board": { "type": "string" }, "init_version": { "type": "string" }, "modules_version": { "type": "string" }, "system_version": { "type": "string" } } }, "system.DeviceUpdateState": { "type": "object", "properties": { "architecture": { "type": "string" }, "board": { "type": "string" }, "device_id": { "type": "string" }, "hardware_rev": { "type": "string" }, "init_version": { "type": "string" }, "last_checked": { "type": "string" }, "model": { "type": "string" }, "modules_version": { "type": "string" }, "pending_action": { "type": "string" }, "system_version": { "type": "string" } } }, "system.DeviceVersionInfo": { "type": "object", "properties": { "architecture": { "type": "string" }, "board": { "type": "string" }, "by_component": { "type": "object", "additionalProperties": { "$ref": "#/definitions/system.ComponentVersionSet" } }, "current_state": { "$ref": "#/definitions/system.ComponentVersions" }, "device_id": { "type": "string" }, "hardware_rev": { "type": "string" }, "model": { "type": "string" }, "pending_action": { "type": "string" }, "updates_available": { "type": "boolean" } } }, "system.FloorBreachRecord": { "type": "object", "properties": { "architecture": { "type": "string" }, "attempts": { "type": "integer" }, "blocking": { "type": "boolean" }, "board": { "type": "string" }, "breaches": { "type": "array", "items": { "$ref": "#/definitions/system.ComponentFloorBreach" } }, "device_id": { "type": "string" }, "first_seen_at": { "type": "string" }, "last_seen_at": { "type": "string" }, "remediable": { "description": "Remediable is false when a floor is configured but no compatible\nartifact at-or-above it exists. That is operator misconfiguration and\nthe highest-priority thing on this list.", "type": "boolean" } } }, "system.MinimumVersion": { "type": "object", "properties": { "architecture": { "type": "string" }, "blocking": { "description": "Blocking escalates this floor from advisory to enforced.\n\nAdvisory (false, the default): the device receives its NATS JWT along\nwith update_required + manifest. A cooperative agent bails out and\nupdates; a modified or hostile agent ignores the flag and joins the\nfabric anyway. This is a COMPLIANCE control, not an access control.\n\nBlocking (true): the JWT is withheld, so a device that ignores\nupdate_required has no usable credential and cannot reach the hub. Safe\nonly because the agent's early return happens before it touches the JWT.\nThe onboard handler additionally refuses to withhold a JWT when no\nmanifest could be resolved — otherwise a floor set before its artifact\nexists would deny credentials to an entire architecture.", "type": "boolean" }, "board": { "description": "Board is stored WITHOUT omitempty so the \"all boards\" row is a queryable\nempty string rather than a missing field. Keeps ListMinimumsFor simple.", "type": "string" }, "component": { "$ref": "#/definitions/system.ComponentType" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "id": { "type": "string" }, "notes": { "type": "string" }, "updated_at": { "type": "string" }, "version": { "type": "string" } } }, "system.PushUpdateRequest": { "type": "object", "properties": { "final_action": { "type": "string" }, "specific_version_ids": { "type": "array", "items": { "type": "string" } }, "use_current_versions": { "type": "boolean" } } }, "system.SetMinimumVersionRequest": { "type": "object", "properties": { "architecture": { "type": "string" }, "blocking": { "type": "boolean" }, "board": { "type": "string" }, "component": { "$ref": "#/definitions/system.ComponentType" }, "notes": { "type": "string" }, "version": { "type": "string" } } }, "usbpolicy.Policy": { "type": "object", "properties": { "allow": { "type": "array", "items": { "$ref": "#/definitions/usbpolicy.Rule" } }, "mode": { "type": "string", "enum": [ "off", "block_storage_hid", "allowlist" ], "example": "block_storage_hid" }, "updated_at": { "type": "string" } } }, "usbpolicy.Rule": { "type": "object", "properties": { "comment": { "type": "string", "example": "Barcode scanner" }, "interface_class": { "type": "string", "example": "08" }, "product_id": { "type": "string", "example": "8153" }, "vendor_id": { "type": "string", "example": "0bda" } } }, "usbpolicyservice.DevicePolicyUpdateView": { "type": "object", "properties": { "delivered": { "description": "Delivered is false when the device is offline or the push failed; the\ndevice converges on its next pull.", "type": "boolean" }, "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "device_override": { "$ref": "#/definitions/usbpolicy.Policy" }, "effective": { "$ref": "#/definitions/usbpolicy.Policy" }, "fleet_id": { "description": "FleetID is empty when the device is in no fleet.", "type": "string" }, "fleet_policy": { "$ref": "#/definitions/usbpolicy.Policy" }, "source": { "type": "string", "enum": [ "device", "fleet", "default" ] } } }, "usbpolicyservice.DevicePolicyView": { "type": "object", "properties": { "deviceId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "device_override": { "$ref": "#/definitions/usbpolicy.Policy" }, "effective": { "$ref": "#/definitions/usbpolicy.Policy" }, "fleet_id": { "description": "FleetID is empty when the device is in no fleet.", "type": "string" }, "fleet_policy": { "$ref": "#/definitions/usbpolicy.Policy" }, "source": { "type": "string", "enum": [ "device", "fleet", "default" ] } } }, "usbpolicyservice.FleetPolicyUpdateView": { "type": "object", "properties": { "devices_notified": { "description": "DevicesNotified is the number of fleet devices a background push was\nstarted for.", "type": "integer" }, "fleet_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "policy": { "$ref": "#/definitions/usbpolicy.Policy" } } }, "usbpolicyservice.FleetPolicyView": { "type": "object", "properties": { "fleet_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "policy": { "$ref": "#/definitions/usbpolicy.Policy" } } } }, "securityDefinitions": { "ApiSecretAuth": { "description": "Your Personal API Secret Key", "type": "apiKey", "name": "X-API-Secret-Key", "in": "header" }, "ApiTokenAuth": { "description": "Your Personal API Token ID", "type": "apiKey", "name": "X-API-Token-ID", "in": "header" }, "BearerAuth": { "description": "Service-account OAuth2 token from POST /oauth/token. Enter the FULL value including the prefix: \"Bearer eyJhbGci...\"", "type": "apiKey", "name": "Authorization", "in": "header" }, "EdgeWireToken": { "description": "EdgeWire token from POST /edgewire/token (the only credential the /cli/edgewire/session endpoints accept). Enter the FULL value including the prefix: \"Bearer admrl_ew_...\"", "type": "apiKey", "name": "Authorization", "in": "header" } } }