{ "openapi": "3.1.1", "info": { "title": "Spotflow Management API", "version": "0.67.0+829c506e09d2a618a1be1208f7695027cb3c9baa" }, "servers": [ { "url": "https://api.spotflow.io" } ], "paths": { "/workspaces/{workspaceId}/settings": { "get": { "tags": [ "Workspaces" ], "summary": "Get workspace settings", "operationId": "GET-workspaces-{workspaceId}-settings", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workspace settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSettings" } } } }, "404": { "description": "Workspace not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Workspace settings: read" ] } ] }, "put": { "tags": [ "Workspaces" ], "summary": "Update workspace settings", "operationId": "PUT-workspaces-{workspaceId}-settings", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceSettingsCommand" } } }, "required": true }, "responses": { "200": { "description": "Updated workspace settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSettings" } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Workspace not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Workspace settings: write" ] } ] } }, "/workspaces/{workspaceId}/members": { "get": { "tags": [ "Workspace members" ], "summary": "List workspace members", "operationId": "GET-workspaces-{workspaceId}-members", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "All members of the workspace.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceMemberListItem" } } } } } }, "security": [ { "API key": [ "Workspace members: read" ] } ] } }, "/workspaces/{workspaceId}/members/{subjectId}": { "delete": { "tags": [ "Workspace members" ], "summary": "Remove workspace member", "operationId": "DELETE-workspaces-{workspaceId}-members-{subjectId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "subjectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Member removed from the workspace." }, "400": { "description": "Member cannot be removed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Workspace member not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Workspace members: write" ] } ] } }, "/workspaces/{workspaceId}/firmware-versions/{firmwareVersionId}/sboms": { "post": { "tags": [ "SBOMs" ], "summary": "Upload SBOMs", "operationId": "POST-workspaces-{workspaceId}-firmware-versions-{firmwareVersionId}-sboms", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Upload SBOMs": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareVersionId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Upload SBOMs": { "description": "Firmware version ID.", "value": "r2Kt75mXc8Vd" } } } ], "responses": { "202": { "description": "Uploaded SBOMs accepted for parsing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SbomBatchUploadResponse" }, "examples": { "Upload SBOMs": { "description": "SBOMs accepted for parsing.", "value": { "sboms": [ { "id": "z3Mp96lQd4Gt", "parsingState": "InProgress" } ] } } } } } }, "400": { "description": "Upload is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Firmware version not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "SBOMs: write" ] } ] }, "get": { "tags": [ "SBOMs" ], "summary": "List SBOMs", "operationId": "GET-workspaces-{workspaceId}-firmware-versions-{firmwareVersionId}-sboms", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List SBOMs": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareVersionId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List SBOMs": { "description": "Firmware version ID.", "value": "r2Kt75mXc8Vd" } } } ], "responses": { "200": { "description": "All SBOMs of the firmware version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSbomsResponse" }, "examples": { "List SBOMs": { "description": "All SBOMs of the firmware version.", "value": { "sboms": [ { "id": "z3Mp96lQd4Gt", "fileName": "thermostat-application-2.4.1.spdx.json", "format": "Spdx3JsonLd", "parsingState": "Succeeded", "componentCount": 142, "createdAt": "2026-01-10T15:35:00+00:00", "vulnerabilitiesParsedAt": "2026-01-10T15:38:00+00:00" } ] } } } } } }, "404": { "description": "Firmware version not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "SBOMs: read" ] } ] } }, "/workspaces/{workspaceId}/sboms/{sbomId}/content": { "get": { "tags": [ "SBOMs" ], "summary": "Get SBOM content link", "operationId": "GET-workspaces-{workspaceId}-sboms-{sbomId}-content", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get SBOM content link": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "sbomId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get SBOM content link": { "description": "SBOM ID.", "value": "z3Mp96lQd4Gt" } } } ], "responses": { "200": { "description": "Time-limited link to the SBOM content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SbomContentResponse" }, "examples": { "Get SBOM content link": { "description": "Time-limited link to the SBOM file.", "value": { "contentSasLink": "https://storage.spotflow.io/sboms/z3Mp96lQd4Gt.spdx.json?sv=2025-01-01&sig=example", "fileName": "thermostat-application-2.4.1.spdx.json" } } } } } }, "404": { "description": "SBOM not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "SBOMs: read" ] } ] } }, "/workspaces/{workspaceId}/sboms/{sbomId}": { "delete": { "tags": [ "SBOMs" ], "summary": "Delete SBOM", "operationId": "DELETE-workspaces-{workspaceId}-sboms-{sbomId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Delete SBOM": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "sbomId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Delete SBOM": { "description": "SBOM ID.", "value": "z3Mp96lQd4Gt" } } } ], "responses": { "204": { "description": "SBOM deleted." }, "404": { "description": "SBOM not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "SBOMs: write" ] } ] } }, "/workspaces/{workspaceId}/firmware-versions/{firmwareVersionId}/sbom-components": { "get": { "tags": [ "SBOMs" ], "summary": "List components of firmware version", "operationId": "GET-workspaces-{workspaceId}-firmware-versions-{firmwareVersionId}-sbom-components", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List components of firmware version": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareVersionId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List components of firmware version": { "description": "Firmware version ID.", "value": "r2Kt75mXc8Vd" } } } ], "responses": { "200": { "description": "Components across all SBOMs of the firmware version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFirmwareVersionComponentsResponse" }, "examples": { "List components of firmware version": { "description": "Components found in the SBOMs of the firmware version.", "value": { "components": [ { "vendor": "ARM", "packageName": "mbedtls", "version": "3.5.2", "purl": "pkg:generic/mbedtls@3.5.2", "cpe": "cpe:2.3:a:arm:mbed_tls:3.5.2:*:*:*:*:*:*:*", "pathsToRoot": [ [ "thermostat-application", "mbedtls" ] ] } ] } } } } } }, "404": { "description": "Firmware version not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "SBOMs: read" ] } ] } }, "/workspaces/{workspaceId}/sboms/{sbomId}/components/list": { "post": { "tags": [ "SBOMs" ], "summary": "List SBOM components", "operationId": "POST-workspaces-{workspaceId}-sboms-{sbomId}-components-list", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List SBOM components": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "sbomId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List SBOM components": { "description": "SBOM ID.", "value": "z3Mp96lQd4Gt" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSbomComponentsCommand" }, "examples": { "List SBOM components": { "value": { "limit": 50 } } } } }, "required": true }, "responses": { "200": { "description": "Matching components with a pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSbomComponentsResponse" }, "examples": { "List SBOM components": { "description": "Page of components declared by the SBOM.", "value": { "components": [ { "id": "a5Nk38jTw2Qe", "packageName": "mbedtls", "version": "3.5.2", "purl": "pkg:generic/mbedtls@3.5.2", "cpe": "cpe:2.3:a:arm:mbed_tls:3.5.2:*:*:*:*:*:*:*", "vendor": "ARM", "pathsToRoot": [ [ "thermostat-application", "mbedtls" ] ] } ], "nextCursor": "eyJvZmZzZXQiOjUwfQ", "hasMore": true } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "SBOM not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "SBOMs: read" ] } ] } }, "/workspaces/{workspaceId}/firmware-versions/{firmwareVersionId}/vulnerability-findings/list": { "post": { "tags": [ "Vulnerability findings" ], "summary": "List vulnerability findings", "operationId": "POST-workspaces-{workspaceId}-firmware-versions-{firmwareVersionId}-vulnerability-findings-list", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List vulnerability findings": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareVersionId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List vulnerability findings": { "description": "Firmware version ID.", "value": "r2Kt75mXc8Vd" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVulnerabilityFindingsCommand" }, "examples": { "List vulnerability findings": { "value": { "sortColumn": "Severity", "ascending": false, "limit": 50, "filter": { "severities": [ "Critical", "High" ], "assessments": [ "NotAssessed", "InTriage" ], "ignored": false, "knownCisaExploit": false, "name": [ { "contains": "mbedtls" } ], "components": [ { "vendor": "ARM", "packageName": "mbedtls", "version": "3.5.2" } ] } } } } } }, "required": true }, "responses": { "200": { "description": "Matching vulnerability findings with a pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVulnerabilityFindingsResponse" }, "examples": { "List vulnerability findings": { "description": "Page of vulnerability findings of the firmware version.", "value": { "findings": [ { "id": "b8Qr47xVm1Zj", "cveId": "CVE-2025-12345", "name": "CVE-2025-12345", "componentName": "mbedtls", "componentVersion": "3.5.2", "severity": "Critical", "assessment": "InTriage", "ignored": false, "isKnownCisaExploit": false, "detectedAt": "2026-01-10T15:38:00+00:00" } ], "hasMore": false } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Firmware version not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Vulnerabilities: read" ] } ] } }, "/workspaces/{workspaceId}/vulnerability-findings/{findingId}": { "get": { "tags": [ "Vulnerability findings" ], "summary": "Get vulnerability finding", "operationId": "GET-workspaces-{workspaceId}-vulnerability-findings-{findingId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get vulnerability finding": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "findingId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get vulnerability finding": { "description": "Vulnerability finding ID.", "value": "b8Qr47xVm1Zj" } } } ], "responses": { "200": { "description": "Vulnerability finding detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VulnerabilityFindingDetail" }, "examples": { "Get vulnerability finding": { "description": "Vulnerability finding detail.", "value": { "id": "b8Qr47xVm1Zj", "assessment": "InTriage", "ignored": false, "isKnownCisaExploit": false, "component": { "name": "mbedtls", "version": "3.5.2", "cpe": "cpe:2.3:a:arm:mbed_tls:3.5.2:*:*:*:*:*:*:*", "purl": "pkg:generic/mbedtls@3.5.2", "vendor": "ARM" }, "cve": { "id": "CVE-2025-12345", "source": "NVD", "sourceUrl": "https://nvd.nist.gov/vuln/detail/CVE-2025-12345", "description": "A buffer overflow in the TLS handshake parser allows a remote attacker to crash the device.", "status": "Analyzed", "severity": "Critical", "primaryBaseScore": 9.1, "cvssScores": [ { "version": "3.1", "vectorString": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:H", "baseScore": 9.1, "baseSeverity": "CRITICAL", "source": "nvd@nist.gov" } ], "references": [ { "url": "https://github.com/Mbed-TLS/mbedtls/security/advisories/example", "source": "GitHub", "tags": [ "Vendor Advisory" ] } ], "cwes": [ { "id": "CWE-120", "name": "Buffer Copy without Checking Size of Input" } ], "publishedAt": "2025-12-18T10:00:00+00:00", "modifiedAt": "2026-01-04T08:30:00+00:00" }, "affectedPackages": [ { "purl": "pkg:generic/mbedtls", "packageName": "mbedtls", "vendor": "ARM", "versions": [ { "cpe": "cpe:2.3:a:arm:mbed_tls:*:*:*:*:*:*:*:*", "versionStartIncluding": "3.0.0", "versionEndExcluding": "3.6.0" } ] } ], "sboms": [ { "sbomId": "z3Mp96lQd4Gt", "fileName": "thermostat-application-2.4.1.spdx.json", "pathsToRoot": [ [ "thermostat-application", "mbedtls" ] ] } ], "timeline": [ { "type": "Published", "timestamp": "2025-12-18T10:00:00+00:00" }, { "type": "Detected", "timestamp": "2026-01-10T15:38:00+00:00" }, { "type": "Assessment", "timestamp": "2026-01-11T09:15:00+00:00", "source": "User", "createdByEmail": "security@example.com", "assessment": { "assessment": "InTriage", "detail": "Checking whether the affected code path is reachable." } } ] } } } } } }, "404": { "description": "Vulnerability finding not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Vulnerabilities: read" ] } ] } }, "/workspaces/{workspaceId}/vulnerability-findings/{findingId}/assessments": { "post": { "tags": [ "Vulnerability findings" ], "summary": "Assess vulnerability finding", "operationId": "POST-workspaces-{workspaceId}-vulnerability-findings-{findingId}-assessments", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Assess vulnerability finding as not affected": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "findingId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Assess vulnerability finding as not affected": { "description": "Vulnerability finding ID.", "value": "b8Qr47xVm1Zj" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssessVulnerabilityFindingCommand" }, "examples": { "Assess vulnerability finding as not affected": { "value": { "assessment": "NotAffected", "justification": "vulnerable_code_not_in_execute_path", "detail": "The TLS handshake parser is compiled out of the firmware build.", "response": "will_not_fix" } } } } }, "required": true }, "responses": { "200": { "description": "Vulnerability finding with the new assessment applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VulnerabilityFindingDetail" }, "examples": { "Assess vulnerability finding as not affected": { "description": "Vulnerability finding with the new assessment.", "value": { "id": "b8Qr47xVm1Zj", "assessment": "NotAffected", "ignored": false, "isKnownCisaExploit": false, "component": { "name": "mbedtls", "version": "3.5.2", "cpe": "cpe:2.3:a:arm:mbed_tls:3.5.2:*:*:*:*:*:*:*", "purl": "pkg:generic/mbedtls@3.5.2", "vendor": "ARM" }, "cve": { "id": "CVE-2025-12345", "source": "NVD", "sourceUrl": "https://nvd.nist.gov/vuln/detail/CVE-2025-12345", "description": "A buffer overflow in the TLS handshake parser allows a remote attacker to crash the device.", "status": "Analyzed", "severity": "Critical", "primaryBaseScore": 9.1, "cvssScores": [ { "version": "3.1", "vectorString": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:H", "baseScore": 9.1, "baseSeverity": "CRITICAL", "source": "nvd@nist.gov" } ], "references": [ { "url": "https://github.com/Mbed-TLS/mbedtls/security/advisories/example", "source": "GitHub", "tags": [ "Vendor Advisory" ] } ], "cwes": [ { "id": "CWE-120", "name": "Buffer Copy without Checking Size of Input" } ], "publishedAt": "2025-12-18T10:00:00+00:00", "modifiedAt": "2026-01-04T08:30:00+00:00" }, "affectedPackages": [ { "purl": "pkg:generic/mbedtls", "packageName": "mbedtls", "vendor": "ARM", "versions": [ { "cpe": "cpe:2.3:a:arm:mbed_tls:*:*:*:*:*:*:*:*", "versionStartIncluding": "3.0.0", "versionEndExcluding": "3.6.0" } ] } ], "sboms": [ { "sbomId": "z3Mp96lQd4Gt", "fileName": "thermostat-application-2.4.1.spdx.json", "pathsToRoot": [ [ "thermostat-application", "mbedtls" ] ] } ], "timeline": [ { "type": "Published", "timestamp": "2025-12-18T10:00:00+00:00" }, { "type": "Detected", "timestamp": "2026-01-10T15:38:00+00:00" }, { "type": "Assessment", "timestamp": "2026-01-11T09:15:00+00:00", "source": "User", "createdByEmail": "security@example.com", "assessment": { "assessment": "InTriage", "detail": "Checking whether the affected code path is reachable." } } ] } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Vulnerability finding not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Vulnerabilities: write" ] } ] } }, "/workspaces/{workspaceId}/vulnerability-findings/{findingId}/ignore": { "put": { "tags": [ "Vulnerability findings" ], "summary": "Set vulnerability finding ignored", "operationId": "PUT-workspaces-{workspaceId}-vulnerability-findings-{findingId}-ignore", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Ignore vulnerability finding": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "findingId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Ignore vulnerability finding": { "description": "Vulnerability finding ID.", "value": "b8Qr47xVm1Zj" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetVulnerabilityFindingIgnoredCommand" }, "examples": { "Ignore vulnerability finding": { "value": { "ignored": true } } } } }, "required": true }, "responses": { "200": { "description": "Vulnerability finding with the new ignored state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VulnerabilityFindingDetail" }, "examples": { "Ignore vulnerability finding": { "description": "Vulnerability finding with the new ignored flag.", "value": { "id": "b8Qr47xVm1Zj", "assessment": "NotAffected", "ignored": true, "isKnownCisaExploit": false, "component": { "name": "mbedtls", "version": "3.5.2", "cpe": "cpe:2.3:a:arm:mbed_tls:3.5.2:*:*:*:*:*:*:*", "purl": "pkg:generic/mbedtls@3.5.2", "vendor": "ARM" }, "cve": { "id": "CVE-2025-12345", "source": "NVD", "sourceUrl": "https://nvd.nist.gov/vuln/detail/CVE-2025-12345", "description": "A buffer overflow in the TLS handshake parser allows a remote attacker to crash the device.", "status": "Analyzed", "severity": "Critical", "primaryBaseScore": 9.1, "cvssScores": [ { "version": "3.1", "vectorString": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:N/A:H", "baseScore": 9.1, "baseSeverity": "CRITICAL", "source": "nvd@nist.gov" } ], "references": [ { "url": "https://github.com/Mbed-TLS/mbedtls/security/advisories/example", "source": "GitHub", "tags": [ "Vendor Advisory" ] } ], "cwes": [ { "id": "CWE-120", "name": "Buffer Copy without Checking Size of Input" } ], "publishedAt": "2025-12-18T10:00:00+00:00", "modifiedAt": "2026-01-04T08:30:00+00:00" }, "affectedPackages": [ { "purl": "pkg:generic/mbedtls", "packageName": "mbedtls", "vendor": "ARM", "versions": [ { "cpe": "cpe:2.3:a:arm:mbed_tls:*:*:*:*:*:*:*:*", "versionStartIncluding": "3.0.0", "versionEndExcluding": "3.6.0" } ] } ], "sboms": [ { "sbomId": "z3Mp96lQd4Gt", "fileName": "thermostat-application-2.4.1.spdx.json", "pathsToRoot": [ [ "thermostat-application", "mbedtls" ] ] } ], "timeline": [ { "type": "Published", "timestamp": "2025-12-18T10:00:00+00:00" }, { "type": "Detected", "timestamp": "2026-01-10T15:38:00+00:00" }, { "type": "Assessment", "timestamp": "2026-01-11T09:15:00+00:00", "source": "User", "createdByEmail": "security@example.com", "assessment": { "assessment": "InTriage", "detail": "Checking whether the affected code path is reachable." } } ] } } } } } }, "404": { "description": "Vulnerability finding not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Vulnerabilities: write" ] } ] } }, "/workspaces/{workspaceId}/vulnerable-firmware-versions": { "get": { "tags": [ "Vulnerability findings" ], "summary": "List vulnerable firmware versions", "operationId": "GET-workspaces-{workspaceId}-vulnerable-firmware-versions", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List vulnerable firmware versions": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "responses": { "200": { "description": "Firmware versions with at least one vulnerability finding.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VulnerableFirmwareVersionItem" } }, "examples": { "List vulnerable firmware versions": { "description": "Firmware versions with at least one active vulnerability finding.", "value": [ { "firmwareId": "q8Fd53pLn1Yr", "firmwareName": "Thermostat application", "firmwareVersionId": "r2Kt75mXc8Vd", "firmwareVersionName": "2.4.1", "createdAt": "2026-01-10T15:30:00+00:00", "vulnerabilitySummary": { "totalActiveIssues": 3, "countsBySeverity": [ { "severity": "Critical", "count": 1 }, { "severity": "High", "count": 2 } ], "affectedDeviceCount": 218, "lastEvaluatedAt": "2026-01-12T02:00:00+00:00" } } ] } } } } } }, "security": [ { "API key": [ "Vulnerabilities: read" ] } ] } }, "/workspaces/{workspaceId}/firmware-versions/{firmwareVersionId}/vulnerability-findings/summary": { "get": { "tags": [ "Vulnerability findings" ], "summary": "Get vulnerability summary of firmware version", "operationId": "GET-workspaces-{workspaceId}-firmware-versions-{firmwareVersionId}-vulnerability-findings-summary", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get vulnerability summary of firmware version": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareVersionId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get vulnerability summary of firmware version": { "description": "Firmware version ID.", "value": "r2Kt75mXc8Vd" } } } ], "responses": { "200": { "description": "Vulnerability finding counts per severity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmwareVersionVulnerabilitySummary" }, "examples": { "Get vulnerability summary of firmware version": { "description": "Vulnerability summary of the firmware version.", "value": { "totalActiveIssues": 3, "countsBySeverity": [ { "severity": "Critical", "count": 1 }, { "severity": "High", "count": 2 } ], "affectedDeviceCount": 218, "knownCisaExploitCount": 0, "lastEvaluatedAt": "2026-01-12T02:00:00+00:00" } } } } } }, "404": { "description": "Firmware version not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Vulnerabilities: read" ] } ] } }, "/workspaces/{workspaceId}/firmwares/{firmwareId}/symbol-files": { "post": { "tags": [ "Symbol files" ], "summary": "Upload symbol file", "operationId": "POST-workspaces-{workspaceId}-firmwares-{firmwareId}-symbol-files", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Upload symbol file": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Upload symbol file": { "description": "Firmware ID.", "value": "q8Fd53pLn1Yr" } } } ], "responses": { "200": { "description": "Created symbol file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SymbolFile" }, "examples": { "Upload symbol file": { "description": "Uploaded symbol file.", "value": { "id": "f1Lk64dHs7Xa", "alias": "thermostat-application-2.4.1", "buildIdParsingState": "InProgress", "createdAt": "2026-01-10T15:32:00+00:00", "firmwareVersions": [ { "id": "r2Kt75mXc8Vd", "name": "2.4.1" } ], "firmware": { "id": "q8Fd53pLn1Yr", "name": "Thermostat application" }, "os": "Zephyr" } } } } } }, "400": { "description": "Upload is not valid, or the file is not a supported symbol file.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Firmware not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Symbol files: write" ] } ] }, "get": { "tags": [ "Symbol files" ], "summary": "List symbol files", "operationId": "GET-workspaces-{workspaceId}-firmwares-{firmwareId}-symbol-files", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List symbol files": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List symbol files": { "description": "Firmware ID.", "value": "q8Fd53pLn1Yr" } } } ], "responses": { "200": { "description": "All symbol files of the firmware.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SymbolFileListItem" } }, "examples": { "List symbol files": { "description": "All symbol files of the firmware.", "value": [ { "id": "f1Lk64dHs7Xa", "alias": "thermostat-application-2.4.1", "buildId": "8f3a1c9e2b7d4506", "buildIdParsingState": "Succeeded", "createdAt": "2026-01-10T15:32:00+00:00", "firmwareVersions": [ { "id": "r2Kt75mXc8Vd", "name": "2.4.1" } ] } ] } } } } }, "404": { "description": "Firmware not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Symbol files: read" ] } ] } }, "/workspaces/{workspaceId}/firmwares/{firmwareId}/symbol-files/{symbolFileId}": { "put": { "tags": [ "Symbol files" ], "summary": "Update symbol file", "operationId": "PUT-workspaces-{workspaceId}-firmwares-{firmwareId}-symbol-files-{symbolFileId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Update symbol file": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Update symbol file": { "description": "Firmware ID.", "value": "q8Fd53pLn1Yr" } } }, { "name": "symbolFileId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Update symbol file": { "description": "Symbol file ID.", "value": "f1Lk64dHs7Xa" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSymbolFileCommand" }, "examples": { "Update symbol file": { "value": { "alias": "thermostat-application-2.4.1", "firmwareVersionIds": [ "r2Kt75mXc8Vd" ] } } } } }, "required": true }, "responses": { "200": { "description": "Updated symbol file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SymbolFile" }, "examples": { "Update symbol file": { "description": "Updated symbol file.", "value": { "id": "f1Lk64dHs7Xa", "alias": "thermostat-application-2.4.1", "buildId": "8f3a1c9e2b7d4506", "buildIdParsingState": "Succeeded", "createdAt": "2026-01-10T15:32:00+00:00", "firmwareVersions": [ { "id": "r2Kt75mXc8Vd", "name": "2.4.1" } ], "firmware": { "id": "q8Fd53pLn1Yr", "name": "Thermostat application" }, "os": "Zephyr" } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Firmware or symbol file not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Symbol files: write" ] } ] }, "delete": { "tags": [ "Symbol files" ], "summary": "Delete symbol file", "operationId": "DELETE-workspaces-{workspaceId}-firmwares-{firmwareId}-symbol-files-{symbolFileId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Delete symbol file": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Delete symbol file": { "description": "Firmware ID.", "value": "q8Fd53pLn1Yr" } } }, { "name": "symbolFileId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Delete symbol file": { "description": "Symbol file ID.", "value": "f1Lk64dHs7Xa" } } } ], "responses": { "204": { "description": "Symbol file deleted." }, "404": { "description": "Firmware or symbol file not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Symbol files: write" ] } ] } }, "/workspaces/{workspaceId}/symbol-files/{symbolFileId}": { "get": { "tags": [ "Symbol files" ], "summary": "Get symbol file content link", "operationId": "GET-workspaces-{workspaceId}-symbol-files-{symbolFileId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get symbol file content link": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "symbolFileId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get symbol file content link": { "description": "Symbol file ID.", "value": "f1Lk64dHs7Xa" } } } ], "responses": { "200": { "description": "Time-limited link to the symbol file content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SymbolFileContentResponse" }, "examples": { "Get symbol file content link": { "description": "Time-limited link to the symbol file.", "value": { "contentSasLink": "https://storage.spotflow.io/symbol-files/f1Lk64dHs7Xa.elf?sv=2025-01-01&sig=example" } } } } } }, "404": { "description": "Symbol file not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Symbol files: read" ] } ] } }, "/workspaces/{workspaceId}/symbol-files/build-id/{buildId}/metadata": { "get": { "tags": [ "Symbol files" ], "summary": "Get symbol file metadata by build ID", "operationId": "GET-workspaces-{workspaceId}-symbol-files-build-id-{buildId}-metadata", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get symbol file metadata by build ID": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "buildId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get symbol file metadata by build ID": { "description": "Build ID parsed from the symbol file.", "value": "8f3a1c9e2b7d4506" } } } ], "responses": { "200": { "description": "Symbol file metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SymbolFile" }, "examples": { "Get symbol file metadata by build ID": { "description": "Symbol file matching the build ID.", "value": { "id": "f1Lk64dHs7Xa", "alias": "thermostat-application-2.4.1", "buildId": "8f3a1c9e2b7d4506", "buildIdParsingState": "Succeeded", "createdAt": "2026-01-10T15:32:00+00:00", "firmwareVersions": [ { "id": "r2Kt75mXc8Vd", "name": "2.4.1" } ], "firmware": { "id": "q8Fd53pLn1Yr", "name": "Thermostat application" }, "os": "Zephyr" } } } } } }, "204": { "description": "No symbol file matches the build ID." } }, "security": [ { "API key": [ "Symbol files: read" ] } ] } }, "/workspaces/{workspaceId}/deployment-cohorts": { "get": { "tags": [ "Deployment cohorts" ], "summary": "List deployment cohorts", "operationId": "GET-workspaces-{workspaceId}-deployment-cohorts", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List deployment cohorts": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "responses": { "200": { "description": "All deployment cohorts in the workspace.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeploymentCohortListItem" } }, "examples": { "List deployment cohorts": { "description": "All deployment cohorts in the workspace.", "value": [ { "id": "m3Yg84tDx7Rn", "name": "Field test devices", "createdAt": "2026-01-07T10:00:00+00:00", "deviceCount": 24 }, { "id": "n9Ac37zEv2Hq", "name": "Production rollout", "createdAt": "2026-01-09T13:20:00+00:00", "deviceCount": 1840 } ] } } } } } }, "security": [ { "API key": [ "Deployments: read" ] } ] }, "post": { "tags": [ "Deployment cohorts" ], "summary": "Create deployment cohort", "operationId": "POST-workspaces-{workspaceId}-deployment-cohorts", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Create deployment cohort": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeploymentCohortCommand" }, "examples": { "Create deployment cohort": { "value": { "name": "Field test devices", "deviceIds": [ "thermostat-0042", "thermostat-0117" ], "filter": { "deviceId": [ { "contains": "thermostat" } ], "tags": [ { "tagName": "environment", "equals": "field-test" } ] } } } } } }, "required": true }, "responses": { "200": { "description": "Created deployment cohort.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentCohort" }, "examples": { "Create deployment cohort": { "description": "Created deployment cohort.", "value": { "id": "m3Yg84tDx7Rn", "name": "Field test devices", "createdAt": "2026-01-07T10:00:00+00:00" } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Deployment cohort with the same name already exists.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Deployments: write" ] } ] } }, "/workspaces/{workspaceId}/deployment-cohorts/{deploymentCohortId}": { "put": { "tags": [ "Deployment cohorts" ], "summary": "Update deployment cohort", "operationId": "PUT-workspaces-{workspaceId}-deployment-cohorts-{deploymentCohortId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Update deployment cohort": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deploymentCohortId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Update deployment cohort": { "description": "Deployment cohort ID.", "value": "m3Yg84tDx7Rn" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDeploymentCohortCommand" }, "examples": { "Update deployment cohort": { "value": { "name": "Field test devices (EU)" } } } } }, "required": true }, "responses": { "200": { "description": "Updated deployment cohort.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentCohort" }, "examples": { "Update deployment cohort": { "description": "Updated deployment cohort.", "value": { "id": "m3Yg84tDx7Rn", "name": "Field test devices (EU)", "createdAt": "2026-01-07T10:00:00+00:00" } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Deployment cohort not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Deployment cohort was modified concurrently.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Deployments: write" ] } ] }, "delete": { "tags": [ "Deployment cohorts" ], "summary": "Delete deployment cohort", "operationId": "DELETE-workspaces-{workspaceId}-deployment-cohorts-{deploymentCohortId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Delete deployment cohort": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deploymentCohortId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Delete deployment cohort": { "description": "Deployment cohort ID.", "value": "m3Yg84tDx7Rn" } } } ], "responses": { "204": { "description": "Deployment cohort deleted." }, "404": { "description": "Deployment cohort not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Deployment cohort has an active deployment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Deployments: write" ] } ] } }, "/workspaces/{workspaceId}/deployment-cohorts/{deploymentCohortId}/devices/add": { "post": { "tags": [ "Deployment cohorts" ], "summary": "Add devices to deployment cohort", "operationId": "POST-workspaces-{workspaceId}-deployment-cohorts-{deploymentCohortId}-devices-add", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Add devices to deployment cohort": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deploymentCohortId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Add devices to deployment cohort": { "description": "Deployment cohort ID.", "value": "m3Yg84tDx7Rn" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDevicesToDeploymentCohortCommand" }, "examples": { "Add devices to deployment cohort": { "value": { "deviceIds": [ "thermostat-0231" ], "filter": { "deviceId": [ { "contains": "thermostat" } ], "tags": [ { "tagName": "environment", "equals": "field-test" } ] } } } } } }, "required": true }, "responses": { "200": { "description": "Deployment cohort with the added devices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentCohort" }, "examples": { "Add devices to deployment cohort": { "description": "Deployment cohort the devices were added to.", "value": { "id": "m3Yg84tDx7Rn", "name": "Field test devices", "createdAt": "2026-01-07T10:00:00+00:00" } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Deployment cohort not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Deployment cohort was modified concurrently.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Deployments: write" ] } ] } }, "/workspaces/{workspaceId}/deployment-cohorts/{deploymentCohortId}/devices/remove": { "post": { "tags": [ "Deployment cohorts" ], "summary": "Remove devices from deployment cohort", "operationId": "POST-workspaces-{workspaceId}-deployment-cohorts-{deploymentCohortId}-devices-remove", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Remove devices from deployment cohort": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deploymentCohortId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Remove devices from deployment cohort": { "description": "Deployment cohort ID.", "value": "m3Yg84tDx7Rn" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveDevicesFromDeploymentCohortCommand" }, "examples": { "Remove devices from deployment cohort": { "value": { "deviceIds": [ "thermostat-0117" ] } } } } }, "required": true }, "responses": { "200": { "description": "Deployment cohort without the removed devices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentCohort" }, "examples": { "Remove devices from deployment cohort": { "description": "Deployment cohort the devices were removed from.", "value": { "id": "m3Yg84tDx7Rn", "name": "Field test devices", "createdAt": "2026-01-07T10:00:00+00:00" } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Deployment cohort not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Deployments: write" ] } ] } }, "/workspaces/{workspaceId}/deployment-cohorts/{deploymentCohortId}/deployments": { "post": { "tags": [ "Deployments" ], "summary": "Create deployment", "operationId": "POST-workspaces-{workspaceId}-deployment-cohorts-{deploymentCohortId}-deployments", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Create deployment": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deploymentCohortId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Create deployment": { "description": "Deployment cohort ID.", "value": "m3Yg84tDx7Rn" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeploymentCommand" }, "examples": { "Create deployment": { "value": { "name": "Roll out 2.4.1", "artifacts": [ { "firmware": { "firmwareVersionId": "r2Kt75mXc8Vd", "isMain": true } } ] } } } } }, "required": true }, "responses": { "200": { "description": "Created deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" }, "examples": { "Create deployment": { "description": "Created deployment.", "value": { "id": "p6Bh19qSj5Fw", "name": "Roll out 2.4.1", "deploymentCohortId": "m3Yg84tDx7Rn", "createdAt": "2026-01-12T09:00:00+00:00", "isActive": true, "artifacts": [ { "id": "s4Jm62wQb7Nz", "order": 0, "firmware": { "isMain": true, "slug": "main-application", "firmwareVersion": { "id": "r2Kt75mXc8Vd", "name": "2.4.1", "firmware": { "id": "q8Fd53pLn1Yr", "name": "Thermostat application" } } } } ], "deviceUpdateStateCounts": { "pending": 4, "inProgress": 2, "succeeded": 17, "failed": 1, "cancelled": 0 } } } } } } }, "400": { "description": "Command is not valid, or the firmware version has no uploaded image.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Deployment cohort or firmware version not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Deployments: write" ] } ] }, "get": { "tags": [ "Deployments" ], "summary": "List deployments", "operationId": "GET-workspaces-{workspaceId}-deployment-cohorts-{deploymentCohortId}-deployments", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List deployments": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deploymentCohortId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List deployments": { "description": "Deployment cohort ID.", "value": "m3Yg84tDx7Rn" } } } ], "responses": { "200": { "description": "All deployments of the deployment cohort.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Deployment" } }, "examples": { "List deployments": { "description": "All deployments of the deployment cohort.", "value": [ { "id": "p6Bh19qSj5Fw", "name": "Roll out 2.4.1", "deploymentCohortId": "m3Yg84tDx7Rn", "createdAt": "2026-01-12T09:00:00+00:00", "isActive": true, "artifacts": [ { "id": "s4Jm62wQb7Nz", "order": 0, "firmware": { "isMain": true, "slug": "main-application", "firmwareVersion": { "id": "r2Kt75mXc8Vd", "name": "2.4.1", "firmware": { "id": "q8Fd53pLn1Yr", "name": "Thermostat application" } } } } ], "deviceUpdateStateCounts": { "pending": 4, "inProgress": 2, "succeeded": 17, "failed": 1, "cancelled": 0 } } ] } } } } }, "404": { "description": "Deployment cohort not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Deployments: read" ] } ] } }, "/workspaces/{workspaceId}/deployment-cohorts/{deploymentCohortId}/deployments/{deploymentId}": { "put": { "tags": [ "Deployments" ], "summary": "Update deployment", "operationId": "PUT-workspaces-{workspaceId}-deployment-cohorts-{deploymentCohortId}-deployments-{deploymentId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Update deployment": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deploymentCohortId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Update deployment": { "description": "Deployment cohort ID.", "value": "m3Yg84tDx7Rn" } } }, { "name": "deploymentId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Update deployment": { "description": "Deployment ID.", "value": "p6Bh19qSj5Fw" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDeploymentCommand" }, "examples": { "Update deployment": { "value": { "name": "Roll out 2.4.1 (EU)" } } } } }, "required": true }, "responses": { "200": { "description": "Updated deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" }, "examples": { "Update deployment": { "description": "Updated deployment.", "value": { "id": "p6Bh19qSj5Fw", "name": "Roll out 2.4.1", "deploymentCohortId": "m3Yg84tDx7Rn", "createdAt": "2026-01-12T09:00:00+00:00", "isActive": true, "artifacts": [ { "id": "s4Jm62wQb7Nz", "order": 0, "firmware": { "isMain": true, "slug": "main-application", "firmwareVersion": { "id": "r2Kt75mXc8Vd", "name": "2.4.1", "firmware": { "id": "q8Fd53pLn1Yr", "name": "Thermostat application" } } } } ], "deviceUpdateStateCounts": { "pending": 4, "inProgress": 2, "succeeded": 17, "failed": 1, "cancelled": 0 } } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Deployment cohort or deployment not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Deployments: write" ] } ] }, "get": { "tags": [ "Deployments" ], "summary": "Get deployment", "operationId": "GET-workspaces-{workspaceId}-deployment-cohorts-{deploymentCohortId}-deployments-{deploymentId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get deployment": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deploymentCohortId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get deployment": { "description": "Deployment cohort ID.", "value": "m3Yg84tDx7Rn" } } }, { "name": "deploymentId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get deployment": { "description": "Deployment ID.", "value": "p6Bh19qSj5Fw" } } } ], "responses": { "200": { "description": "Deployment detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" }, "examples": { "Get deployment": { "description": "Deployment detail.", "value": { "id": "p6Bh19qSj5Fw", "name": "Roll out 2.4.1", "deploymentCohortId": "m3Yg84tDx7Rn", "createdAt": "2026-01-12T09:00:00+00:00", "isActive": true, "artifacts": [ { "id": "s4Jm62wQb7Nz", "order": 0, "firmware": { "isMain": true, "slug": "main-application", "firmwareVersion": { "id": "r2Kt75mXc8Vd", "name": "2.4.1", "firmware": { "id": "q8Fd53pLn1Yr", "name": "Thermostat application" } } } } ], "deviceUpdateStateCounts": { "pending": 4, "inProgress": 2, "succeeded": 17, "failed": 1, "cancelled": 0 } } } } } } }, "404": { "description": "Deployment cohort or deployment not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Deployments: read" ] } ] } }, "/workspaces/{workspaceId}/deployment-cohorts/{deploymentCohortId}/deployments/{deploymentId}/device-updates/{deviceId}/retry": { "post": { "tags": [ "Deployments" ], "summary": "Retry device update", "operationId": "POST-workspaces-{workspaceId}-deployment-cohorts-{deploymentCohortId}-deployments-{deploymentId}-device-updates-{deviceId}-retry", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Retry device update": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deploymentCohortId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Retry device update": { "description": "Deployment cohort ID.", "value": "m3Yg84tDx7Rn" } } }, { "name": "deploymentId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Retry device update": { "description": "Deployment ID.", "value": "p6Bh19qSj5Fw" } } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Retry device update": { "description": "Device ID.", "value": "thermostat-0042" } } } ], "responses": { "200": { "description": "New update attempt created for the device.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceUpdateAttempt" }, "examples": { "Retry device update": { "description": "Update attempt created by the retry.", "value": { "id": 1042, "deviceId": "thermostat-0042", "deploymentId": "p6Bh19qSj5Fw", "createdAt": "2026-01-12T09:05:00+00:00", "state": "InProgress", "manifestSentToDeviceAt": "2026-01-12T09:05:02+00:00", "lastArtifactStateChangedAt": "2026-01-12T09:07:41+00:00", "artifacts": [ { "id": "t7Ln28xRg4Cp", "deploymentArtifactId": "s4Jm62wQb7Nz", "state": "InProgress", "firmware": { "isMain": true, "slug": "main-application", "firmwareVersion": { "id": "r2Kt75mXc8Vd", "name": "2.4.1", "firmware": { "id": "q8Fd53pLn1Yr", "name": "Thermostat application" } } } } ] } } } } } }, "404": { "description": "Deployment cohort, deployment or device not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Deployment is not active, or the device update cannot be retried.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Deployments: write" ] } ] } }, "/workspaces/{workspaceId}/deployment-cohorts/{deploymentCohortId}/deployments/{deploymentId}/stop": { "post": { "tags": [ "Deployments" ], "summary": "Stop deployment", "operationId": "POST-workspaces-{workspaceId}-deployment-cohorts-{deploymentCohortId}-deployments-{deploymentId}-stop", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Stop deployment": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deploymentCohortId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Stop deployment": { "description": "Deployment cohort ID.", "value": "m3Yg84tDx7Rn" } } }, { "name": "deploymentId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Stop deployment": { "description": "Deployment ID.", "value": "p6Bh19qSj5Fw" } } } ], "responses": { "200": { "description": "Stopped deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" }, "examples": { "Stop deployment": { "description": "Stopped deployment.", "value": { "id": "p6Bh19qSj5Fw", "name": "Roll out 2.4.1", "deploymentCohortId": "m3Yg84tDx7Rn", "createdAt": "2026-01-12T09:00:00+00:00", "isActive": false, "endedAt": "2026-01-12T11:30:00+00:00", "artifacts": [ { "id": "s4Jm62wQb7Nz", "order": 0, "firmware": { "isMain": true, "slug": "main-application", "firmwareVersion": { "id": "r2Kt75mXc8Vd", "name": "2.4.1", "firmware": { "id": "q8Fd53pLn1Yr", "name": "Thermostat application" } } } } ], "deviceUpdateStateCounts": { "pending": 0, "inProgress": 0, "succeeded": 18, "failed": 1, "cancelled": 5 } } } } } } }, "404": { "description": "Deployment cohort or deployment not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Deployment is not active.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Deployments: write" ] } ] } }, "/workspaces/{workspaceId}/deployment-cohorts/{deploymentCohortId}/deployments/{deploymentId}/rollback": { "post": { "tags": [ "Deployments" ], "summary": "Roll back deployment", "operationId": "POST-workspaces-{workspaceId}-deployment-cohorts-{deploymentCohortId}-deployments-{deploymentId}-rollback", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Roll back deployment": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deploymentCohortId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Roll back deployment": { "description": "Deployment cohort ID.", "value": "m3Yg84tDx7Rn" } } }, { "name": "deploymentId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Roll back deployment": { "description": "Deployment ID.", "value": "p6Bh19qSj5Fw" } } } ], "responses": { "200": { "description": "Rolled back deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deployment" }, "examples": { "Roll back deployment": { "description": "Deployment created to roll the devices back to the previous firmware version.", "value": { "id": "u1Dq46yTk3Bs", "name": "Roll back of Roll out 2.4.1", "deploymentCohortId": "m3Yg84tDx7Rn", "createdAt": "2026-01-12T11:35:00+00:00", "isActive": true, "artifacts": [ { "id": "v5Gp83hMz2Xf", "order": 0, "firmware": { "isMain": true, "slug": "main-application", "firmwareVersion": { "id": "w9Rc14sNv6Jd", "name": "2.4.0", "firmware": { "id": "q8Fd53pLn1Yr", "name": "Thermostat application" } } } } ], "deviceUpdateStateCounts": { "pending": 18, "inProgress": 0, "succeeded": 0, "failed": 0, "cancelled": 0 } } } } } } }, "404": { "description": "Deployment cohort or deployment not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Deployments: write" ] } ] } }, "/workspaces/{workspaceId}/deployment-cohorts/{deploymentCohortId}/deployments/{deploymentId}/device-updates/list": { "post": { "tags": [ "Deployments" ], "summary": "List device updates", "operationId": "POST-workspaces-{workspaceId}-deployment-cohorts-{deploymentCohortId}-deployments-{deploymentId}-device-updates-list", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List failed device updates": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deploymentCohortId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List failed device updates": { "description": "Deployment cohort ID.", "value": "m3Yg84tDx7Rn" } } }, { "name": "deploymentId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List failed device updates": { "description": "Deployment ID.", "value": "p6Bh19qSj5Fw" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDeviceUpdatesCommand" }, "examples": { "List failed device updates": { "value": { "sortColumn": "DeviceId", "ascending": true, "limit": 50, "filter": { "deviceId": [ { "contains": "thermostat" } ], "state": [ "Failed", "InProgress" ] } } } } } }, "required": true }, "responses": { "200": { "description": "Matching device updates with a pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDeviceUpdatesResponse" }, "examples": { "List failed device updates": { "description": "Page of device updates of the deployment.", "value": { "deviceUpdates": [ { "deviceId": "thermostat-0042", "state": "InProgress", "attempts": [ { "id": 1042, "deviceId": "thermostat-0042", "deploymentId": "p6Bh19qSj5Fw", "createdAt": "2026-01-12T09:05:00+00:00", "state": "InProgress", "manifestSentToDeviceAt": "2026-01-12T09:05:02+00:00", "lastArtifactStateChangedAt": "2026-01-12T09:07:41+00:00", "artifacts": [ { "id": "t7Ln28xRg4Cp", "deploymentArtifactId": "s4Jm62wQb7Nz", "state": "InProgress", "firmware": { "isMain": true, "slug": "main-application", "firmwareVersion": { "id": "r2Kt75mXc8Vd", "name": "2.4.1", "firmware": { "id": "q8Fd53pLn1Yr", "name": "Thermostat application" } } } } ] } ] } ], "hasMore": false } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Deployment cohort or deployment not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Deployments: read" ] } ] } }, "/workspaces/{workspaceId}/notification-targets": { "post": { "tags": [ "Notification targets" ], "summary": "Create notification target", "operationId": "POST-workspaces-{workspaceId}-notification-targets", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Create notification target": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNotificationTargetCommand" }, "examples": { "Create notification target": { "value": { "name": "On-call e-mail", "type": "Email", "emailAddresses": [ "on-call@example.com", "platform-team@example.com" ] } } } } }, "required": true }, "responses": { "200": { "description": "Created notification target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationTarget" }, "examples": { "Create notification target": { "description": "Created notification target.", "value": { "id": "n4Tg81vBz6Rw", "name": "On-call e-mail", "type": "Email", "state": "Enabled", "emailAddresses": [ "on-call@example.com", "platform-team@example.com" ], "alertRuleCount": 0 } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: write" ] } ] }, "get": { "tags": [ "Notification targets" ], "summary": "List notification targets", "operationId": "GET-workspaces-{workspaceId}-notification-targets", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List notification targets": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "responses": { "200": { "description": "All notification targets in the workspace.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationTarget" } }, "examples": { "List notification targets": { "description": "All notification targets in the workspace.", "value": [ { "id": "n4Tg81vBz6Rw", "name": "On-call e-mail", "type": "Email", "state": "Enabled", "emailAddresses": [ "on-call@example.com", "platform-team@example.com" ], "alertRuleCount": 4 } ] } } } } } }, "security": [ { "API key": [ "Alerts: read" ] } ] } }, "/workspaces/{workspaceId}/notification-targets/{notificationTargetId}": { "get": { "tags": [ "Notification targets" ], "summary": "Get notification target", "operationId": "GET-workspaces-{workspaceId}-notification-targets-{notificationTargetId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get notification target": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "notificationTargetId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get notification target": { "description": "Notification target ID.", "value": "n4Tg81vBz6Rw" } } } ], "responses": { "200": { "description": "Notification target detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationTarget" }, "examples": { "Get notification target": { "description": "Notification target detail.", "value": { "id": "n4Tg81vBz6Rw", "name": "On-call e-mail", "type": "Email", "state": "Enabled", "emailAddresses": [ "on-call@example.com", "platform-team@example.com" ], "alertRuleCount": 4 } } } } } }, "404": { "description": "Notification target not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: read" ] } ] }, "put": { "tags": [ "Notification targets" ], "summary": "Update notification target", "operationId": "PUT-workspaces-{workspaceId}-notification-targets-{notificationTargetId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Disable notification target": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "notificationTargetId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Disable notification target": { "description": "Notification target ID.", "value": "n4Tg81vBz6Rw" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNotificationTargetCommand" }, "examples": { "Disable notification target": { "value": { "name": "On-call e-mail", "type": "Email", "state": "Disabled", "emailAddresses": [ "on-call@example.com" ] } } } } }, "required": true }, "responses": { "200": { "description": "Updated notification target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationTarget" }, "examples": { "Disable notification target": { "description": "Updated notification target.", "value": { "id": "n4Tg81vBz6Rw", "name": "On-call e-mail", "type": "Email", "state": "Disabled", "emailAddresses": [ "on-call@example.com" ], "alertRuleCount": 4 } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Notification target not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: write" ] } ] }, "delete": { "tags": [ "Notification targets" ], "summary": "Delete notification target", "operationId": "DELETE-workspaces-{workspaceId}-notification-targets-{notificationTargetId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Delete notification target": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "notificationTargetId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Delete notification target": { "description": "Notification target ID.", "value": "n4Tg81vBz6Rw" } } } ], "responses": { "204": { "description": "Notification target deleted." }, "404": { "description": "Notification target not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: write" ] } ] } }, "/workspaces/{workspaceId}/metrics/system": { "post": { "tags": [ "Metrics" ], "summary": "Run a built-in metric query", "description": "Runs one of the built-in queries behind the Spotflow dashboards. See [Built-in Metric Queries](https://docs.spotflow.io/api-reference/built-in-metric-queries) for the available query names and the parameters each one takes.", "operationId": "POST-workspaces-{workspaceId}-metrics-system", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Run a built-in metric query": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemMetricsCommand" }, "examples": { "Run a built-in metric query": { "value": { "queryName": "DeviceCountPerFirmware", "parameters": { "from": "2026-01-05T00:00:00+00:00", "to": "2026-01-12T00:00:00+00:00", "aggregation": "1d" } } } } } }, "required": true }, "responses": { "200": { "description": "Query result as columns and rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsQueryResponse" }, "examples": { "Run a built-in metric query": { "description": "Query result as columns and rows.", "value": { "effectiveAggregation": "1d", "columns": [ { "name": "Timestamp", "type": "DateTimeOffset" }, { "name": "Firmware", "type": "String" }, { "name": "Version", "type": "String" }, { "name": "DeviceCount", "type": "Number" } ], "rows": [ [ "2026-01-10T00:00:00+00:00", "Thermostat application", "2.4.0", 1622 ], [ "2026-01-10T00:00:00+00:00", "Thermostat application", "2.4.1", 218 ], [ "2026-01-11T00:00:00+00:00", "Thermostat application", "2.4.1", 1840 ] ] } } } } } }, "400": { "description": "Query failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Metrics: read" ] } ] } }, "/workspaces/{workspaceId}/metrics/custom": { "post": { "tags": [ "Metrics" ], "summary": "Query metrics", "description": "Aggregates any ingested metric, system or custom, with a query written in a subset of the Kusto Query Language (KQL). See [Metrics Query Syntax](https://docs.spotflow.io/api-reference/metrics-query-syntax) for the supported operators, functions, and limits.", "operationId": "POST-workspaces-{workspaceId}-metrics-custom", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Query metrics": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomMetricsCommand" }, "examples": { "Query metrics": { "value": { "query": "metrics | where metric_name == 'unlock_duration_ms' | summarize avg(value) by bin(timestamp, 1h)", "from": "2026-01-12T00:00:00+00:00", "to": "2026-01-13T00:00:00+00:00" } } } } }, "required": true }, "responses": { "200": { "description": "Query result as columns and rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsQueryResponse" }, "examples": { "Query metrics": { "description": "Query result as columns and rows.", "value": { "columns": [ { "name": "timestamp", "type": "DateTimeOffset" }, { "name": "value", "type": "Number" } ], "rows": [ [ "2026-01-12T12:00:00+00:00", 412.7 ], [ "2026-01-12T13:00:00+00:00", 398.2 ] ] } } } } } }, "400": { "description": "Query failed. The `diagnostics` extension carries the query diagnostics.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Metrics: read" ] } ] } }, "/workspaces/{workspaceId}/metrics": { "get": { "tags": [ "Metrics" ], "summary": "List metric names", "operationId": "GET-workspaces-{workspaceId}-metrics", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List metric names": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "responses": { "200": { "description": "Names of all metrics in the workspace, including system metrics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsListResponse" }, "examples": { "List metric names": { "description": "Names of all metrics in the workspace, including system metrics.", "value": { "metricNames": [ "battery_level", "cpu_utilization_percent", "heap_free_bytes", "unlock_attempt", "unlock_duration_ms" ] } } } } } } }, "security": [ { "API key": [ "Metrics: read" ] } ] } }, "/workspaces/{workspaceId}/metrics/{metricName}/labels/keys": { "get": { "tags": [ "Metrics" ], "summary": "List metric label keys", "operationId": "GET-workspaces-{workspaceId}-metrics-{metricName}-labels-keys", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List metric label keys": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "metricName", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List metric label keys": { "description": "Metric name.", "value": "unlock_duration_ms" } } } ], "responses": { "200": { "description": "Label keys used by the metric.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricLabelKeysResponse" }, "examples": { "List metric label keys": { "description": "Label keys used by the metric.", "value": { "labelKeys": [ "mechanism", "result" ] } } } } } } }, "security": [ { "API key": [ "Metrics: read" ] } ] } }, "/workspaces/{workspaceId}/metrics/{metricName}/labels/keys/{labelKey}/values": { "get": { "tags": [ "Metrics" ], "summary": "List metric label values", "operationId": "GET-workspaces-{workspaceId}-metrics-{metricName}-labels-keys-{labelKey}-values", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List metric label values": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "metricName", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List metric label values": { "description": "Metric name.", "value": "unlock_duration_ms" } } }, { "name": "labelKey", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List metric label values": { "description": "Label key.", "value": "mechanism" } } } ], "responses": { "200": { "description": "Values used for the label key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricLabelValuesResponse" }, "examples": { "List metric label values": { "description": "Values used for the label key of the metric.", "value": { "labelValues": [ "keypad", "nfc", "mobile-app" ] } } } } } } }, "security": [ { "API key": [ "Metrics: read" ] } ] } }, "/users/me/invites": { "get": { "tags": [ "User invites" ], "summary": "List invites for current user", "operationId": "GET-users-me-invites", "responses": { "200": { "description": "Pending invites addressed to the current user.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserInviteListItem" } } } } }, "401": { "description": "Caller has no email claim.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Personal invites: read" ] } ] } }, "/users/me/invites/{inviteId}": { "delete": { "tags": [ "User invites" ], "summary": "Decline invite", "operationId": "DELETE-users-me-invites-{inviteId}", "parameters": [ { "name": "inviteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Invite declined." }, "401": { "description": "Caller has no email claim.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Invite not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Personal invites: write" ] } ] } }, "/users/me/invites/{inviteId}/accept": { "post": { "tags": [ "User invites" ], "summary": "Accept invite", "operationId": "POST-users-me-invites-{inviteId}-accept", "parameters": [ { "name": "inviteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "ID of the workspace the user joined.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInviteResponse" } } } }, "401": { "description": "Caller has no user identity or email claim.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Invite not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Personal invites: write" ] } ] } }, "/workspaces/{workspaceId}/invites": { "post": { "tags": [ "Workspace members" ], "summary": "Create workspace invites", "description": "Sending an invite needs a user API key.", "operationId": "POST-workspaces-{workspaceId}-invites", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceInvitesCommand" } } }, "required": true }, "responses": { "200": { "description": "Created invites.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceInviteListItem" } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Workspace not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Workspace members: write" ] } ] }, "get": { "tags": [ "Workspace members" ], "summary": "List workspace invites", "operationId": "GET-workspaces-{workspaceId}-invites", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "All pending invites of the workspace.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceInviteListItem" } } } } } }, "security": [ { "API key": [ "Workspace members: read" ] } ] } }, "/workspaces/{workspaceId}/invites/{inviteId}": { "delete": { "tags": [ "Workspace members" ], "summary": "Delete workspace invite", "operationId": "DELETE-workspaces-{workspaceId}-invites-{inviteId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "inviteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Invite deleted." }, "404": { "description": "Invite not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Workspace members: write" ] } ] } }, "/workspaces/{workspaceId}/ingestion-keys": { "post": { "tags": [ "Ingestion keys" ], "summary": "Create ingestion key", "operationId": "POST-workspaces-{workspaceId}-ingestion-keys", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIngestionKeyCommand" } } }, "required": true }, "responses": { "200": { "description": "Created ingestion key, including its secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionKey" } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Ingest keys: write" ] } ] }, "get": { "tags": [ "Ingestion keys" ], "summary": "List ingestion keys", "operationId": "GET-workspaces-{workspaceId}-ingestion-keys", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "All ingestion keys in the workspace.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IngestionKeyListItem" } } } } } }, "security": [ { "API key": [ "Ingest keys: read" ] } ] } }, "/workspaces/{workspaceId}/ingestion-keys/{ingestionKeyId}": { "put": { "tags": [ "Ingestion keys" ], "summary": "Update ingestion key", "operationId": "PUT-workspaces-{workspaceId}-ingestion-keys-{ingestionKeyId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "ingestionKeyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIngestionKeyCommand" } } }, "required": true }, "responses": { "200": { "description": "Updated ingestion key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionKey" } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Ingestion key not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Ingest keys: write" ] } ] }, "delete": { "tags": [ "Ingestion keys" ], "summary": "Delete ingestion key", "operationId": "DELETE-workspaces-{workspaceId}-ingestion-keys-{ingestionKeyId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "ingestionKeyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Ingestion key deleted." }, "404": { "description": "Ingestion key not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Ingest keys: write" ] } ] }, "get": { "tags": [ "Ingestion keys" ], "summary": "Get ingestion key", "operationId": "GET-workspaces-{workspaceId}-ingestion-keys-{ingestionKeyId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "ingestionKeyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Ingestion key, including its secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionKey" } } } }, "404": { "description": "Ingestion key not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Ingest keys: read" ] } ] } }, "/workspaces/{workspaceId}/firmwares/{firmwareId}/versions": { "post": { "tags": [ "Firmware versions" ], "summary": "Create firmware version", "operationId": "POST-workspaces-{workspaceId}-firmwares-{firmwareId}-versions", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Create firmware version": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Create firmware version": { "description": "Firmware ID.", "value": "q8Fd53pLn1Yr" } } } ], "responses": { "200": { "description": "Created firmware version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmwareVersion" }, "examples": { "Create firmware version": { "description": "Created firmware version.", "value": { "id": "r2Kt75mXc8Vd", "name": "2.4.1", "createdAt": "2026-01-10T15:30:00+00:00", "assignedSymbolFilesCount": 0, "firmwareImageId": "y7Bs21fWn5Hk", "isUsedInDeployment": false, "deviceCount": 0 } } } } } }, "400": { "description": "Upload is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Firmware not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Firmware version with the same name already exists.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Firmwares: write" ] } ] }, "get": { "tags": [ "Firmware versions" ], "summary": "List firmware versions", "operationId": "GET-workspaces-{workspaceId}-firmwares-{firmwareId}-versions", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List firmware versions": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List firmware versions": { "description": "Firmware ID.", "value": "q8Fd53pLn1Yr" } } } ], "responses": { "200": { "description": "All versions of the firmware.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FirmwareVersionListItem" } }, "examples": { "List firmware versions": { "description": "All versions of the firmware.", "value": [ { "id": "r2Kt75mXc8Vd", "name": "2.4.1", "createdAt": "2026-01-10T15:30:00+00:00", "assignedSymbolFilesCount": 1, "firmwareImageId": "y7Bs21fWn5Hk", "isUsedInDeployment": true, "deviceCount": 218, "vulnerabilitySummary": { "totalActiveIssues": 3, "countsBySeverity": [ { "severity": "Critical", "count": 1 }, { "severity": "High", "count": 2 } ], "affectedDeviceCount": 218, "lastEvaluatedAt": "2026-01-12T02:00:00+00:00" } } ] } } } } }, "404": { "description": "Firmware not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Firmwares: read" ] } ] } }, "/workspaces/{workspaceId}/firmwares/{firmwareId}/versions/{firmwareVersionId}/image": { "post": { "tags": [ "Firmware versions" ], "summary": "Upload firmware image", "operationId": "POST-workspaces-{workspaceId}-firmwares-{firmwareId}-versions-{firmwareVersionId}-image", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Upload firmware image": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Upload firmware image": { "description": "Firmware ID.", "value": "q8Fd53pLn1Yr" } } }, { "name": "firmwareVersionId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Upload firmware image": { "description": "Firmware version ID.", "value": "r2Kt75mXc8Vd" } } } ], "responses": { "200": { "description": "Time-limited link to the uploaded firmware image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmwareImageContentResponse" }, "examples": { "Upload firmware image": { "description": "Time-limited link to the uploaded firmware image.", "value": { "contentSasLink": "https://storage.spotflow.io/firmware-images/y7Bs21fWn5Hk.bin?sv=2025-01-01&sig=example", "fileName": "thermostat-application-2.4.1.bin" } } } } } }, "400": { "description": "Upload is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Firmware or firmware version not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Firmware version is already used as a deployment artifact.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Firmwares: write" ] } ] }, "get": { "tags": [ "Firmware versions" ], "summary": "Get firmware image content link", "operationId": "GET-workspaces-{workspaceId}-firmwares-{firmwareId}-versions-{firmwareVersionId}-image", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get firmware image content link": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get firmware image content link": { "description": "Firmware ID.", "value": "q8Fd53pLn1Yr" } } }, { "name": "firmwareVersionId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get firmware image content link": { "description": "Firmware version ID.", "value": "r2Kt75mXc8Vd" } } } ], "responses": { "200": { "description": "Time-limited link to the firmware image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmwareImageContentResponse" }, "examples": { "Get firmware image content link": { "description": "Time-limited link to the firmware image.", "value": { "contentSasLink": "https://storage.spotflow.io/firmware-images/y7Bs21fWn5Hk.bin?sv=2025-01-01&sig=example", "fileName": "thermostat-application-2.4.1.bin" } } } } } }, "404": { "description": "Firmware, firmware version or firmware image not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Firmwares: read" ] } ] } }, "/workspaces/{workspaceId}/firmwares/{firmwareId}/versions/{firmwareVersionId}": { "put": { "tags": [ "Firmware versions" ], "summary": "Update firmware version", "operationId": "PUT-workspaces-{workspaceId}-firmwares-{firmwareId}-versions-{firmwareVersionId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Update firmware version": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Update firmware version": { "description": "Firmware ID.", "value": "q8Fd53pLn1Yr" } } }, { "name": "firmwareVersionId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Update firmware version": { "description": "Firmware version ID.", "value": "r2Kt75mXc8Vd" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFirmwareVersionCommand" }, "examples": { "Update firmware version": { "value": { "name": "2.4.2" } } } } }, "required": true }, "responses": { "200": { "description": "Updated firmware version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmwareVersion" }, "examples": { "Update firmware version": { "description": "Updated firmware version.", "value": { "id": "r2Kt75mXc8Vd", "name": "2.4.1", "createdAt": "2026-01-10T15:30:00+00:00", "assignedSymbolFilesCount": 1, "firmwareImageId": "y7Bs21fWn5Hk", "isUsedInDeployment": true, "deviceCount": 218 } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Firmware or firmware version not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Firmware version is used as a deployment artifact and cannot be renamed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Firmwares: write" ] } ] }, "delete": { "tags": [ "Firmware versions" ], "summary": "Delete firmware version", "operationId": "DELETE-workspaces-{workspaceId}-firmwares-{firmwareId}-versions-{firmwareVersionId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Delete firmware version": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Delete firmware version": { "description": "Firmware ID.", "value": "q8Fd53pLn1Yr" } } }, { "name": "firmwareVersionId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Delete firmware version": { "description": "Firmware version ID.", "value": "r2Kt75mXc8Vd" } } } ], "responses": { "204": { "description": "Firmware version deleted." }, "404": { "description": "Firmware or firmware version not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Firmware version is used as a deployment artifact.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Firmwares: write" ] } ] } }, "/workspaces/{workspaceId}/firmwares": { "post": { "tags": [ "Firmwares" ], "summary": "Create firmware", "operationId": "POST-workspaces-{workspaceId}-firmwares", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Create firmware": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFirmwareCommand" }, "examples": { "Create firmware": { "value": { "name": "Thermostat application", "slug": "thermostat-application" } } } } }, "required": true }, "responses": { "200": { "description": "Created firmware.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Firmware" }, "examples": { "Create firmware": { "description": "Created firmware.", "value": { "id": "q8Fd53pLn1Yr", "name": "Thermostat application", "slug": "thermostat-application", "createdAt": "2025-10-14T12:00:00+00:00", "versionsCount": 0, "isUsedInDeployment": false, "deviceCount": 0 } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Firmware with the same slug already exists.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Firmwares: write" ] } ] }, "get": { "tags": [ "Firmwares" ], "summary": "List firmwares", "operationId": "GET-workspaces-{workspaceId}-firmwares", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List firmwares": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "responses": { "200": { "description": "All firmwares in the workspace.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FirmwareListItem" } }, "examples": { "List firmwares": { "description": "All firmwares in the workspace.", "value": [ { "id": "q8Fd53pLn1Yr", "name": "Thermostat application", "slug": "thermostat-application", "createdAt": "2025-10-14T12:00:00+00:00", "versionsCount": 8, "deviceCount": 1840 }, { "id": "x4Th67kPw9Ln", "name": "Radio module", "slug": "radio-module", "createdAt": "2025-10-20T09:00:00+00:00", "versionsCount": 3, "deviceCount": 1840 } ] } } } } } }, "security": [ { "API key": [ "Firmwares: read" ] } ] } }, "/workspaces/{workspaceId}/firmwares/{firmwareId}": { "put": { "tags": [ "Firmwares" ], "summary": "Update firmware", "operationId": "PUT-workspaces-{workspaceId}-firmwares-{firmwareId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Update firmware": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Update firmware": { "description": "Firmware ID.", "value": "q8Fd53pLn1Yr" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFirmwareCommand" }, "examples": { "Update firmware": { "value": { "name": "Thermostat main application", "slug": "thermostat-application" } } } } }, "required": true }, "responses": { "200": { "description": "Updated firmware.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Firmware" }, "examples": { "Update firmware": { "description": "Updated firmware.", "value": { "id": "q8Fd53pLn1Yr", "name": "Thermostat main application", "slug": "thermostat-application", "createdAt": "2025-10-14T12:00:00+00:00", "versionsCount": 8, "isUsedInDeployment": true, "deviceCount": 1840 } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Firmware not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Firmware with the same slug already exists, or the slug is used as a deployment artifact.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Firmwares: write" ] } ] }, "get": { "tags": [ "Firmwares" ], "summary": "Get firmware", "operationId": "GET-workspaces-{workspaceId}-firmwares-{firmwareId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get firmware": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get firmware": { "description": "Firmware ID.", "value": "q8Fd53pLn1Yr" } } } ], "responses": { "200": { "description": "Firmware detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Firmware" }, "examples": { "Get firmware": { "description": "Firmware detail.", "value": { "id": "q8Fd53pLn1Yr", "name": "Thermostat application", "slug": "thermostat-application", "createdAt": "2025-10-14T12:00:00+00:00", "versionsCount": 8, "isUsedInDeployment": true, "deviceCount": 1840 } } } } } }, "404": { "description": "Firmware not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Firmwares: read" ] } ] }, "delete": { "tags": [ "Firmwares" ], "summary": "Delete firmware", "operationId": "DELETE-workspaces-{workspaceId}-firmwares-{firmwareId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Delete firmware": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "firmwareId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Delete firmware": { "description": "Firmware ID.", "value": "q8Fd53pLn1Yr" } } } ], "responses": { "204": { "description": "Firmware deleted." }, "404": { "description": "Firmware not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Firmware is used as a deployment artifact.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Firmwares: write" ] } ] } }, "/workspaces/{workspaceId}/events": { "post": { "tags": [ "Events" ], "summary": "List events", "operationId": "POST-workspaces-{workspaceId}-events", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List events": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsCommand" }, "examples": { "List events": { "value": { "filter": { "fromTimestamp": "2026-01-12T00:00:00+00:00", "toTimestamp": "2026-01-13T00:00:00+00:00", "severity": [ "Error", "Critical" ], "device": [ { "contains": "thermostat" } ], "body": [ { "contains": "timeout" } ], "eventType": [ "Log", "CrashReport" ], "labels": { "component": [ { "equals": "network" } ] }, "firmware": { "firmwareIds": [ "q8Fd53pLn1Yr" ], "firmwareVersionIds": [ "r2Kt75mXc8Vd" ] } }, "offset": 0, "limit": 100 } } } } }, "required": true }, "responses": { "200": { "description": "Matching events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsResponse" }, "examples": { "List events": { "description": "Events matching the filter.", "value": { "events": [ { "deviceId": "thermostat-0042", "timestamp": "2026-01-12T14:05:12.482+00:00", "deviceTimestampMs": 1768226712482, "deviceUptimeMs": 864320, "body": "Connection to broker timed out after 30000 ms", "bodyTemplate": "Connection to broker timed out after {} ms", "severity": "Error", "bodyTemplateValues": [ "30000" ], "labels": { "component": "network" }, "eventType": "Log", "coreDumpId": "", "crashReportId": "", "buildId": "8f3a1c9e2b7d4506", "sequenceNumber": 91422, "transportRoute": [ "mqtt" ] } ] } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Logs: read" ] } ] } }, "/workspaces/{workspaceId}/events/counts": { "post": { "tags": [ "Events" ], "summary": "Count events", "operationId": "POST-workspaces-{workspaceId}-events-counts", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Count events per hour": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsCountCommand" }, "examples": { "Count events per hour": { "value": { "filter": { "fromTimestamp": "2026-01-12T00:00:00+00:00", "toTimestamp": "2026-01-13T00:00:00+00:00", "severity": [ "Error", "Critical" ], "device": [ { "contains": "thermostat" } ], "body": [ { "contains": "timeout" } ], "eventType": [ "Log", "CrashReport" ], "labels": { "component": [ { "equals": "network" } ] }, "firmware": { "firmwareIds": [ "q8Fd53pLn1Yr" ], "firmwareVersionIds": [ "r2Kt75mXc8Vd" ] } }, "intervalSeconds": 3600 } } } } }, "required": true }, "responses": { "200": { "description": "Event counts per bucket and the total count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsCountResponse" }, "examples": { "Count events per hour": { "description": "Event counts per interval and severity.", "value": { "counts": [ { "count": 18, "timestamp": "2026-01-12T13:00:00+00:00", "severity": "Error" }, { "count": 2, "timestamp": "2026-01-12T13:00:00+00:00", "severity": "Critical" }, { "count": 25, "timestamp": "2026-01-12T14:00:00+00:00", "severity": "Error" } ], "totalCount": 45 } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Logs: read" ] } ] } }, "/workspaces/{workspaceId}/events/labels/keys": { "get": { "tags": [ "Events" ], "summary": "List event label keys", "operationId": "GET-workspaces-{workspaceId}-events-labels-keys", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List event label keys": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "responses": { "200": { "description": "Label keys used by events in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelKeysResponse" }, "examples": { "List event label keys": { "description": "Label keys used by events in the workspace.", "value": { "labelKeys": [ "component", "thread", "module" ] } } } } } } }, "security": [ { "API key": [ "Logs: read" ] } ] } }, "/workspaces/{workspaceId}/events/labels/{labelKey}/values": { "get": { "tags": [ "Events" ], "summary": "List event label values", "operationId": "GET-workspaces-{workspaceId}-events-labels-{labelKey}-values", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List event label values": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "labelKey", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List event label values": { "description": "Label key.", "value": "component" } } } ], "responses": { "200": { "description": "Values used for the label key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelValuesResponse" }, "examples": { "List event label values": { "description": "Values used for the label key in the workspace.", "value": { "labelValues": [ "network", "storage", "sensors" ] } } } } } } }, "security": [ { "API key": [ "Logs: read" ] } ] } }, "/workspaces/{workspaceId}/devices/{deviceId}": { "delete": { "tags": [ "Devices" ], "summary": "Delete device", "operationId": "DELETE-workspaces-{workspaceId}-devices-{deviceId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Delete device": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Delete device": { "description": "Device ID.", "value": "thermostat-0042" } } } ], "responses": { "204": { "description": "Device deleted." }, "404": { "description": "Device not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Devices: write" ] } ] }, "get": { "tags": [ "Devices" ], "summary": "Get device", "operationId": "GET-workspaces-{workspaceId}-devices-{deviceId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get device": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get device": { "description": "Device ID.", "value": "thermostat-0042" } } } ], "responses": { "200": { "description": "Device detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceDetail" }, "examples": { "Get device": { "description": "Device detail.", "value": { "deviceId": "thermostat-0042", "createdAt": "2025-11-03T07:12:00+00:00", "firmwares": [ { "id": "q8Fd53pLn1Yr", "name": "Thermostat application", "firmwareVersions": [ { "id": "r2Kt75mXc8Vd", "name": "2.4.1" } ] } ], "latestReportedBuildId": "8f3a1c9e2b7d4506", "statusFlags": [ ], "tags": { "environment": "field-test", "region": "eu-west" }, "cohort": { "id": "m3Yg84tDx7Rn", "name": "Field test devices" } } } } } } }, "404": { "description": "Device not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Devices: read" ] } ] } }, "/workspaces/{workspaceId}/devices/delete": { "post": { "tags": [ "Devices" ], "summary": "Delete devices by filter", "operationId": "POST-workspaces-{workspaceId}-devices-delete", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Delete devices by filter": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDevicesCommand" }, "examples": { "Delete devices by filter": { "value": { "deviceIds": [ "thermostat-0117" ], "filter": { "tags": [ { "tagName": "environment", "equals": "decommissioned" } ] } } } } } }, "required": true }, "responses": { "200": { "description": "Number of deleted devices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDevicesResponse" }, "examples": { "Delete devices by filter": { "description": "Number of deleted devices.", "value": { "devicesDeleted": 12 } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Devices: write" ] } ] } }, "/workspaces/{workspaceId}/devices": { "get": { "tags": [ "Devices" ], "summary": "List devices", "operationId": "GET-workspaces-{workspaceId}-devices", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List devices": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "responses": { "200": { "description": "All devices in the workspace.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceListItem" } }, "examples": { "List devices": { "description": "All devices in the workspace.", "value": [ { "deviceId": "thermostat-0042", "createdAt": "2025-11-03T07:12:00+00:00", "firmwares": [ { "id": "q8Fd53pLn1Yr", "name": "Thermostat application", "firmwareVersions": [ { "id": "r2Kt75mXc8Vd", "name": "2.4.1" } ] } ], "latestReportedBuildId": "8f3a1c9e2b7d4506", "statusFlags": [ ], "tags": { "environment": "field-test", "region": "eu-west" }, "cohort": { "id": "m3Yg84tDx7Rn", "name": "Field test devices" } } ] } } } } } }, "security": [ { "API key": [ "Devices: read" ] } ] } }, "/workspaces/{workspaceId}/devices/list": { "post": { "tags": [ "Devices" ], "summary": "List devices with filter and pagination", "operationId": "POST-workspaces-{workspaceId}-devices-list", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List devices with filter and pagination": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDevicesCommand" }, "examples": { "List devices with filter and pagination": { "value": { "sortColumn": "CreatedAt", "ascending": false, "limit": 50, "filter": { "createdAt": [ { "from": "2025-11-01T00:00:00+00:00", "to": "2026-01-01T00:00:00+00:00" } ], "deviceId": [ { "contains": "thermostat" } ], "statusFlags": [ "IsCrashing" ], "firmware": { "firmwareIds": [ "q8Fd53pLn1Yr" ], "firmwareVersionIds": [ "r2Kt75mXc8Vd" ] }, "tags": [ { "tagName": "environment", "equals": "field-test" } ], "cohort": { "in": [ "m3Yg84tDx7Rn" ] } } } } } } }, "required": true }, "responses": { "200": { "description": "Matching devices with a pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDevicesResponse" }, "examples": { "List devices with filter and pagination": { "description": "Page of devices matching the filter.", "value": { "devices": [ { "deviceId": "thermostat-0042", "createdAt": "2025-11-03T07:12:00+00:00", "firmwares": [ { "id": "q8Fd53pLn1Yr", "name": "Thermostat application", "firmwareVersions": [ { "id": "r2Kt75mXc8Vd", "name": "2.4.1" } ] } ], "latestReportedBuildId": "8f3a1c9e2b7d4506", "statusFlags": [ ], "tags": { "environment": "field-test", "region": "eu-west" }, "cohort": { "id": "m3Yg84tDx7Rn", "name": "Field test devices" } } ], "nextCursor": "eyJvZmZzZXQiOjUwfQ", "hasMore": true, "totalCount": 1840 } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Devices: read" ] } ] } }, "/workspaces/{workspaceId}/devices/{deviceId}/configuration/desired": { "put": { "tags": [ "Devices" ], "summary": "Update desired device configuration", "operationId": "PUT-workspaces-{workspaceId}-devices-{deviceId}-configuration-desired", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Update desired device configuration": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Update desired device configuration": { "description": "Device ID.", "value": "thermostat-0042" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDesiredConfigurationCommand" }, "examples": { "Update desired device configuration": { "value": { "logSeverity": "Warning" } } } } }, "required": true }, "responses": { "204": { "description": "Desired configuration updated." }, "404": { "description": "Device not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Devices: write" ] } ] }, "get": { "tags": [ "Devices" ], "summary": "Get desired device configuration", "operationId": "GET-workspaces-{workspaceId}-devices-{deviceId}-configuration-desired", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get desired device configuration": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get desired device configuration": { "description": "Device ID.", "value": "thermostat-0042" } } } ], "responses": { "200": { "description": "Desired configuration of the device.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesiredConfigurationResponse" }, "examples": { "Get desired device configuration": { "description": "Desired configuration of the device.", "value": { "configuration": { "logSeverity": "Warning" }, "version": 7 } } } } } }, "404": { "description": "Device not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Devices: read" ] } ] } }, "/workspaces/{workspaceId}/devices/{deviceId}/configuration/reported": { "get": { "tags": [ "Devices" ], "summary": "Get reported device configuration", "operationId": "GET-workspaces-{workspaceId}-devices-{deviceId}-configuration-reported", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get reported device configuration": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get reported device configuration": { "description": "Device ID.", "value": "thermostat-0042" } } } ], "responses": { "200": { "description": "Configuration last reported by the device.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportedConfigurationResponse" }, "examples": { "Get reported device configuration": { "description": "Configuration last reported by the device.", "value": { "configuration": { "logSeverity": "Warning", "compiledLogSeverity": "Debug", "acknowledgedDesiredConfigurationVersion": 7 }, "version": 3 } } } } } }, "404": { "description": "Device not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Devices: read" ] } ] } }, "/workspaces/{workspaceId}/devices/{deviceId}/firmware-version/reported/latest": { "get": { "tags": [ "Devices" ], "summary": "Get latest reported firmware version of device", "operationId": "GET-workspaces-{workspaceId}-devices-{deviceId}-firmware-version-reported-latest", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get latest reported firmware version of device": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get latest reported firmware version of device": { "description": "Device ID.", "value": "thermostat-0042" } } } ], "responses": { "200": { "description": "Device with its latest reported firmware version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceListItem" }, "examples": { "Get latest reported firmware version of device": { "description": "Device with the firmware versions it last reported.", "value": { "deviceId": "thermostat-0042", "createdAt": "2025-11-03T07:12:00+00:00", "firmwares": [ { "id": "q8Fd53pLn1Yr", "name": "Thermostat application", "firmwareVersions": [ { "id": "r2Kt75mXc8Vd", "name": "2.4.1" } ] } ], "latestReportedBuildId": "8f3a1c9e2b7d4506", "statusFlags": [ ], "tags": { "environment": "field-test", "region": "eu-west" }, "cohort": { "id": "m3Yg84tDx7Rn", "name": "Field test devices" } } } } } } }, "404": { "description": "Device not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Devices: read" ] } ] } }, "/workspaces/{workspaceId}/devices/upsert-tags": { "post": { "tags": [ "Device tags" ], "summary": "Upsert device tags", "operationId": "POST-workspaces-{workspaceId}-devices-upsert-tags", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Upsert device tags": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertDeviceTagsCommand" }, "examples": { "Upsert device tags": { "value": { "deviceIds": [ "thermostat-0042", "thermostat-0117" ], "filter": { "deviceId": [ { "contains": "thermostat" } ] }, "tags": { "environment": "field-test", "region": "eu-west" } } } } } }, "required": true }, "responses": { "200": { "description": "Number of updated devices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertDeviceTagsResponse" }, "examples": { "Upsert device tags": { "description": "Number of devices whose tags changed.", "value": { "devicesUpdated": 24 } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Devices: write" ] } ] } }, "/workspaces/{workspaceId}/devices/clear-tags": { "post": { "tags": [ "Device tags" ], "summary": "Clear device tags", "operationId": "POST-workspaces-{workspaceId}-devices-clear-tags", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Clear device tags": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearDeviceTagsCommand" }, "examples": { "Clear device tags": { "value": { "deviceIds": [ "thermostat-0117" ], "filter": { "tags": [ { "tagName": "environment", "equals": "field-test" } ] } } } } } }, "required": true }, "responses": { "200": { "description": "Number of updated devices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearDeviceTagsResponse" }, "examples": { "Clear device tags": { "description": "Number of devices whose tags were cleared.", "value": { "devicesUpdated": 24 } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Devices: write" ] } ] } }, "/workspaces/{workspaceId}/devices/{deviceId}/set-tags": { "post": { "tags": [ "Device tags" ], "summary": "Set device tags", "operationId": "POST-workspaces-{workspaceId}-devices-{deviceId}-set-tags", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Set device tags": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Set device tags": { "description": "Device ID.", "value": "thermostat-0042" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDeviceTagsCommand" }, "examples": { "Set device tags": { "value": { "tags": { "environment": "production", "region": "eu-west" } } } } } }, "required": true }, "responses": { "200": { "description": "Number of updated devices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDeviceTagsResponse" }, "examples": { "Set device tags": { "description": "Number of devices whose tags were replaced.", "value": { "devicesUpdated": 1 } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Device not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Device tags were modified concurrently.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Devices: write" ] } ] } }, "/workspaces/{workspaceId}/device-tags": { "get": { "tags": [ "Device tags" ], "summary": "List device tag names", "operationId": "GET-workspaces-{workspaceId}-device-tags", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List device tag names": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "responses": { "200": { "description": "Tag names used in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDeviceTagsResponse" }, "examples": { "List device tag names": { "description": "Tag names used by devices in the workspace.", "value": { "tagNames": [ "environment", "region", "hardwareRevision" ] } } } } } } }, "security": [ { "API key": [ "Devices: read" ] } ] } }, "/workspaces/{workspaceId}/device-tags/{tagName}/values": { "get": { "tags": [ "Device tags" ], "summary": "List device tag values", "operationId": "GET-workspaces-{workspaceId}-device-tags-{tagName}-values", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List device tag values": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "tagName", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List device tag values": { "description": "Tag name.", "value": "environment" } } } ], "responses": { "200": { "description": "Values used for the tag in the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDeviceTagValuesResponse" }, "examples": { "List device tag values": { "description": "Values used for the tag in the workspace.", "value": { "values": [ "development", "field-test", "production" ] } } } } } } }, "security": [ { "API key": [ "Devices: read" ] } ] } }, "/workspaces/{workspaceId}/dashboards": { "post": { "tags": [ "Dashboards" ], "summary": "Create dashboard", "operationId": "POST-workspaces-{workspaceId}-dashboards", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Create dashboard": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDashboardCommand" }, "examples": { "Create dashboard": { "value": { "name": "Smart locks analytics", "description": "Monitors the behavior of the smart lock product.", "definition": { "version": 1, "widgets": [ { "id": "0c1d500a-e457-4bd2-98ee-9e86cec88148", "name": "Unlocks by mechanism", "description": "", "query": { "type": "queryBuilder", "queryBuilderDefinition": { "metricName": "sample_unlock_attempt", "filters": [ ], "connectors": [ ], "summarize": { "groupBy": [ "mechanism" ], "aggregation": "count" } } }, "position": { "x": 0, "y": 0, "width": 3, "height": 6 }, "visualizationOptions": { "type": "bar", "stacked": true, "series": { "type": "dynamic", "valueColumn": { "type": "number", "dimensionName": "value" }, "xAxisColumn": { "type": "time", "dimensionName": "timestamp" } } } } ] } } } } } }, "required": true }, "responses": { "200": { "description": "Created dashboard. The `ETag` header carries its current version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dashboard" }, "examples": { "Create dashboard": { "description": "Created dashboard.", "value": { "id": "j5Vd71rKw4Xc", "name": "Smart locks analytics", "description": "Monitors the behavior of the smart lock product.", "createdAt": "2026-01-04T08:00:00+00:00", "updatedAt": "2026-01-11T16:42:00+00:00", "creatorSubjectId": "00000000-0000-0000-0000-0000000000aa", "updaterSubjectId": "00000000-0000-0000-0000-0000000000bb", "definition": { "version": 1, "widgets": [ { "id": "0c1d500a-e457-4bd2-98ee-9e86cec88148", "name": "Unlocks by mechanism", "description": "", "query": { "type": "queryBuilder", "queryBuilderDefinition": { "metricName": "sample_unlock_attempt", "filters": [ ], "connectors": [ ], "summarize": { "groupBy": [ "mechanism" ], "aggregation": "count" } } }, "position": { "x": 0, "y": 0, "width": 3, "height": 6 }, "visualizationOptions": { "type": "bar", "stacked": true, "series": { "type": "dynamic", "valueColumn": { "type": "number", "dimensionName": "value" }, "xAxisColumn": { "type": "time", "dimensionName": "timestamp" } } } } ] } } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Dashboards: write" ] } ] }, "get": { "tags": [ "Dashboards" ], "summary": "List dashboards", "operationId": "GET-workspaces-{workspaceId}-dashboards", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List dashboards": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "responses": { "200": { "description": "All dashboards in the workspace.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardListItem" } }, "examples": { "List dashboards": { "description": "All dashboards in the workspace.", "value": [ { "id": "j5Vd71rKw4Xc", "name": "Smart locks analytics", "description": "Monitors the behavior of the smart lock product.", "createdAt": "2026-01-04T08:00:00+00:00", "updatedAt": "2026-01-11T16:42:00+00:00", "creatorSubjectId": "00000000-0000-0000-0000-0000000000aa", "updaterSubjectId": "00000000-0000-0000-0000-0000000000bb" }, { "id": "k8Wf32nBy6Tm", "name": "Fleet connectivity", "description": "Connection drops and reconnect latency across the fleet.", "createdAt": "2026-01-06T09:30:00+00:00", "updatedAt": "2026-01-10T12:05:00+00:00", "creatorSubjectId": "00000000-0000-0000-0000-0000000000aa", "updaterSubjectId": "00000000-0000-0000-0000-0000000000aa" } ] } } } } } }, "security": [ { "API key": [ "Dashboards: read" ] } ] } }, "/workspaces/{workspaceId}/dashboards/{dashboardId}": { "get": { "tags": [ "Dashboards" ], "summary": "Get dashboard", "operationId": "GET-workspaces-{workspaceId}-dashboards-{dashboardId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get dashboard": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "dashboardId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get dashboard": { "description": "Dashboard ID.", "value": "j5Vd71rKw4Xc" } } } ], "responses": { "200": { "description": "Dashboard detail. The `ETag` header carries its current version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dashboard" }, "examples": { "Get dashboard": { "description": "Dashboard detail including its definition.", "value": { "id": "j5Vd71rKw4Xc", "name": "Smart locks analytics", "description": "Monitors the behavior of the smart lock product.", "createdAt": "2026-01-04T08:00:00+00:00", "updatedAt": "2026-01-11T16:42:00+00:00", "creatorSubjectId": "00000000-0000-0000-0000-0000000000aa", "updaterSubjectId": "00000000-0000-0000-0000-0000000000bb", "definition": { "version": 1, "widgets": [ { "id": "0c1d500a-e457-4bd2-98ee-9e86cec88148", "name": "Unlocks by mechanism", "description": "", "query": { "type": "queryBuilder", "queryBuilderDefinition": { "metricName": "sample_unlock_attempt", "filters": [ ], "connectors": [ ], "summarize": { "groupBy": [ "mechanism" ], "aggregation": "count" } } }, "position": { "x": 0, "y": 0, "width": 3, "height": 6 }, "visualizationOptions": { "type": "bar", "stacked": true, "series": { "type": "dynamic", "valueColumn": { "type": "number", "dimensionName": "value" }, "xAxisColumn": { "type": "time", "dimensionName": "timestamp" } } } } ] } } } } } } }, "404": { "description": "Dashboard not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Dashboards: read" ] } ] }, "put": { "tags": [ "Dashboards" ], "summary": "Update dashboard", "operationId": "PUT-workspaces-{workspaceId}-dashboards-{dashboardId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Update dashboard": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "dashboardId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Update dashboard": { "description": "Dashboard ID.", "value": "j5Vd71rKw4Xc" } } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "examples": { "Update dashboard": { "description": "ETag returned by the last read of the dashboard.", "value": "\"3\"" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDashboardCommand" }, "examples": { "Update dashboard": { "value": { "name": "Smart locks analytics", "description": "Monitors the behavior of the smart lock product.", "definition": { "version": 1, "widgets": [ { "id": "0c1d500a-e457-4bd2-98ee-9e86cec88148", "name": "Unlocks by mechanism", "description": "", "query": { "type": "queryBuilder", "queryBuilderDefinition": { "metricName": "sample_unlock_attempt", "filters": [ ], "connectors": [ ], "summarize": { "groupBy": [ "mechanism" ], "aggregation": "count" } } }, "position": { "x": 0, "y": 0, "width": 3, "height": 6 }, "visualizationOptions": { "type": "bar", "stacked": true, "series": { "type": "dynamic", "valueColumn": { "type": "number", "dimensionName": "value" }, "xAxisColumn": { "type": "time", "dimensionName": "timestamp" } } } } ] } } } } } }, "required": true }, "responses": { "200": { "description": "Updated dashboard. The `ETag` header carries its new version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dashboard" }, "examples": { "Update dashboard": { "description": "Updated dashboard.", "value": { "id": "j5Vd71rKw4Xc", "name": "Smart locks analytics", "description": "Monitors the behavior of the smart lock product.", "createdAt": "2026-01-04T08:00:00+00:00", "updatedAt": "2026-01-11T16:42:00+00:00", "creatorSubjectId": "00000000-0000-0000-0000-0000000000aa", "updaterSubjectId": "00000000-0000-0000-0000-0000000000bb", "definition": { "version": 1, "widgets": [ { "id": "0c1d500a-e457-4bd2-98ee-9e86cec88148", "name": "Unlocks by mechanism", "description": "", "query": { "type": "queryBuilder", "queryBuilderDefinition": { "metricName": "sample_unlock_attempt", "filters": [ ], "connectors": [ ], "summarize": { "groupBy": [ "mechanism" ], "aggregation": "count" } } }, "position": { "x": 0, "y": 0, "width": 3, "height": 6 }, "visualizationOptions": { "type": "bar", "stacked": true, "series": { "type": "dynamic", "valueColumn": { "type": "number", "dimensionName": "value" }, "xAxisColumn": { "type": "time", "dimensionName": "timestamp" } } } } ] } } } } } } }, "400": { "description": "Command is not valid, or the `If-Match` header is not a valid ETag.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Dashboard not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "description": "Dashboard was modified by someone else since the `If-Match` ETag was issued.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Dashboards: write" ] } ] }, "delete": { "tags": [ "Dashboards" ], "summary": "Delete dashboard", "operationId": "DELETE-workspaces-{workspaceId}-dashboards-{dashboardId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Delete dashboard": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "dashboardId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Delete dashboard": { "description": "Dashboard ID.", "value": "j5Vd71rKw4Xc" } } }, { "name": "If-Match", "in": "header", "schema": { "type": "string" }, "examples": { "Delete dashboard": { "description": "ETag returned by the last read of the dashboard.", "value": "\"3\"" } } } ], "responses": { "204": { "description": "Dashboard deleted." }, "400": { "description": "`If-Match` header is not a valid ETag.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Dashboard not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "description": "Dashboard was modified by someone else since the `If-Match` ETag was issued.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Dashboards: write" ] } ] } }, "/workspaces/{workspaceId}/core-dumps/{coreDumpId}/start-analysis": { "post": { "tags": [ "Core dumps" ], "summary": "Start core dump analysis", "operationId": "POST-workspaces-{workspaceId}-core-dumps-{coreDumpId}-start-analysis", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Start core dump analysis": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "coreDumpId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Start core dump analysis": { "description": "Core dump ID.", "value": "d4Rt89jWq5Zb" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartCoreDumpAnalysisCommand" }, "examples": { "Start core dump analysis": { "value": { "symbolFileId": "f1Lk64dHs7Xa" } } } } }, "required": true }, "responses": { "200": { "description": "Core dump analysis started." }, "404": { "description": "Core dump or symbol file not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Core dumps: write" ] } ] } }, "/workspaces/{workspaceId}/core-dumps/{coreDumpId}": { "get": { "tags": [ "Core dumps" ], "summary": "Get core dump content links", "operationId": "GET-workspaces-{workspaceId}-core-dumps-{coreDumpId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get core dump content links": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "coreDumpId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get core dump content links": { "description": "Core dump ID.", "value": "d4Rt89jWq5Zb" } } } ], "responses": { "200": { "description": "Time-limited links to the core dump content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoreDumpResponse" }, "examples": { "Get core dump content links": { "description": "Time-limited download links to the core dump content.", "value": { "sasLinksExpiration": "2026-01-12T15:05:12+00:00", "contentSasLink": "https://storage.spotflow.io/core-dumps/d4Rt89jWq5Zb.bin?sv=2025-01-01&sig=example", "elfContentSasLink": "https://storage.spotflow.io/core-dumps/d4Rt89jWq5Zb.elf?sv=2025-01-01&sig=example" } } } } } }, "404": { "description": "Core dump not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Core dumps: read" ] } ] } }, "/workspaces/{workspaceId}/core-dumps/{coreDumpId}/analyses": { "get": { "tags": [ "Core dumps" ], "summary": "List core dump analyses", "operationId": "GET-workspaces-{workspaceId}-core-dumps-{coreDumpId}-analyses", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List core dump analyses": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "coreDumpId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List core dump analyses": { "description": "Core dump ID.", "value": "d4Rt89jWq5Zb" } } } ], "responses": { "200": { "description": "All analyses of the core dump.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CoreDumpAnalysisResponse" } }, "examples": { "List core dump analyses": { "description": "Analyses performed for the core dump.", "value": [ { "id": "g7Nb25vFm3Pd", "basicAnalysisState": "Succeeded", "gdbAnalysisState": "Succeeded", "aiAnalysisState": "Succeeded", "createdAt": "2026-01-12T14:12:00+00:00", "basicAnalysisSasLink": "https://storage.spotflow.io/analyses/g7Nb25vFm3Pd-basic.json?sv=2025-01-01&sig=example", "gdbAnalysisSasLink": "https://storage.spotflow.io/analyses/g7Nb25vFm3Pd-gdb.txt?sv=2025-01-01&sig=example", "aiAnalysisSasLink": "https://storage.spotflow.io/analyses/g7Nb25vFm3Pd-ai.md?sv=2025-01-01&sig=example" }, { "id": "h2Qs58cJp9Wl", "basicAnalysisState": "Succeeded", "gdbAnalysisState": "Failed", "gdbAnalysisError": "Symbol file does not match the firmware build ID.", "aiAnalysisState": "Skipped", "createdAt": "2026-01-12T14:08:00+00:00", "basicAnalysisSasLink": "https://storage.spotflow.io/analyses/h2Qs58cJp9Wl-basic.json?sv=2025-01-01&sig=example" } ] } } } } }, "404": { "description": "Core dump or crash report not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Core dumps: read" ] } ] } }, "/api-keys/current": { "get": { "tags": [ "API keys" ], "summary": "Get current API key", "description": "Returns the API key used to authenticate the request, including its scopes and the workspaces it can access.", "operationId": "GET-api-keys-current", "responses": { "200": { "description": "API key used to authenticate the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentApiKey" } } } } }, "security": [ ] } }, "/workspaces/{workspaceId}/alert-tags": { "post": { "tags": [ "Alert tags" ], "summary": "Create alert tag", "operationId": "POST-workspaces-{workspaceId}-alert-tags", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Create alert tag": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAlertTagCommand" }, "examples": { "Create alert tag": { "value": { "name": "Production", "color": "#e11d48" } } } } }, "required": true }, "responses": { "200": { "description": "Created alert tag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertTag" }, "examples": { "Create alert tag": { "description": "Created alert tag.", "value": { "id": "t8Pj42kLd6Nw", "name": "Production", "color": "#e11d48", "createdAt": "2026-01-08T11:20:00+00:00" } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: write" ] } ] }, "get": { "tags": [ "Alert tags" ], "summary": "List alert tags", "operationId": "GET-workspaces-{workspaceId}-alert-tags", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List alert tags": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "responses": { "200": { "description": "All alert tags in the workspace.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AlertTag" } }, "examples": { "List alert tags": { "description": "All alert tags in the workspace.", "value": [ { "id": "t8Pj42kLd6Nw", "name": "Production", "color": "#e11d48", "createdAt": "2026-01-08T11:20:00+00:00" }, { "id": "u5Zm93bRf1Qs", "name": "Needs investigation", "color": "#f59e0b", "createdAt": "2026-01-09T07:45:00+00:00" } ] } } } } } }, "security": [ { "API key": [ "Alerts: read" ] } ] } }, "/workspaces/{workspaceId}/alert-tags/{tagId}": { "put": { "tags": [ "Alert tags" ], "summary": "Update alert tag", "operationId": "PUT-workspaces-{workspaceId}-alert-tags-{tagId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Update alert tag": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Update alert tag": { "description": "Alert tag ID.", "value": "t8Pj42kLd6Nw" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAlertTagCommand" }, "examples": { "Update alert tag": { "value": { "name": "Production fleet", "color": "#be123c" } } } } }, "required": true }, "responses": { "200": { "description": "Updated alert tag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertTag" }, "examples": { "Update alert tag": { "description": "Updated alert tag.", "value": { "id": "t8Pj42kLd6Nw", "name": "Production fleet", "color": "#be123c", "createdAt": "2026-01-08T11:20:00+00:00" } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Alert tag not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: write" ] } ] }, "delete": { "tags": [ "Alert tags" ], "summary": "Delete alert tag", "operationId": "DELETE-workspaces-{workspaceId}-alert-tags-{tagId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Delete alert tag": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "tagId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Delete alert tag": { "description": "Alert tag ID.", "value": "t8Pj42kLd6Nw" } } } ], "responses": { "204": { "description": "Alert tag deleted." }, "404": { "description": "Alert tag not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: write" ] } ] } }, "/workspaces/{workspaceId}/alerts/list": { "post": { "tags": [ "Alerts" ], "summary": "List alerts", "operationId": "POST-workspaces-{workspaceId}-alerts-list", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List firing alerts": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAlertsCommand" }, "examples": { "List firing alerts": { "value": { "sortColumn": "StartedAt", "ascending": false, "limit": 50, "filter": { "state": [ "Firing" ], "alertRuleId": [ "a7Kd93mQx2Lp" ], "startedAt": [ { "from": "2026-01-12T00:00:00+00:00", "to": "2026-01-13T00:00:00+00:00" } ], "tag": { "tagIds": [ "t8Pj42kLd6Nw" ], "mode": "ContainsAny" } } } } } } }, "required": true }, "responses": { "200": { "description": "Matching alerts with a pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAlertsResponse" }, "examples": { "List firing alerts": { "description": "Page of alerts matching the filter.", "value": { "alerts": [ { "id": "c6Hy71wPd3Mv", "alertRuleId": "a7Kd93mQx2Lp", "state": "Firing", "thresholdType": "FixedHigherThan", "thresholdValue": 90, "startedAt": "2026-01-12T14:05:12+00:00", "devices": [ { "deviceId": "thermostat-0042", "startedAt": "2026-01-12T14:05:12+00:00" }, { "deviceId": "thermostat-0117", "startedAt": "2026-01-12T14:10:31+00:00", "resolvedAt": "2026-01-12T14:40:02+00:00" } ], "tagIds": [ "t8Pj42kLd6Nw" ] } ], "nextCursor": "eyJvZmZzZXQiOjUwfQ", "hasMore": true } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: read" ] } ] } }, "/workspaces/{workspaceId}/alerts/{alertId}": { "get": { "tags": [ "Alerts" ], "summary": "Get alert", "operationId": "GET-workspaces-{workspaceId}-alerts-{alertId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get alert": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get alert": { "description": "Alert ID.", "value": "c6Hy71wPd3Mv" } } } ], "responses": { "200": { "description": "Alert detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" }, "examples": { "Get alert": { "description": "Alert detail.", "value": { "id": "c6Hy71wPd3Mv", "alertRuleId": "a7Kd93mQx2Lp", "state": "Firing", "thresholdType": "FixedHigherThan", "thresholdValue": 90, "startedAt": "2026-01-12T14:05:12+00:00", "devices": [ { "deviceId": "thermostat-0042", "startedAt": "2026-01-12T14:05:12+00:00" }, { "deviceId": "thermostat-0117", "startedAt": "2026-01-12T14:10:31+00:00", "resolvedAt": "2026-01-12T14:40:02+00:00" } ], "tags": [ { "id": "t8Pj42kLd6Nw", "name": "Production", "color": "#e11d48" } ] } } } } } }, "404": { "description": "Alert not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: read" ] } ] }, "patch": { "tags": [ "Alerts" ], "summary": "Update alert", "operationId": "PATCH-workspaces-{workspaceId}-alerts-{alertId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Replace tags of an alert": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Replace tags of an alert": { "description": "Alert ID.", "value": "c6Hy71wPd3Mv" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAlertCommand" }, "examples": { "Replace tags of an alert": { "value": { "tagIds": [ "t8Pj42kLd6Nw", "u5Zm93bRf1Qs" ] } } } } }, "required": true }, "responses": { "200": { "description": "Updated alert.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" }, "examples": { "Replace tags of an alert": { "description": "Updated alert.", "value": { "id": "c6Hy71wPd3Mv", "alertRuleId": "a7Kd93mQx2Lp", "state": "Firing", "thresholdType": "FixedHigherThan", "thresholdValue": 90, "startedAt": "2026-01-12T14:05:12+00:00", "devices": [ { "deviceId": "thermostat-0042", "startedAt": "2026-01-12T14:05:12+00:00" }, { "deviceId": "thermostat-0117", "startedAt": "2026-01-12T14:10:31+00:00", "resolvedAt": "2026-01-12T14:40:02+00:00" } ], "tags": [ { "id": "t8Pj42kLd6Nw", "name": "Production", "color": "#e11d48" }, { "id": "u5Zm93bRf1Qs", "name": "Needs investigation", "color": "#f59e0b" } ] } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Alert not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: write" ] } ] } }, "/workspaces/{workspaceId}/alerts/{alertId}/evaluated-time-series/list": { "post": { "tags": [ "Alerts" ], "summary": "List evaluated time series of alert", "operationId": "POST-workspaces-{workspaceId}-alerts-{alertId}-evaluated-time-series-list", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List evaluated time series of alert": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "List evaluated time series of alert": { "description": "Alert ID.", "value": "c6Hy71wPd3Mv" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAlertEvaluatedTimeSeriesCommand" }, "examples": { "List evaluated time series of alert": { "value": { "ascending": false, "limit": 50, "filter": { "state": [ "Firing" ], "deviceId": [ "thermostat-0042" ] } } } } } }, "required": true }, "responses": { "200": { "description": "Time series evaluated for the alert.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAlertEvaluatedTimeSeriesResponse" }, "examples": { "List evaluated time series of alert": { "description": "Page of time series evaluated by the alert rule.", "value": { "evaluatedTimeSeries": [ { "id": "s9Cv36gTn8Ku", "metricName": "cpu", "labels": { "core": "0", "unit": "percent" }, "deviceId": "thermostat-0042", "evaluatedValue": { "fixed": { "value": 96.4 } }, "startedAt": "2026-01-12T14:05:12+00:00" } ], "hasMore": false } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Alert not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: read" ] } ] } }, "/workspaces/{workspaceId}/alert-rules": { "post": { "tags": [ "Alert rules" ], "summary": "Create alert rule", "operationId": "POST-workspaces-{workspaceId}-alert-rules", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Create alert rule": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAlertRuleCommand" }, "examples": { "Create alert rule": { "value": { "name": "High CPU usage", "description": "Fires when the average CPU usage of a device exceeds 90 %.", "condition": { "fixed": { "query": "metrics | where metric_name == 'cpu' | summarize avg(value) by device_id", "thresholdValue": 90, "minimalTimeSeriesCount": 1, "thresholdType": "HigherThan", "evaluationWindow": "5m" } }, "evaluationFrequency": "5m", "firstEvaluationAt": "2026-01-12T10:00:00+00:00", "notificationTargetIds": [ "n4Tg81vBz6Rw" ], "queryType": "RawQuery" } } } } }, "required": true }, "responses": { "200": { "description": "Created alert rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRule" }, "examples": { "Create alert rule": { "description": "Created alert rule.", "value": { "id": "a7Kd93mQx2Lp", "name": "High CPU usage", "description": "Fires when the average CPU usage of a device exceeds 90 %.", "state": "Enabled", "type": "MetricFixedThreshold", "condition": { "fixed": { "query": "metrics | where metric_name == 'cpu' | summarize avg(value) by device_id", "thresholdValue": 90, "minimalTimeSeriesCount": 1, "thresholdType": "HigherThan", "evaluationWindow": "5m" } }, "evaluationFrequency": "5m", "createdAt": "2026-01-12T09:30:00+00:00", "firstEvaluationAt": "2026-01-12T10:00:00+00:00", "lastEvaluatedAt": "2026-01-12T14:05:12+00:00", "creatorSubjectId": "00000000-0000-0000-0000-0000000000aa", "targets": [ { "id": "n4Tg81vBz6Rw", "name": "On-call e-mail" } ], "evaluations": [ { "id": "e2Wq58hNc4Yt", "evaluatedAt": "2026-01-12T14:05:12+00:00", "evaluationScheduledAt": "2026-01-12T14:05:00+00:00", "evaluationWindowStart": "2026-01-12T14:00:00+00:00", "evaluationWindowEnd": "2026-01-12T14:05:00+00:00", "status": "Firing" } ], "hasFiringAlert": true, "queryType": "RawQuery" } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: write" ] } ] }, "get": { "tags": [ "Alert rules" ], "summary": "List alert rules", "operationId": "GET-workspaces-{workspaceId}-alert-rules", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "List enabled alert rules": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "state", "in": "query", "schema": { "$ref": "#/components/schemas/AlertRuleState" }, "examples": { "List enabled alert rules": { "description": "Return only alert rules in this state.", "value": "Enabled" } } } ], "responses": { "200": { "description": "All alert rules in the workspace.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AlertRuleListItem" } }, "examples": { "List enabled alert rules": { "description": "All alert rules in the workspace.", "value": [ { "id": "a7Kd93mQx2Lp", "name": "High CPU usage", "description": "Fires when the average CPU usage of a device exceeds 90 %.", "state": "Enabled", "type": "MetricFixedThreshold", "evaluationFrequency": "5m", "createdAt": "2026-01-12T09:30:00+00:00", "targets": [ { "id": "n4Tg81vBz6Rw", "name": "On-call e-mail" } ], "hasFiringAlert": true, "evaluations": [ { "id": "e2Wq58hNc4Yt", "evaluatedAt": "2026-01-12T14:05:12+00:00", "evaluationScheduledAt": "2026-01-12T14:05:00+00:00", "evaluationWindowStart": "2026-01-12T14:00:00+00:00", "evaluationWindowEnd": "2026-01-12T14:05:00+00:00", "status": "Firing" } ] }, { "id": "b3Xn17sVt9Kc", "name": "Memory usage growth", "description": "Fires when memory usage grows by more than 25 % in an hour.", "state": "Enabled", "type": "MetricPercentualThreshold", "evaluationFrequency": "1h", "createdAt": "2026-01-05T08:15:00+00:00", "targets": [ { "id": "n4Tg81vBz6Rw", "name": "On-call e-mail" } ], "hasFiringAlert": false, "evaluations": [ ] } ] } } } } } }, "security": [ { "API key": [ "Alerts: read" ] } ] } }, "/workspaces/{workspaceId}/alert-rules/{alertRuleId}": { "get": { "tags": [ "Alert rules" ], "summary": "Get alert rule", "operationId": "GET-workspaces-{workspaceId}-alert-rules-{alertRuleId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Get alert rule": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "alertRuleId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Get alert rule": { "description": "Alert rule ID.", "value": "a7Kd93mQx2Lp" } } } ], "responses": { "200": { "description": "Alert rule detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRule" }, "examples": { "Get alert rule": { "description": "Alert rule detail.", "value": { "id": "a7Kd93mQx2Lp", "name": "High CPU usage", "description": "Fires when the average CPU usage of a device exceeds 90 %.", "state": "Enabled", "type": "MetricFixedThreshold", "condition": { "fixed": { "query": "metrics | where metric_name == 'cpu' | summarize avg(value) by device_id", "thresholdValue": 90, "minimalTimeSeriesCount": 1, "thresholdType": "HigherThan", "evaluationWindow": "5m" } }, "evaluationFrequency": "5m", "createdAt": "2026-01-12T09:30:00+00:00", "firstEvaluationAt": "2026-01-12T10:00:00+00:00", "lastEvaluatedAt": "2026-01-12T14:05:12+00:00", "creatorSubjectId": "00000000-0000-0000-0000-0000000000aa", "targets": [ { "id": "n4Tg81vBz6Rw", "name": "On-call e-mail" } ], "evaluations": [ { "id": "e2Wq58hNc4Yt", "evaluatedAt": "2026-01-12T14:05:12+00:00", "evaluationScheduledAt": "2026-01-12T14:05:00+00:00", "evaluationWindowStart": "2026-01-12T14:00:00+00:00", "evaluationWindowEnd": "2026-01-12T14:05:00+00:00", "status": "Firing" } ], "hasFiringAlert": true, "queryType": "RawQuery" } } } } } }, "404": { "description": "Alert rule not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: read" ] } ] }, "put": { "tags": [ "Alert rules" ], "summary": "Update alert rule", "operationId": "PUT-workspaces-{workspaceId}-alert-rules-{alertRuleId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Update alert rule": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "alertRuleId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Update alert rule": { "description": "Alert rule ID.", "value": "a7Kd93mQx2Lp" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAlertRuleCommand" }, "examples": { "Update alert rule": { "value": { "name": "High CPU usage", "description": "Fires when the average CPU usage of a device exceeds 95 %.", "state": "Enabled", "condition": { "fixed": { "query": "metrics | where metric_name == 'cpu' | summarize avg(value) by device_id", "thresholdValue": 95, "minimalTimeSeriesCount": 1, "thresholdType": "HigherThan", "evaluationWindow": "5m" } }, "evaluationFrequency": "5m", "notificationTargetIds": [ "n4Tg81vBz6Rw" ], "queryType": "RawQuery" } } } } }, "required": true }, "responses": { "200": { "description": "Updated alert rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRule" }, "examples": { "Update alert rule": { "description": "Updated alert rule.", "value": { "id": "a7Kd93mQx2Lp", "name": "High CPU usage", "description": "Fires when the average CPU usage of a device exceeds 90 %.", "state": "Enabled", "type": "MetricFixedThreshold", "condition": { "fixed": { "query": "metrics | where metric_name == 'cpu' | summarize avg(value) by device_id", "thresholdValue": 90, "minimalTimeSeriesCount": 1, "thresholdType": "HigherThan", "evaluationWindow": "5m" } }, "evaluationFrequency": "5m", "createdAt": "2026-01-12T09:30:00+00:00", "firstEvaluationAt": "2026-01-12T10:00:00+00:00", "lastEvaluatedAt": "2026-01-12T14:05:12+00:00", "creatorSubjectId": "00000000-0000-0000-0000-0000000000aa", "targets": [ { "id": "n4Tg81vBz6Rw", "name": "On-call e-mail" } ], "evaluations": [ { "id": "e2Wq58hNc4Yt", "evaluatedAt": "2026-01-12T14:05:12+00:00", "evaluationScheduledAt": "2026-01-12T14:05:00+00:00", "evaluationWindowStart": "2026-01-12T14:00:00+00:00", "evaluationWindowEnd": "2026-01-12T14:05:00+00:00", "status": "Firing" } ], "hasFiringAlert": true, "queryType": "RawQuery" } } } } } }, "400": { "description": "Command is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Alert rule not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: write" ] } ] }, "delete": { "tags": [ "Alert rules" ], "summary": "Delete alert rule", "operationId": "DELETE-workspaces-{workspaceId}-alert-rules-{alertRuleId}", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Delete alert rule": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } }, { "name": "alertRuleId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "Delete alert rule": { "description": "Alert rule ID.", "value": "a7Kd93mQx2Lp" } } } ], "responses": { "204": { "description": "Alert rule deleted." }, "404": { "description": "Alert rule not found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: write" ] } ] } }, "/workspaces/{workspaceId}/alert-rules/preview-condition": { "post": { "tags": [ "Alert rules" ], "summary": "Preview alert rule condition", "operationId": "POST-workspaces-{workspaceId}-alert-rules-preview-condition", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "examples": { "Preview alert rule condition": { "description": "Workspace ID.", "value": "00000000-0000-0000-0000-000000000001" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewConditionCommand" }, "examples": { "Preview alert rule condition": { "value": { "condition": { "fixed": { "query": "metrics | where metric_name == 'cpu' | summarize avg(value) by device_id", "thresholdValue": 90, "minimalTimeSeriesCount": 1, "thresholdType": "HigherThan", "evaluationWindow": "5m" } }, "from": "2026-01-12T12:00:00+00:00", "to": "2026-01-12T14:00:00+00:00" } } } } }, "required": true }, "responses": { "200": { "description": "Simulated evaluation of the condition over the requested time range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewConditionResponse" }, "examples": { "Preview alert rule condition": { "description": "Simulated evaluation of the condition over the requested time range.", "value": { "evaluationSimulation": [ { "timestamp": "2026-01-12T13:00:00+00:00", "isFiring": false }, { "timestamp": "2026-01-12T13:30:00+00:00", "isFiring": true }, { "timestamp": "2026-01-12T14:00:00+00:00", "isFiring": true } ] } } } } } }, "400": { "description": "Condition or time range is not valid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "API key": [ "Alerts: read" ] } ] } } }, "components": { "schemas": { "AcceptInviteResponse": { "required": [ "workspaceId" ], "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" } } }, "AddDevicesToDeploymentCohortCommand": { "type": "object", "properties": { "deviceIds": { "type": [ "null", "array" ], "items": { "type": "string" } }, "filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DevicesFilter" } ] } } }, "AffectedPackageItem": { "required": [ "versions" ], "type": "object", "properties": { "purl": { "type": [ "null", "string" ] }, "packageName": { "type": [ "null", "string" ] }, "vendor": { "type": [ "null", "string" ] }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/AffectedPackageVersionItem" }, "description": "The affected versions / version ranges for this package." } } }, "AffectedPackageVersionItem": { "type": "object", "properties": { "cpe": { "type": [ "null", "string" ], "description": "Raw CPE criteria this version was parsed from." }, "version": { "type": [ "null", "string" ], "description": "Exact affected version parsed from the CPE; null when the CPE uses a wildcard." }, "versionStartIncluding": { "type": [ "null", "string" ] }, "versionStartExcluding": { "type": [ "null", "string" ] }, "versionEndIncluding": { "type": [ "null", "string" ] }, "versionEndExcluding": { "type": [ "null", "string" ] } } }, "AiAnalysisState": { "enum": [ "Skipped", "InProgress", "Succeeded", "Failed" ], "type": "string" }, "Alert": { "required": [ "id", "alertRuleId", "state", "thresholdType", "thresholdValue", "startedAt", "devices", "tags" ], "type": "object", "properties": { "id": { "type": "string" }, "alertRuleId": { "type": "string" }, "state": { "$ref": "#/components/schemas/AlertState" }, "thresholdType": { "$ref": "#/components/schemas/ConditionThresholdType" }, "thresholdValue": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "startedAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": [ "null", "string" ], "format": "date-time" }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/AlertDeviceItem" } }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/AlertTagItem" } } } }, "AlertDeviceItem": { "required": [ "deviceId", "startedAt" ], "type": "object", "properties": { "deviceId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": [ "null", "string" ], "format": "date-time" } } }, "AlertEvaluatedTimeSeriesFilter": { "type": "object", "properties": { "state": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AlertState" } }, "deviceId": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "AlertEvaluatedTimeSeriesItem": { "required": [ "id", "metricName", "labels", "evaluatedValue", "startedAt" ], "type": "object", "properties": { "id": { "type": "string" }, "metricName": { "type": "string" }, "labels": { "type": "object", "additionalProperties": { "type": "string" } }, "deviceId": { "type": [ "null", "string" ] }, "evaluatedValue": { "$ref": "#/components/schemas/AlertEvaluatedValue" }, "startedAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": [ "null", "string" ], "format": "date-time" } } }, "AlertEvaluatedValue": { "type": "object", "properties": { "fixed": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FixedThresholdEvaluatedValue" } ] }, "percentual": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PercentualThresholdEvaluatedValue" } ] } } }, "AlertListItem": { "required": [ "id", "alertRuleId", "state", "thresholdType", "thresholdValue", "startedAt", "devices", "tagIds" ], "type": "object", "properties": { "id": { "type": "string" }, "alertRuleId": { "type": "string" }, "state": { "$ref": "#/components/schemas/AlertState" }, "thresholdType": { "$ref": "#/components/schemas/ConditionThresholdType" }, "thresholdValue": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "startedAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": [ "null", "string" ], "format": "date-time" }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/AlertDeviceItem" } }, "tagIds": { "type": "array", "items": { "type": "string" } } } }, "AlertRule": { "required": [ "id", "name", "state", "type", "condition", "evaluationFrequency", "createdAt", "firstEvaluationAt", "targets", "evaluations", "hasFiringAlert" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "state": { "$ref": "#/components/schemas/AlertRuleState" }, "type": { "$ref": "#/components/schemas/AlertRuleType" }, "condition": { "$ref": "#/components/schemas/AlertRuleCondition" }, "evaluationFrequency": { "$ref": "#/components/schemas/EvaluationFrequency" }, "createdAt": { "type": "string", "format": "date-time" }, "firstEvaluationAt": { "type": "string", "format": "date-time" }, "lastEvaluatedAt": { "type": [ "null", "string" ], "format": "date-time" }, "creatorSubjectId": { "type": [ "null", "string" ], "format": "uuid" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/AlertRuleTarget" } }, "evaluations": { "type": "array", "items": { "$ref": "#/components/schemas/AlertRuleEvaluation" } }, "hasFiringAlert": { "type": "boolean" }, "queryType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AlertRuleQueryType" } ] } } }, "AlertRuleCondition": { "type": "object", "properties": { "fixed": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FixedThresholdAlertRuleCondition" } ] }, "percentual": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PercentualThresholdAlertRuleCondition" } ] } } }, "AlertRuleEvaluation": { "required": [ "id", "evaluatedAt", "evaluationScheduledAt", "evaluationWindowStart", "evaluationWindowEnd", "status" ], "type": "object", "properties": { "id": { "type": "string" }, "evaluatedAt": { "type": "string", "format": "date-time" }, "evaluationScheduledAt": { "type": "string", "format": "date-time" }, "evaluationWindowStart": { "type": "string", "format": "date-time" }, "evaluationWindowEnd": { "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/AlertRuleEvaluationStatus" } } }, "AlertRuleEvaluationStatus": { "enum": [ "Normal", "Firing" ], "type": "string" }, "AlertRuleListItem": { "required": [ "id", "name", "state", "type", "evaluationFrequency", "createdAt", "targets", "hasFiringAlert", "evaluations" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "state": { "$ref": "#/components/schemas/AlertRuleState" }, "type": { "$ref": "#/components/schemas/AlertRuleType" }, "evaluationFrequency": { "$ref": "#/components/schemas/EvaluationFrequency" }, "createdAt": { "type": "string", "format": "date-time" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/AlertRuleTarget" } }, "hasFiringAlert": { "type": "boolean" }, "evaluations": { "type": "array", "items": { "$ref": "#/components/schemas/AlertRuleEvaluation" } } } }, "AlertRuleQueryType": { "enum": [ "Builder", "RawQuery" ], "type": [ "null", "string" ] }, "AlertRuleState": { "enum": [ "Enabled", "Disabled" ], "type": "string" }, "AlertRuleTarget": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "AlertRuleType": { "enum": [ "MetricFixedThreshold", "MetricPercentualThreshold" ], "type": "string" }, "AlertsFilter": { "type": "object", "properties": { "state": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/AlertState" } }, "alertRuleId": { "type": [ "null", "array" ], "items": { "type": "string" } }, "deviceId": { "type": [ "null", "array" ], "items": { "type": "string" } }, "startedAt": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/DateTimeFilterOperator" } }, "tag": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AlertTagFilter" } ] } } }, "AlertSortColumn": { "enum": [ "StartedAt" ], "type": [ "null", "string" ] }, "AlertState": { "enum": [ "Firing", "Resolved" ], "type": "string" }, "AlertTag": { "required": [ "id", "name", "createdAt" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "AlertTagFilter": { "type": "object", "properties": { "tagIds": { "type": "array", "items": { "type": "string" } }, "mode": { "$ref": "#/components/schemas/AlertTagFilterMode" } } }, "AlertTagFilterMode": { "enum": [ "ContainsAll", "ContainsAny", "ContainsNoneOf" ], "type": "string" }, "AlertTagItem": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": [ "null", "string" ] } } }, "ApiKeyKind": { "enum": [ "Workspace", "User" ], "type": "string" }, "ApiKeyScope": { "required": [ "value", "displayName" ], "type": "object", "properties": { "value": { "type": "string" }, "displayName": { "type": "string" } } }, "AssessmentInfo": { "required": [ "assessment" ], "type": "object", "properties": { "assessment": { "$ref": "#/components/schemas/FindingAssessment" }, "justification": { "type": [ "null", "string" ], "description": "Structured reason category for the decision (e.g. a VEX justification)." }, "detail": { "type": [ "null", "string" ], "description": "Free-text explanation the author entered alongside the assessment (the reason textarea)." }, "response": { "type": [ "null", "string" ], "description": "The VEX action statement: the recommended response / remediation for an affected product." } } }, "AssessVulnerabilityFindingCommand": { "required": [ "assessment" ], "type": "object", "properties": { "assessment": { "$ref": "#/components/schemas/FindingAssessment" }, "justification": { "type": [ "null", "string" ], "description": "Optional structured reason category for the decision (e.g. a VEX justification)." }, "detail": { "type": [ "null", "string" ], "description": "Optional free-text explanation entered alongside the assessment." }, "response": { "type": [ "null", "string" ], "description": "The VEX action statement: the recommended response / remediation for the affected product.\nRequired (non-empty) when FindingAssessment AssessVulnerabilityFindingCommand.Assessment is FindingAssessment.Affected." } }, "description": "Records a user assessment of a vulnerability finding. Appends an audit row and updates the finding's\ncurrent assessment." }, "BasicAnalysisState": { "enum": [ "Skipped", "InProgress", "Succeeded", "Failed" ], "type": "string" }, "BuildIdParsingState": { "enum": [ "InProgress", "Succeeded", "Failed" ], "type": "string" }, "ClearDeviceTagsCommand": { "type": "object", "properties": { "deviceIds": { "type": [ "null", "array" ], "items": { "type": "string" } }, "filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DevicesFilter" } ] } } }, "ClearDeviceTagsResponse": { "required": [ "devicesUpdated" ], "type": "object", "properties": { "devicesUpdated": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "ComponentFilter": { "type": "object", "properties": { "vendor": { "type": [ "null", "string" ] }, "packageName": { "type": [ "null", "string" ] }, "version": { "type": [ "null", "string" ] } }, "description": "A single component identity (exact match on all three fields, null-aware)." }, "ComponentInfo": { "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "version": { "type": [ "null", "string" ] }, "cpe": { "type": [ "null", "string" ] }, "purl": { "type": [ "null", "string" ] }, "vendor": { "type": [ "null", "string" ] } } }, "ConditionThresholdType": { "enum": [ "FixedEquals", "FixedLowerThan", "FixedHigherThan", "FixedLowerOrEqual", "FixedHigherOrEqual", "PercentageChange", "PercentageIncrease", "PercentageDecrease" ], "type": "string" }, "CoreDumpAnalysisResponse": { "required": [ "id", "basicAnalysisState", "gdbAnalysisState", "aiAnalysisState", "createdAt" ], "type": "object", "properties": { "id": { "type": "string" }, "basicAnalysisState": { "$ref": "#/components/schemas/BasicAnalysisState" }, "basicAnalysisError": { "type": [ "null", "string" ] }, "gdbAnalysisState": { "$ref": "#/components/schemas/GdbAnalysisState" }, "gdbAnalysisError": { "type": [ "null", "string" ] }, "aiAnalysisState": { "$ref": "#/components/schemas/AiAnalysisState" }, "aiAnalysisError": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" }, "basicAnalysisSasLink": { "type": [ "null", "string" ], "description": "Time-limited link to the Brotli-compressed JSON representation of the basic analysis result.", "format": "uri" }, "gdbAnalysisSasLink": { "type": [ "null", "string" ], "description": "Time-limited link to the Brotli-compressed JSON representation of the GDB analysis result.", "format": "uri" }, "aiAnalysisSasLink": { "type": [ "null", "string" ], "description": "Time-limited link to the Brotli-compressed JSON representation of the AI analysis result.", "format": "uri" } } }, "CoreDumpResponse": { "required": [ "sasLinksExpiration", "contentSasLink" ], "type": "object", "properties": { "sasLinksExpiration": { "type": "string", "format": "date-time" }, "contentSasLink": { "type": "string", "description": "Time-limited link to the content of the core dump.", "format": "uri" }, "elfContentSasLink": { "type": [ "null", "string" ], "description": "Time-limited link to the ELF content of the core dump, if available.", "format": "uri" } } }, "CreateAlertRuleCommand": { "required": [ "name", "condition", "evaluationFrequency", "firstEvaluationAt" ], "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "condition": { "$ref": "#/components/schemas/AlertRuleCondition" }, "evaluationFrequency": { "$ref": "#/components/schemas/EvaluationFrequency" }, "firstEvaluationAt": { "type": "string", "format": "date-time" }, "notificationTargetIds": { "type": [ "null", "array" ], "items": { "type": "string" } }, "queryType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AlertRuleQueryType" } ] } } }, "CreateAlertTagCommand": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": [ "null", "string" ] } } }, "CreateDashboardCommand": { "required": [ "name", "definition" ], "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "definition": { "$ref": "#/components/schemas/JsonElement" } } }, "CreateDeploymentArtifactCommand": { "type": "object", "properties": { "firmware": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreateDeploymentArtifactFirmwareCommand" } ] } } }, "CreateDeploymentArtifactFirmwareCommand": { "required": [ "firmwareVersionId", "isMain" ], "type": "object", "properties": { "firmwareVersionId": { "type": "string" }, "isMain": { "type": "boolean" } } }, "CreateDeploymentCohortCommand": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string" }, "deviceIds": { "type": [ "null", "array" ], "items": { "type": "string" } }, "filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DevicesFilter" } ] } } }, "CreateDeploymentCommand": { "required": [ "name", "artifacts" ], "type": "object", "properties": { "name": { "type": "string" }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/CreateDeploymentArtifactCommand" } } } }, "CreateFirmwareCommand": { "required": [ "name", "slug" ], "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } }, "CreateIngestionKeyCommand": { "required": [ "displayName" ], "type": "object", "properties": { "displayName": { "type": "string" }, "description": { "type": [ "null", "string" ] } } }, "CreateNotificationTargetCommand": { "required": [ "name", "type" ], "type": "object", "properties": { "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/NotificationTargetType" }, "emailAddresses": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "CreateWorkspaceInvitesCommand": { "required": [ "emails" ], "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" } } } }, "CurrentApiKey": { "required": [ "id", "kind", "displayPrefix", "displayName", "scopes", "workspaces" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "$ref": "#/components/schemas/ApiKeyKind" }, "displayPrefix": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyScope" } }, "expiresOn": { "type": [ "null", "string" ], "format": "date" }, "workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceListItem" }, "description": "Every workspace the key can reach. A workspace key has exactly one, a user key has the workspaces its\nowner is a member of, narrowed by the key's workspace access." } }, "description": "What the key presented on the request is allowed to do, so a caller that holds nothing but the secret\ncan discover its own workspaces and scopes." }, "CustomMetricsCommand": { "required": [ "query", "from", "to" ], "type": "object", "properties": { "query": { "type": "string" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "CveDetail": { "required": [ "id", "source", "description", "severity", "cvssScores", "references", "cwes", "publishedAt", "modifiedAt" ], "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "sourceUrl": { "type": [ "null", "string" ] }, "description": { "type": "string" }, "status": { "type": [ "null", "string" ] }, "severity": { "$ref": "#/components/schemas/Severity" }, "primaryBaseScore": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "cvssScores": { "type": "array", "items": { "$ref": "#/components/schemas/CvssScoreItem" } }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/ReferenceItem" } }, "cwes": { "type": "array", "items": { "$ref": "#/components/schemas/CweItem" } }, "publishedAt": { "type": "string", "format": "date-time" }, "modifiedAt": { "type": "string", "format": "date-time" } } }, "CvssScoreItem": { "required": [ "version", "baseScore" ], "type": "object", "properties": { "version": { "type": "string" }, "vectorString": { "type": [ "null", "string" ] }, "baseScore": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "baseSeverity": { "type": [ "null", "string" ] }, "source": { "type": [ "null", "string" ] } } }, "CweItem": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "null", "string" ] } } }, "Dashboard": { "required": [ "id", "name", "createdAt", "updatedAt", "definition" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "creatorSubjectId": { "type": [ "null", "string" ], "format": "uuid" }, "updaterSubjectId": { "type": [ "null", "string" ], "format": "uuid" }, "definition": { "$ref": "#/components/schemas/JsonElement" } } }, "DashboardListItem": { "required": [ "id", "name", "createdAt", "updatedAt" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "creatorSubjectId": { "type": [ "null", "string" ], "format": "uuid" }, "updaterSubjectId": { "type": [ "null", "string" ], "format": "uuid" } } }, "DateTimeFilterOperator": { "type": "object", "properties": { "from": { "type": [ "null", "string" ], "format": "date-time" }, "to": { "type": [ "null", "string" ], "format": "date-time" } } }, "DeleteDevicesCommand": { "type": "object", "properties": { "deviceIds": { "type": [ "null", "array" ], "items": { "type": "string" } }, "filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DevicesFilter" } ] } } }, "DeleteDevicesResponse": { "required": [ "devicesDeleted" ], "type": "object", "properties": { "devicesDeleted": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "Deployment": { "required": [ "id", "name", "deploymentCohortId", "createdAt", "isActive", "artifacts", "deviceUpdateStateCounts" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "deploymentCohortId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "isActive": { "type": "boolean" }, "endedAt": { "type": [ "null", "string" ], "format": "date-time" }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/DeploymentArtifact" } }, "deviceUpdateStateCounts": { "$ref": "#/components/schemas/DeviceUpdateStateCounts" } } }, "DeploymentArtifact": { "required": [ "id", "order" ], "type": "object", "properties": { "id": { "type": "string" }, "order": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "firmware": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeploymentArtifactFirmware" } ] } } }, "DeploymentArtifactFirmware": { "required": [ "isMain", "firmwareVersion" ], "type": "object", "properties": { "isMain": { "type": "boolean" }, "slug": { "type": [ "null", "string" ] }, "firmwareVersion": { "$ref": "#/components/schemas/DeploymentArtifactFirmwareVersion" } } }, "DeploymentArtifactFirmwareDefinition": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "DeploymentArtifactFirmwareVersion": { "required": [ "id", "name", "firmware" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "firmware": { "$ref": "#/components/schemas/DeploymentArtifactFirmwareDefinition" } } }, "DeploymentCohort": { "required": [ "id", "name", "createdAt" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "DeploymentCohortFilter": { "type": "object", "properties": { "in": { "type": [ "null", "array" ], "items": { "type": "string" } }, "notIn": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "DeploymentCohortListItem": { "required": [ "id", "name", "createdAt", "deviceCount" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "deviceCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "DesiredConfiguration": { "type": "object", "properties": { "logSeverity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeviceLogSeverity" } ] } } }, "DesiredConfigurationResponse": { "type": "object", "properties": { "configuration": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DesiredConfiguration" } ] }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" } } }, "DeviceCohortReference": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "DeviceDetail": { "required": [ "deviceId", "createdAt", "firmwares", "statusFlags", "tags" ], "type": "object", "properties": { "deviceId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "firmwares": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceReportedFirmware" } }, "latestReportedBuildId": { "type": [ "null", "string" ] }, "statusFlags": { "type": "array", "items": { "$ref": "#/components/schemas/StatusFlag" } }, "tags": { "type": "object", "additionalProperties": { "type": "string" } }, "cohort": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeviceCohortReference" } ] } } }, "DeviceFirmwareFilter": { "type": "object", "properties": { "firmwareIds": { "type": [ "null", "array" ], "items": { "type": "string" } }, "firmwareVersionIds": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "DeviceListItem": { "required": [ "deviceId", "createdAt", "firmwares", "statusFlags", "tags" ], "type": "object", "properties": { "deviceId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "firmwares": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceReportedFirmware" } }, "latestReportedBuildId": { "type": [ "null", "string" ] }, "statusFlags": { "type": "array", "items": { "$ref": "#/components/schemas/StatusFlag" } }, "tags": { "type": "object", "additionalProperties": { "type": "string" } }, "cohort": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeviceCohortReference" } ] } } }, "DeviceLogSeverity": { "enum": [ "Debug", "Info", "Warning", "Error", "Critical" ], "type": [ "null", "string" ] }, "DeviceReportedFirmware": { "required": [ "id", "name", "firmwareVersions" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "firmwareVersions": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceReportedFirmwareVersion" } } } }, "DeviceReportedFirmwareVersion": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "DevicesFilter": { "type": "object", "properties": { "createdAt": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/DateTimeFilterOperator" } }, "deviceId": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/TextFilterOperator" } }, "statusFlags": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/StatusFlag" } }, "firmware": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeviceFirmwareFilter" } ] }, "tags": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/DeviceTagFilter" } }, "cohort": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeploymentCohortFilter" } ] } } }, "DeviceSortColumn": { "enum": [ "DeviceId", "CreatedAt" ], "type": [ "null", "string" ] }, "DeviceTagFilter": { "required": [ "tagName" ], "type": "object", "properties": { "tagName": { "type": "string" }, "equals": { "type": [ "null", "string" ] }, "notEquals": { "type": [ "null", "string" ] }, "in": { "type": [ "null", "array" ], "items": { "type": "string" } }, "notIn": { "type": [ "null", "array" ], "items": { "type": "string" } }, "contains": { "type": [ "null", "string" ] }, "notContains": { "type": [ "null", "string" ] }, "exists": { "type": [ "null", "boolean" ] }, "notExists": { "type": [ "null", "boolean" ] } } }, "DeviceUpdate": { "required": [ "deviceId", "state", "attempts" ], "type": "object", "properties": { "deviceId": { "type": "string" }, "state": { "$ref": "#/components/schemas/DeviceUpdateAttemptState" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceUpdateAttempt" } } } }, "DeviceUpdateAttempt": { "required": [ "id", "deviceId", "deploymentId", "createdAt", "state", "artifacts" ], "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "uint64" }, "deviceId": { "type": "string" }, "deploymentId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "state": { "$ref": "#/components/schemas/DeviceUpdateAttemptState" }, "updateAttemptError": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UpdateAttemptError" } ] }, "manifestSentToDeviceAt": { "type": [ "null", "string" ], "format": "date-time" }, "lastArtifactStateChangedAt": { "type": [ "null", "string" ], "format": "date-time" }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceUpdateAttemptArtifact" } } } }, "DeviceUpdateAttemptArtifact": { "required": [ "id", "deploymentArtifactId", "state" ], "type": "object", "properties": { "id": { "type": "string" }, "deploymentArtifactId": { "type": "string" }, "state": { "$ref": "#/components/schemas/DeviceUpdateAttemptArtifactState" }, "firmware": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeploymentArtifactFirmware" } ] } } }, "DeviceUpdateAttemptArtifactState": { "enum": [ "Pending", "InProgress", "Succeeded", "Failed", "Cancelled" ], "type": "string" }, "DeviceUpdateAttemptState": { "enum": [ "Pending", "InProgress", "Succeeded", "Failed", "Cancelled" ], "type": "string" }, "DeviceUpdatesFilter": { "type": "object", "properties": { "deviceId": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/TextFilterOperator" } }, "state": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/DeviceUpdateAttemptState" } } } }, "DeviceUpdateSortColumn": { "enum": [ "DeviceId" ], "type": [ "null", "string" ] }, "DeviceUpdateStateCounts": { "required": [ "pending", "inProgress", "succeeded", "failed", "cancelled" ], "type": "object", "properties": { "pending": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "inProgress": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "succeeded": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "failed": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "cancelled": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "EvaluationFrequency": { "enum": [ "5m", "10m", "30m", "1h", "2h", "3h", "6h", "12h", "24h" ], "type": "string" }, "EvaluationSimulationPoint": { "required": [ "timestamp", "isFiring" ], "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "isFiring": { "type": "boolean" } } }, "EvaluationWindow": { "enum": [ "5m", "10m", "30m", "1h", "2h", "3h", "6h", "12h", "24h", "7d" ], "type": "string" }, "EventCountItem": { "required": [ "count", "timestamp", "severity" ], "type": "object", "properties": { "count": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "timestamp": { "type": "string", "format": "date-time" }, "severity": { "$ref": "#/components/schemas/EventSeverity" } } }, "EventFirmwareFilter": { "type": "object", "properties": { "firmwareIds": { "type": [ "null", "array" ], "items": { "type": "string" } }, "firmwareVersionIds": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "EventItem": { "required": [ "deviceId", "timestamp", "deviceTimestampMs", "deviceUptimeMs", "body", "bodyTemplate", "severity", "bodyTemplateValues", "labels", "eventType", "coreDumpId", "crashReportId", "buildId", "sequenceNumber", "transportRoute" ], "type": "object", "properties": { "deviceId": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "deviceTimestampMs": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "deviceUptimeMs": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "body": { "type": "string" }, "bodyTemplate": { "type": "string" }, "severity": { "$ref": "#/components/schemas/EventSeverity" }, "bodyTemplateValues": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "object", "additionalProperties": { "type": "string" } }, "eventType": { "$ref": "#/components/schemas/EventType" }, "coreDumpId": { "type": "string" }, "crashReportId": { "type": "string" }, "buildId": { "type": "string" }, "sequenceNumber": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" }, "transportRoute": { "type": "array", "items": { "type": "string" } } } }, "EventsCommand": { "required": [ "filter" ], "type": "object", "properties": { "filter": { "$ref": "#/components/schemas/EventsFilter" }, "offset": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" } } }, "EventsCountCommand": { "required": [ "filter" ], "type": "object", "properties": { "filter": { "$ref": "#/components/schemas/EventsFilter" }, "intervalSeconds": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" } } }, "EventsCountResponse": { "required": [ "counts", "totalCount" ], "type": "object", "properties": { "counts": { "type": "array", "items": { "$ref": "#/components/schemas/EventCountItem" } }, "totalCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int64" } } }, "EventSeverity": { "enum": [ "Unknown", "Debug", "Info", "Warning", "Error", "Critical" ], "type": "string" }, "EventsFilter": { "required": [ "fromTimestamp" ], "type": "object", "properties": { "fromTimestamp": { "type": "string", "format": "date-time" }, "toTimestamp": { "type": [ "null", "string" ], "format": "date-time" }, "severity": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/EventSeverity" } }, "device": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/FilterOperator" } }, "body": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/FilterOperator" } }, "bodyTemplate": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/FilterOperator" } }, "labels": { "type": [ "null", "object" ], "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/FilterOperator" } } }, "eventType": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/EventType" } }, "firmware": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EventFirmwareFilter" } ] } } }, "EventsResponse": { "required": [ "events" ], "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventItem" } } } }, "EventType": { "enum": [ "Log", "SystemEvent", "CrashReport" ], "type": "string" }, "FilterOperator": { "type": "object", "properties": { "equals": { "type": [ "null", "string" ] }, "notEquals": { "type": [ "null", "string" ] }, "in": { "type": [ "null", "array" ], "items": { "type": "string" } }, "notIn": { "type": [ "null", "array" ], "items": { "type": "string" } }, "contains": { "type": [ "null", "string" ] }, "notContains": { "type": [ "null", "string" ] } } }, "FindingAssessment": { "enum": [ "NotAssessed", "InTriage", "Affected", "NotAffected" ], "type": "string", "description": "How a vulnerability finding has been assessed for a firmware version. Findings start as\n`NotAssessed` and move through triage to a resolution." }, "Firmware": { "required": [ "id", "name", "slug", "createdAt", "isUsedInDeployment" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "versionsCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "isUsedInDeployment": { "type": "boolean" }, "deviceCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Number of devices whose last reported build id belongs to this firmware.", "format": "int32" } } }, "FirmwareImageContentResponse": { "required": [ "contentSasLink", "fileName" ], "type": "object", "properties": { "contentSasLink": { "type": "string", "format": "uri" }, "fileName": { "type": "string" } } }, "FirmwareListItem": { "required": [ "id", "name", "slug", "createdAt" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "versionsCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "deviceCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Number of devices whose last reported build id belongs to this firmware.", "format": "int32" } } }, "FirmwareVersion": { "required": [ "id", "name", "createdAt", "isUsedInDeployment" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "assignedSymbolFilesCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "firmwareImageId": { "type": [ "null", "string" ] }, "isUsedInDeployment": { "type": "boolean" }, "deviceCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Number of devices whose last reported build id belongs to this firmware version.", "format": "int32" } } }, "FirmwareVersionComponentListItem": { "type": "object", "properties": { "vendor": { "type": [ "null", "string" ] }, "packageName": { "type": [ "null", "string" ] }, "version": { "type": [ "null", "string" ] }, "commitHash": { "type": [ "null", "string" ], "description": "Git commit hash when the component is pinned to a revision rather than a released version." }, "purl": { "type": [ "null", "string" ] }, "cpe": { "type": [ "null", "string" ] }, "pathsToRoot": { "type": [ "null", "array" ], "items": { "type": "array", "items": { "type": "string" } }, "description": "Union of all distinct dependency chains (each ordered root→component) across the collapsed rows." } }, "description": "One distinct component identity within a firmware version, collapsed across all its SBOMs by\n`(Vendor, PackageName, Version)`. There is no per-row id because the identity spans SBOM rows;\nstring? FirmwareVersionComponentListItem.Cpe/string? FirmwareVersionComponentListItem.Purl/string? FirmwareVersionComponentListItem.CommitHash come from the first occurrence, and\nIReadOnlyList<IReadOnlyList<string>>? FirmwareVersionComponentListItem.PathsToRoot is the union of every collapsed row's dependency chains." }, "FirmwareVersionListItem": { "required": [ "id", "name", "createdAt", "isUsedInDeployment", "vulnerabilitySummary" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "assignedSymbolFilesCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "firmwareImageId": { "type": [ "null", "string" ] }, "isUsedInDeployment": { "type": "boolean" }, "deviceCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Number of devices whose last reported build id belongs to this firmware version.", "format": "int32" }, "vulnerabilitySummary": { "description": "Vulnerability summary for this firmware version (all-zero when it has no active findings).", "$ref": "#/components/schemas/VulnerabilityFindingsSummary" } } }, "FirmwareVersionVulnerabilitySummary": { "required": [ "totalActiveIssues", "countsBySeverity", "affectedDeviceCount", "knownCisaExploitCount" ], "type": "object", "properties": { "totalActiveIssues": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Total number of active (potentially-affected) findings for the firmware version.", "format": "int32" }, "countsBySeverity": { "type": "array", "items": { "$ref": "#/components/schemas/SeverityCount" } }, "affectedDeviceCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Number of devices currently running the firmware version (0 when there are no active issues).", "format": "int32" }, "knownCisaExploitCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Number of active findings whose CVE is in CISA's Known Exploited Vulnerabilities catalog.", "format": "int32" }, "lastEvaluatedAt": { "type": [ "null", "string" ], "description": "When this firmware version's vulnerability picture was last evaluated: the more recent of the global\nCVE database sync completion and the latest SBOM parse for this version. Null when neither has happened.", "format": "date-time" } }, "description": "Vulnerability summary for a single firmware version. Same shape as VulnerabilityFindingsSummary\nplus int FirmwareVersionVulnerabilitySummary.KnownCisaExploitCount - the latter is intentionally scoped to this per-firmware-version\nendpoint and is not surfaced on the cross-firmware-version summaries." }, "FixedThresholdAlertRuleCondition": { "required": [ "query", "thresholdValue", "thresholdType", "evaluationWindow" ], "type": "object", "properties": { "query": { "type": "string", "description": "The same [query](https://docs.spotflow.io/api-reference/metrics-query-syntax) that you can use with the metrics endpoint except that here you don't aggregate by time (`bin(...)`)." }, "thresholdValue": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "minimalTimeSeriesCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "thresholdType": { "$ref": "#/components/schemas/FixedThresholdType" }, "evaluationWindow": { "$ref": "#/components/schemas/EvaluationWindow" }, "frontendBuilderDefinition": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ] } } }, "FixedThresholdEvaluatedValue": { "required": [ "value" ], "type": "object", "properties": { "value": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } } }, "FixedThresholdType": { "enum": [ "Equals", "LowerThan", "HigherThan", "LowerOrEqual", "HigherOrEqual" ], "type": "string" }, "GdbAnalysisState": { "enum": [ "Skipped", "InProgress", "BaseAnalysisSucceeded", "BaseAnalysisSucceededFullFailed", "Succeeded", "Failed" ], "type": "string" }, "IgnoreInfo": { "required": [ "ignored" ], "type": "object", "properties": { "ignored": { "type": "boolean", "description": "The ignore flag this entry set the finding to (true = ignored, false = un-ignored)." } } }, "IngestionKey": { "required": [ "id", "createdAt", "secret", "displayName" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": [ "null", "string" ] } } }, "IngestionKeyListItem": { "required": [ "id", "createdAt", "displayName" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "displayName": { "type": "string" }, "description": { "type": [ "null", "string" ] } } }, "JsonElement": { }, "JsonObject": { "type": "object" }, "LabelKeysResponse": { "required": [ "labelKeys" ], "type": "object", "properties": { "labelKeys": { "type": "array", "items": { "type": "string" } } } }, "LabelValuesResponse": { "required": [ "labelValues" ], "type": "object", "properties": { "labelValues": { "type": "array", "items": { "type": "string" } } } }, "ListAlertEvaluatedTimeSeriesCommand": { "type": "object", "properties": { "ascending": { "type": [ "null", "boolean" ] }, "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "cursor": { "type": [ "null", "string" ] }, "filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AlertEvaluatedTimeSeriesFilter" } ] } } }, "ListAlertEvaluatedTimeSeriesResponse": { "required": [ "evaluatedTimeSeries" ], "type": "object", "properties": { "evaluatedTimeSeries": { "type": "array", "items": { "$ref": "#/components/schemas/AlertEvaluatedTimeSeriesItem" } }, "nextCursor": { "type": [ "null", "string" ] }, "hasMore": { "type": "boolean" } } }, "ListAlertsCommand": { "type": "object", "properties": { "sortColumn": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AlertSortColumn" } ] }, "ascending": { "type": [ "null", "boolean" ] }, "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "cursor": { "type": [ "null", "string" ] }, "filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AlertsFilter" } ] } } }, "ListAlertsResponse": { "required": [ "alerts" ], "type": "object", "properties": { "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/AlertListItem" } }, "nextCursor": { "type": [ "null", "string" ] }, "hasMore": { "type": "boolean" } } }, "ListDevicesCommand": { "type": "object", "properties": { "sortColumn": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeviceSortColumn" } ] }, "ascending": { "type": [ "null", "boolean" ] }, "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "cursor": { "type": [ "null", "string" ] }, "filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DevicesFilter" } ] } } }, "ListDevicesResponse": { "required": [ "devices", "totalCount" ], "type": "object", "properties": { "devices": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceListItem" } }, "nextCursor": { "type": [ "null", "string" ] }, "hasMore": { "type": "boolean" }, "totalCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "ListDeviceTagsResponse": { "required": [ "tagNames" ], "type": "object", "properties": { "tagNames": { "type": "array", "items": { "type": "string" } } } }, "ListDeviceTagValuesResponse": { "required": [ "values" ], "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string" } } } }, "ListDeviceUpdatesCommand": { "type": "object", "properties": { "sortColumn": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeviceUpdateSortColumn" } ] }, "ascending": { "type": [ "null", "boolean" ] }, "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "cursor": { "type": [ "null", "string" ] }, "filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeviceUpdatesFilter" } ] } } }, "ListDeviceUpdatesResponse": { "required": [ "deviceUpdates" ], "type": "object", "properties": { "deviceUpdates": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceUpdate" } }, "nextCursor": { "type": [ "null", "string" ] }, "hasMore": { "type": "boolean" } } }, "ListFirmwareVersionComponentsResponse": { "required": [ "components" ], "type": "object", "properties": { "components": { "type": "array", "items": { "$ref": "#/components/schemas/FirmwareVersionComponentListItem" } } }, "description": "The de-duplicated bill of materials for a firmware version: every distinct component identity across\nall of the firmware version's SBOMs, each returned once. Not paginated." }, "ListSbomComponentsCommand": { "type": "object", "properties": { "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "cursor": { "type": [ "null", "string" ] } } }, "ListSbomComponentsResponse": { "required": [ "components" ], "type": "object", "properties": { "components": { "type": "array", "items": { "$ref": "#/components/schemas/SbomComponentListItem" } }, "nextCursor": { "type": [ "null", "string" ] }, "hasMore": { "type": "boolean" } } }, "ListSbomsResponse": { "required": [ "sboms" ], "type": "object", "properties": { "sboms": { "type": "array", "items": { "$ref": "#/components/schemas/SbomListItem" } } } }, "ListVulnerabilityFindingsCommand": { "type": "object", "properties": { "sortColumn": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VulnerabilityFindingSortColumn" } ] }, "ascending": { "type": [ "null", "boolean" ] }, "limit": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "cursor": { "type": [ "null", "string" ] }, "filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VulnerabilityFindingsFilter" } ] } } }, "ListVulnerabilityFindingsResponse": { "required": [ "findings" ], "type": "object", "properties": { "findings": { "type": "array", "items": { "$ref": "#/components/schemas/VulnerabilityFindingListItem" } }, "nextCursor": { "type": [ "null", "string" ] }, "hasMore": { "type": "boolean" } } }, "MetricLabelKeysResponse": { "required": [ "labelKeys" ], "type": "object", "properties": { "labelKeys": { "type": "array", "items": { "type": "string" } } } }, "MetricLabelValuesResponse": { "required": [ "labelValues" ], "type": "object", "properties": { "labelValues": { "type": "array", "items": { "type": "string" } } } }, "MetricsListResponse": { "required": [ "metricNames" ], "type": "object", "properties": { "metricNames": { "type": "array", "items": { "type": "string" } } } }, "MetricsQueryColumn": { "required": [ "name", "type" ], "type": "object", "properties": { "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/MetricsQueryColumnType" } } }, "MetricsQueryColumnType": { "enum": [ "String", "DateTimeOffset", "Number", "Boolean" ], "type": "string" }, "MetricsQueryResponse": { "required": [ "columns", "rows" ], "type": "object", "properties": { "effectiveAggregation": { "type": [ "null", "string" ] }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/MetricsQueryColumn" } }, "rows": { "type": "array" } } }, "NameFilterOperator": { "type": "object", "properties": { "contains": { "type": [ "null", "string" ] }, "notContains": { "type": [ "null", "string" ] } }, "description": "A finding-name text filter. Only substring matching is supported, so exactly one of\nstring? NameFilterOperator.Contains / string? NameFilterOperator.NotContains is set per operator." }, "NotificationTarget": { "required": [ "id", "name", "type", "state", "alertRuleCount" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/NotificationTargetType" }, "state": { "$ref": "#/components/schemas/NotificationTargetState" }, "emailAddresses": { "type": [ "null", "array" ], "items": { "type": "string" } }, "alertRuleCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "NotificationTargetState": { "enum": [ "Enabled", "Disabled" ], "type": "string" }, "NotificationTargetType": { "enum": [ "Email" ], "type": "string" }, "Os": { "enum": [ "Zephyr", "EspIdf", "FreeRtos" ], "type": [ "null", "string" ] }, "PercentualThresholdAlertRuleCondition": { "required": [ "query", "thresholdValue", "thresholdType", "evaluationWindow" ], "type": "object", "properties": { "query": { "type": "string", "description": "The same [query](https://docs.spotflow.io/api-reference/metrics-query-syntax) that you can use with the metrics endpoint except that here you don't aggregate by time (`bin(...)`)." }, "thresholdValue": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "minimalTimeSeriesCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "thresholdType": { "$ref": "#/components/schemas/PercentualThresholdType" }, "evaluationWindow": { "$ref": "#/components/schemas/EvaluationWindow" }, "frontendBuilderDefinition": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonElement" } ] } } }, "PercentualThresholdEvaluatedValue": { "required": [ "previousValue", "currentValue", "percentualChange" ], "type": "object", "properties": { "previousValue": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "currentValue": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "percentualChange": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } } }, "PercentualThresholdType": { "enum": [ "Change", "Increase", "Decrease" ], "type": "string" }, "PreviewConditionCommand": { "required": [ "condition", "from", "to" ], "type": "object", "properties": { "condition": { "$ref": "#/components/schemas/AlertRuleCondition" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } }, "PreviewConditionResponse": { "required": [ "evaluationSimulation" ], "type": "object", "properties": { "evaluationSimulation": { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationSimulationPoint" } } } }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "ReferenceItem": { "required": [ "url" ], "type": "object", "properties": { "url": { "type": "string" }, "source": { "type": [ "null", "string" ] }, "tags": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "RemoveDevicesFromDeploymentCohortCommand": { "type": "object", "properties": { "deviceIds": { "type": [ "null", "array" ], "items": { "type": "string" } }, "filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DevicesFilter" } ] } } }, "ReportedConfiguration": { "type": "object", "properties": { "logSeverity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeviceLogSeverity" } ] }, "compiledLogSeverity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeviceLogSeverity" } ] }, "acknowledgedDesiredConfigurationVersion": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" } } }, "ReportedConfigurationResponse": { "type": "object", "properties": { "configuration": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ReportedConfiguration" } ] }, "version": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int64" } } }, "SbomBatchUploadResponse": { "required": [ "sboms" ], "type": "object", "properties": { "sboms": { "type": "array", "items": { "$ref": "#/components/schemas/SbomUploadResponse" } } }, "description": "Response for a multi-file SBOM upload: one SbomUploadResponse per accepted file." }, "SbomComponentListItem": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string" }, "packageName": { "type": [ "null", "string" ] }, "version": { "type": [ "null", "string" ] }, "commitHash": { "type": [ "null", "string" ], "description": "Git commit hash when the component is pinned to a revision rather than a released version." }, "purl": { "type": [ "null", "string" ] }, "cpe": { "type": [ "null", "string" ] }, "vendor": { "type": [ "null", "string" ] }, "pathsToRoot": { "type": [ "null", "array" ], "items": { "type": "array", "items": { "type": "string" } }, "description": "All distinct dependency chains from a graph root down to this component (each ordered root→component); null until parsed." } } }, "SbomContentResponse": { "required": [ "contentSasLink", "fileName" ], "type": "object", "properties": { "contentSasLink": { "type": "string", "format": "uri" }, "fileName": { "type": "string" } } }, "SbomFormat": { "enum": [ "Spdx3JsonLd", "Spdx2TagValue" ], "type": "string" }, "SbomListItem": { "required": [ "id", "fileName", "format", "parsingState", "componentCount", "createdAt" ], "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "format": { "$ref": "#/components/schemas/SbomFormat" }, "parsingState": { "$ref": "#/components/schemas/SbomParsingState" }, "componentCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "vulnerabilitiesParsedAt": { "type": [ "null", "string" ], "format": "date-time" } } }, "SbomParsingState": { "enum": [ "InProgress", "Succeeded", "Failed" ], "type": "string" }, "SbomReference": { "required": [ "sbomId", "fileName" ], "type": "object", "properties": { "sbomId": { "type": "string" }, "fileName": { "type": "string" }, "pathsToRoot": { "type": [ "null", "array" ], "items": { "type": "array", "items": { "type": "string" } }, "description": "All distinct dependency chains from this SBOM's root down to the matched component (each ordered root→component); null until parsed." } } }, "SbomUploadResponse": { "required": [ "id", "parsingState" ], "type": "object", "properties": { "id": { "type": "string" }, "parsingState": { "$ref": "#/components/schemas/SbomParsingState" } } }, "SetDeviceTagsCommand": { "required": [ "tags" ], "type": "object", "properties": { "tags": { "type": "object", "additionalProperties": { "type": "string" } } } }, "SetDeviceTagsResponse": { "required": [ "devicesUpdated" ], "type": "object", "properties": { "devicesUpdated": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "SetVulnerabilityFindingIgnoredCommand": { "required": [ "ignored" ], "type": "object", "properties": { "ignored": { "type": "boolean" } }, "description": "Sets the `ignored` flag on a vulnerability finding, independently of its assessment. Idempotent." }, "Severity": { "enum": [ "Unknown", "Low", "Medium", "High", "Critical" ], "type": "string" }, "SeverityCount": { "required": [ "severity", "count" ], "type": "object", "properties": { "severity": { "$ref": "#/components/schemas/Severity" }, "count": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "StartCoreDumpAnalysisCommand": { "required": [ "symbolFileId" ], "type": "object", "properties": { "symbolFileId": { "type": "string" } } }, "StatusFlag": { "enum": [ "IsCrashing" ], "type": "string" }, "SymbolFile": { "required": [ "id", "buildIdParsingState", "createdAt", "firmwareVersions", "firmware" ], "type": "object", "properties": { "id": { "type": "string" }, "alias": { "type": [ "null", "string" ] }, "buildId": { "type": [ "null", "string" ] }, "buildIdParsingState": { "$ref": "#/components/schemas/BuildIdParsingState" }, "createdAt": { "type": "string", "format": "date-time" }, "firmwareVersions": { "type": "array", "items": { "$ref": "#/components/schemas/SymbolFileFirmwareVersion" } }, "firmware": { "$ref": "#/components/schemas/SymbolFileFirmware" }, "os": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Os" } ] } } }, "SymbolFileContentResponse": { "required": [ "contentSasLink" ], "type": "object", "properties": { "contentSasLink": { "type": "string", "format": "uri" } } }, "SymbolFileFirmware": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "SymbolFileFirmwareVersion": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "SymbolFileListItem": { "required": [ "id", "buildIdParsingState", "createdAt", "firmwareVersions" ], "type": "object", "properties": { "id": { "type": "string" }, "alias": { "type": [ "null", "string" ] }, "buildId": { "type": [ "null", "string" ] }, "buildIdParsingState": { "$ref": "#/components/schemas/BuildIdParsingState" }, "createdAt": { "type": "string", "format": "date-time" }, "firmwareVersions": { "type": "array", "items": { "$ref": "#/components/schemas/SymbolFileFirmwareVersion" } } } }, "SystemMetricsCommand": { "required": [ "queryName" ], "type": "object", "properties": { "queryName": { "type": "string" }, "parameters": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsonObject" } ] } } }, "TextFilterOperator": { "type": "object", "properties": { "equals": { "type": [ "null", "string" ] }, "notEquals": { "type": [ "null", "string" ] }, "contains": { "type": [ "null", "string" ] }, "notContains": { "type": [ "null", "string" ] } } }, "TimelineEvent": { "required": [ "type", "timestamp" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/TimelineEventType" }, "timestamp": { "type": "string", "format": "date-time" }, "source": { "oneOf": [ { "type": "null" }, { "description": "Where the entry came from; present for user/SBOM entries (TimelineEventType.Assessment, TimelineEventType.Ignore), null for `Published`/`Detected`.", "$ref": "#/components/schemas/VulnerabilityFindingHistorySource" } ] }, "createdByEmail": { "type": [ "null", "string" ], "description": "Resolved author email for user-originated entries; null otherwise." }, "assessment": { "oneOf": [ { "type": "null" }, { "description": "Present only when TimelineEventType TimelineEvent.Type is TimelineEventType.Assessment.", "$ref": "#/components/schemas/AssessmentInfo" } ] }, "ignore": { "oneOf": [ { "type": "null" }, { "description": "Present only when TimelineEventType TimelineEvent.Type is TimelineEventType.Ignore.", "$ref": "#/components/schemas/IgnoreInfo" } ] } } }, "TimelineEventType": { "enum": [ "Published", "Detected", "CisaKnownExploit", "Assessment", "Ignore" ], "type": "string" }, "UpdateAlertCommand": { "type": "object", "properties": { "tagIds": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "UpdateAlertRuleCommand": { "required": [ "name", "state", "condition", "evaluationFrequency" ], "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "state": { "$ref": "#/components/schemas/AlertRuleState" }, "condition": { "$ref": "#/components/schemas/AlertRuleCondition" }, "evaluationFrequency": { "$ref": "#/components/schemas/EvaluationFrequency" }, "notificationTargetIds": { "type": [ "null", "array" ], "items": { "type": "string" } }, "queryType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AlertRuleQueryType" } ] } } }, "UpdateAlertTagCommand": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": [ "null", "string" ] } } }, "UpdateAttemptError": { "enum": [ "UnknownError", "ArtifactCountExceeded", "UnknownArtifactType", "CannotParseMessage" ], "type": [ "null", "string" ] }, "UpdateDashboardCommand": { "required": [ "name", "definition" ], "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "null", "string" ] }, "definition": { "$ref": "#/components/schemas/JsonElement" } } }, "UpdateDeploymentCohortCommand": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string" } } }, "UpdateDeploymentCommand": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string" } } }, "UpdateDesiredConfigurationCommand": { "type": "object", "properties": { "logSeverity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeviceLogSeverity" } ] } } }, "UpdateFirmwareCommand": { "required": [ "name", "slug" ], "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } }, "UpdateFirmwareVersionCommand": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string" } } }, "UpdateIngestionKeyCommand": { "required": [ "displayName" ], "type": "object", "properties": { "displayName": { "type": "string" }, "description": { "type": [ "null", "string" ] } } }, "UpdateNotificationTargetCommand": { "required": [ "name", "type", "state" ], "type": "object", "properties": { "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/NotificationTargetType" }, "state": { "$ref": "#/components/schemas/NotificationTargetState" }, "emailAddresses": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "UpdateSymbolFileCommand": { "type": "object", "properties": { "alias": { "type": [ "null", "string" ] }, "firmwareVersionIds": { "type": [ "null", "array" ], "items": { "type": "string" } } } }, "UpdateWorkspaceSettingsCommand": { "type": "object", "properties": { "timeZone": { "type": [ "null", "string" ] } } }, "UpsertDeviceTagsCommand": { "required": [ "tags" ], "type": "object", "properties": { "deviceIds": { "type": [ "null", "array" ], "items": { "type": "string" } }, "filter": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DevicesFilter" } ] }, "tags": { "type": "object", "additionalProperties": { "type": "string" } } } }, "UpsertDeviceTagsResponse": { "required": [ "devicesUpdated" ], "type": "object", "properties": { "devicesUpdated": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "UserInviteListItem": { "required": [ "id", "workspaceId", "createdByEmail", "createdAt" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "workspaceDisplayName": { "type": [ "null", "string" ] }, "createdByEmail": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "VulnerabilityFindingDetail": { "required": [ "id", "assessment", "ignored", "isKnownCisaExploit", "component", "cve", "affectedPackages", "sboms", "timeline" ], "type": "object", "properties": { "id": { "type": "string" }, "assessment": { "$ref": "#/components/schemas/FindingAssessment" }, "ignored": { "type": "boolean", "description": "When true the finding has been dismissed/hidden independently of its assessment." }, "isKnownCisaExploit": { "type": "boolean", "description": "True when the finding's CVE is in CISA's Known Exploited Vulnerabilities (KEV) catalog." }, "cisaKnownExploitCatalogUrl": { "type": [ "null", "string" ], "description": "Link to the CVE in CISA's KEV catalog; null unless bool VulnerabilityFindingDetail.IsKnownCisaExploit is true." }, "component": { "$ref": "#/components/schemas/ComponentInfo" }, "cve": { "$ref": "#/components/schemas/CveDetail" }, "affectedPackages": { "type": "array", "items": { "$ref": "#/components/schemas/AffectedPackageItem" } }, "sboms": { "type": "array", "items": { "$ref": "#/components/schemas/SbomReference" }, "description": "The SBOMs whose components back this finding (provenance)." }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEvent" }, "description": "Ordered timeline: CVE published, Spotflow detected, then each history entry (assessment or ignore)." } } }, "VulnerabilityFindingHistorySource": { "enum": [ "User", "SbomVex", "WorkspaceApiKey" ], "type": [ "null", "string" ] }, "VulnerabilityFindingListItem": { "required": [ "id", "cveId", "name", "severity", "assessment", "ignored", "isKnownCisaExploit", "detectedAt" ], "type": "object", "properties": { "id": { "type": "string" }, "cveId": { "type": "string" }, "name": { "type": "string", "description": "Display name of the issue - the primary CWE weakness name, falling back to the CVE id." }, "componentName": { "type": [ "null", "string" ] }, "componentVersion": { "type": [ "null", "string" ] }, "severity": { "$ref": "#/components/schemas/Severity" }, "assessment": { "$ref": "#/components/schemas/FindingAssessment" }, "ignored": { "type": "boolean", "description": "When true the finding has been dismissed/hidden independently of its assessment." }, "isKnownCisaExploit": { "type": "boolean", "description": "True when the finding's CVE is in CISA's Known Exploited Vulnerabilities (KEV) catalog." }, "detectedAt": { "type": "string", "format": "date-time" } } }, "VulnerabilityFindingsFilter": { "type": "object", "properties": { "severities": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/Severity" } }, "assessments": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/FindingAssessment" }, "description": "Filter by finding assessment with \"one of\" semantics; empty or unset returns every assessment.\nFor example `[NotAffected]` returns only findings resolved as not affected." }, "ignored": { "type": [ "null", "boolean" ], "description": "Filter by the `ignored` flag, independently of IReadOnlyList<FindingAssessment>? VulnerabilityFindingsFilter.Assessments. Unset returns every\nfinding; `true` returns only ignored findings; `false` returns only non-ignored findings." }, "knownCisaExploit": { "type": [ "null", "boolean" ], "description": "Filter by whether the finding's CVE is in CISA's Known Exploited Vulnerabilities catalog. Unset returns\nevery finding; `true` returns only known CISA exploits; `false` returns only the rest." }, "name": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/NameFilterOperator" }, "description": "Filter by the finding display name. Substring matching only — each operator sets exactly one of\n`contains` / `notContains`." }, "components": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/ComponentFilter" }, "description": "Filter by component identity with \"one of\" semantics: a finding matches when it is backed by a\ncomponent equal to any of the listed `(Vendor, PackageName, Version)` triples. Empty or unset\napplies no component filter." } } }, "VulnerabilityFindingSortColumn": { "enum": [ "Severity", "DetectedAt" ], "type": [ "null", "string" ] }, "VulnerabilityFindingsSummary": { "required": [ "totalActiveIssues", "countsBySeverity", "affectedDeviceCount" ], "type": "object", "properties": { "totalActiveIssues": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Total number of active (potentially-affected) findings for the firmware version.", "format": "int32" }, "countsBySeverity": { "type": "array", "items": { "$ref": "#/components/schemas/SeverityCount" } }, "affectedDeviceCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "Number of devices currently running the firmware version (0 when there are no active issues).", "format": "int32" }, "lastEvaluatedAt": { "type": [ "null", "string" ], "description": "When this firmware version's vulnerability picture was last evaluated: the more recent of the global\nCVE database sync completion and the latest SBOM parse for this version. Null when neither has happened.", "format": "date-time" } } }, "VulnerableFirmwareVersionItem": { "required": [ "firmwareId", "firmwareName", "firmwareVersionId", "firmwareVersionName", "createdAt", "vulnerabilitySummary" ], "type": "object", "properties": { "firmwareId": { "type": "string" }, "firmwareName": { "type": "string" }, "firmwareVersionId": { "type": "string" }, "firmwareVersionName": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "vulnerabilitySummary": { "$ref": "#/components/schemas/VulnerabilityFindingsSummary" } }, "description": "A firmware version that has at least one active vulnerability finding, with its vulnerability summary." }, "WorkspaceInviteListItem": { "required": [ "id", "invitedEmail", "createdBySubjectId", "createdByEmail", "createdAt" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invitedEmail": { "type": "string" }, "createdBySubjectId": { "type": "string", "format": "uuid" }, "createdByEmail": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "WorkspaceListItem": { "required": [ "id", "createdAt", "slug", "creatorSubjectId" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "displayName": { "type": [ "null", "string" ] }, "slug": { "type": "string" }, "creatorSubjectId": { "type": "string", "format": "uuid" } } }, "WorkspaceMemberListItem": { "required": [ "subjectId", "email", "createdAt", "isCreator" ], "type": "object", "properties": { "subjectId": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "isCreator": { "type": "boolean" } } }, "WorkspaceSettings": { "type": "object", "properties": { "timeZone": { "type": [ "null", "string" ] } } } }, "securitySchemes": { "API key": { "type": "http", "description": "API key (`sf_...`) with any of the required scopes. Generate it in the [Spotflow portal](https://app.spotflow.io/) on the settings page.", "scheme": "bearer" } } }, "tags": [ { "name": "Workspaces" }, { "name": "Workspace members" }, { "name": "SBOMs" }, { "name": "Vulnerability findings" }, { "name": "Symbol files" }, { "name": "Deployment cohorts" }, { "name": "Deployments" }, { "name": "Notification targets" }, { "name": "Metrics" }, { "name": "User invites" }, { "name": "Ingestion keys" }, { "name": "Firmware versions" }, { "name": "Firmwares" }, { "name": "Events" }, { "name": "Devices" }, { "name": "Device tags" }, { "name": "Dashboards" }, { "name": "Core dumps" }, { "name": "API keys" }, { "name": "Alert tags" }, { "name": "Alerts" }, { "name": "Alert rules" } ] }