> ## Documentation Index > Fetch the complete documentation index at: https://docs.kombify.io/llms.txt > Use this file to discover all available pages before exploring further. # Read per-drive SMART and NVMe health evidence > Authenticated, tenant-scoped projection of Guard drive observations. Self-hosted installations use their configured installation tenant. Hardware identities retain history independently of mutable device paths; replacements never inherit earlier readings. Anonymous observations have attempt-specific IDs and cannot establish historical continuity. Missing, unsupported, inaccessible, incomplete, stale and disconnected observations stay explicit and cannot imply healthy hardware. A server with no observations returns a missing state when selected explicitly. Last successful readings remain historical evidence when a new attempt fails. Only a complete inventory or an explicit missing observation can establish disconnection, and an unreadable identity at a seen path stays uncertain. Reads age evidence and condition episodes, without initiating collection, self-tests, repairs, provisioning or other device actions. Capacity growth forecasts remain on the separate storage-forecast route. ## OpenAPI ````yaml /techstack/reference/api/openapi.yaml get /api/v1/monitor/drive-health openapi: 3.1.0 info: title: kombify-TechStack API description: > REST API for kombify-TechStack -- the hybrid cloud control plane for homelabs. kombify-TechStack manages infrastructure through a spec-driven architecture: validate YAML specs via CUE, generate OpenTofu configurations, and manage nodes through a gRPC agent protocol. ## Authentication Authenticated endpoints accept an OIDC/JWKS bearer token or an API key where documented. Self-hosted TechStack defaults to Pocket ID as identity provider. SaaS routes enter through the edge with Auth0 as the platform identity provider. PocketBase session exchange remains legacy migration compatibility only. ## Response Format **Success:** `{ "data": , "meta": { "total": int, "page": int, "per_page": int } }` **Error:** `{ "error": { "code": "", "message": "...", "details": } }` ## Pagination List endpoints accept `page` (default: 1) and `per_page` (default: 20, max: 100) query parameters. version: 1.0.0 contact: name: kombify url: https://kombify.io license: name: Apache-2.0 AND GPL-3.0 url: https://github.com/KombiverseLabs/kombify-TechStack/blob/main/LICENSE servers: - url: https://api.kombify.io/v1/techstack description: >- Production canonical (via Cloudflare edge gateway, strip-prefix). Clients MUST use this projection. The Gateway strips /v1/techstack and re-adds /api/v1 at the origin, so it resolves the /api/v1/* paths below cleanly. - url: http://localhost:5260 description: Local development - url: https://techstack.kombify.io description: Production (direct, no Gateway prefix) - url: https://api.kombify.io/v1/orchestrator description: >- Legacy StackKit-Orchestrator projection of the same origin. RETAINED for backward compatibility with existing consumers only. Do NOT use for mobile or new clients: combined with the /api/v1/* paths it double-resolves (yielding /v1/orchestrator/api/v1/...). Prefer /v1/techstack. security: - bearerAuth: [] tags: - name: Health description: Health checks and service info (no auth required) - name: Instance description: Local instance identity and enrollment metadata - name: Stacks description: Stack lifecycle management (create, provision, deploy, destroy) - name: Stacks - Specs description: Access persisted specification chain (intent, requirements, unified) - name: Stacks - Import/Export description: Import and export StackKits stack-spec.yaml configurations - name: Stacks - Drift description: Infrastructure drift detection and resolution - name: Unifier description: Spec validation, analysis, unification, and IaC generation pipeline - name: StackKits description: Infrastructure template catalog - name: Add-ons description: Add-on detection and registry - name: Workers description: Worker node registration and management - name: Servers description: Canonical server lifecycle, connection, and health state - name: Inventory description: >- Owner-scoped sanitized server and service read models for UI, API, and MCP clients - name: Pre-Checks description: Pre-deployment hardware and software validation - name: Agents description: Connected gRPC agent management and commands - name: Jobs description: Background job monitoring and SSE streaming - name: Discovery description: Network device discovery and SSH testing - name: Features description: Feature flags (read-only; managed centrally via the kombify Admin API) - name: Monthly Runtime description: Provider-free user API for subscription-backed stack runtime control - name: Runtime description: Recent runtime/deploy logs (job/deploy progress + container tail) - name: Wallet description: >- Redacted recovery-item wallet with biometric/platform-reauth-gated reveal. List responses strip secret/totp; reveal requires a fresh trusted-reauth HMAC proof (5-minute window) and is audited server-side. - name: Trust description: Pairing tokens for worker enrollment - name: Client Binding description: >- Short-lived HTTPS pairing for a second client and normal OIDC account handoff - name: Tunnel description: Cloudflare tunnel management for NAT traversal - name: Backups description: Database backup management (admin only) - name: Auth description: Authentication mode and SSO configuration - name: Metrics description: Prometheus-compatible instance metrics for admin/infra scrapers - name: Internal description: >- Internal SaaS-only APIs, including servicecall-protected executor contracts paths: /api/v1/monitor/drive-health: get: tags: - Metrics summary: Read per-drive SMART and NVMe health evidence description: > Authenticated, tenant-scoped projection of Guard drive observations. Self-hosted installations use their configured installation tenant. Hardware identities retain history independently of mutable device paths; replacements never inherit earlier readings. Anonymous observations have attempt-specific IDs and cannot establish historical continuity. Missing, unsupported, inaccessible, incomplete, stale and disconnected observations stay explicit and cannot imply healthy hardware. A server with no observations returns a missing state when selected explicitly. Last successful readings remain historical evidence when a new attempt fails. Only a complete inventory or an explicit missing observation can establish disconnection, and an unreadable identity at a seen path stays uncertain. Reads age evidence and condition episodes, without initiating collection, self-tests, repairs, provisioning or other device actions. Capacity growth forecasts remain on the separate storage-forecast route. operationId: getMonitorDriveHealth parameters: - $ref: '#/components/parameters/driveHealthServerId' responses: '200': description: >- Current collection state, retained drive readings and durable condition episodes content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/DriveHealthResponse' meta: $ref: '#/components/schemas/ResponseMeta' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '503': $ref: '#/components/responses/DriveHealthUnavailable' components: parameters: driveHealthServerId: name: server_id in: query required: false description: >- Restrict evidence to one server within the authenticated tenant; an unobserved server remains explicitly missing. schema: type: string maxLength: 128 schemas: DriveHealthResponse: type: object required: - generated_at - servers properties: generated_at: type: string format: date-time servers: type: array items: $ref: '#/components/schemas/DriveHealthServerState' ResponseMeta: type: object properties: total: type: integer page: type: integer per_page: type: integer managed_runtime_inventory_complete: type: boolean description: >- True only when the managed RuntimeLease authority was configured and read successfully for this inventory response. worker_inventory_sha256: type: string pattern: ^[0-9a-f]{64}$ description: >- Stable digest of the complete worker identity, attachment, freshness, and managed RuntimeLease authority snapshot used for pagination. managed_runtime_active_lease_ids: type: array items: type: string description: >- Canonically sorted IDs of visible managed RuntimeLeases classified as active for inventory and cleanup. This visibility projection is not capacity reservation or release authority. managed_runtime_inactive_lease_ids: type: array items: type: string description: >- Canonically sorted IDs of visible managed RuntimeLeases classified as cancelled or archived for inventory and cleanup. Inactive state does not prove provider absence or release managed-server capacity. managed_runtime_lease_generation_digests: type: array items: type: object required: - lease_id - resource_generation_digest properties: lease_id: type: string resource_generation_digest: type: string pattern: ^[0-9a-f]{64}$ description: >- Canonically sorted opaque bindings from each visible managed RuntimeLease ID to its exact provider-resource generation. Missing coverage makes destructive inventory proof invalid while leaving ordinary dashboard inventory readable. managed_runtime_duplicate_lease_ids: type: array items: type: string description: >- Managed RuntimeLease IDs represented by multiple persisted worker rows before UI projection deduplication; must be empty for destructive inventory proof. managed_runtime_attachment_conflict_lease_ids: type: array items: type: string description: >- Canonically sorted caller-visible managed RuntimeLease IDs with a conflicting tenant-wide worker attachment; must be empty for destructive inventory proof and never exposes foreign private lease or worker details. DriveHealthServerState: type: object required: - server_id - worker_id - last_attempt_at - collection_status - inventory_complete - drives - alerts properties: server_id: type: string worker_id: type: string description: >- Authenticated Guard identity; empty when the selected server has no observation. last_attempt_at: type: string format: date-time description: >- Latest accepted collection attempt; the zero timestamp 0001-01-01T00:00:00Z denotes no observation. collection_status: $ref: '#/components/schemas/DriveObservationState' collection_reason: type: string inventory_complete: type: boolean description: >- Only a complete inventory supports inference that an absent known identity disconnected. drives: type: array items: $ref: '#/components/schemas/DriveHealthState' alerts: type: array description: >- Server collection conditions, including path-scoped anonymous availability incidents. items: $ref: '#/components/schemas/DriveHealthAlert' ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - INTERNAL_ERROR - NOT_FOUND - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - CONFLICT - VALIDATION_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - METHOD_NOT_ALLOWED message: type: string details: description: Additional error context (validation errors, etc.) DriveHealthUnavailableError: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string const: INTERNAL_ERROR message: type: string details: type: object properties: reason_code: type: string const: drive_health_persistence_unavailable retryable: type: boolean const: true DriveObservationState: type: string enum: - available - incomplete - unsupported - inaccessible - missing - stale - disconnected description: >- Observation availability, independently of the hardware health assessment. DriveHealthState: type: object required: - drive_id - device_path - observation_status - health - last_attempt_at - last_attempt - last_success - alerts properties: drive_id: type: string description: >- Immutable hardware-derived identity, or an attempt-specific unidentified-* display ID with no historical continuity. device_path: type: string observation_status: $ref: '#/components/schemas/DriveObservationState' health: type: string enum: - healthy - warning - critical - unknown description: >- Current supported evidence assessment; failed, incomplete or stale collection cannot establish health from absent values. last_attempt_at: type: string format: date-time description: >- Latest attempt, including an ambiguous identity read at a previously observed path; it may be newer than last_attempt.observed_at. last_attempt: oneOf: - $ref: '#/components/schemas/DriveHealthReading' - type: 'null' last_success: description: >- Last available identified reading; retained as historical evidence across failed or incomplete attempts. oneOf: - $ref: '#/components/schemas/DriveHealthReading' - type: 'null' alerts: type: array items: $ref: '#/components/schemas/DriveHealthAlert' DriveHealthAlert: type: object required: - id - worker_id - server_id - category - code - severity - message - evidence - recommended_step - first_seen_at - last_seen_at properties: id: type: string format: uuid description: Stable condition episode identity. worker_id: type: string condition_key: type: string description: >- Stable server/path availability key for anonymous collection incidents; does not identify physical hardware. server_id: type: string drive_id: type: string description: >- Attributable drive identity; absent on server or anonymous path collection conditions. category: type: string enum: - collection - hardware code: type: string enum: - collection - stale - observation - disconnected - smart_failed - self_test_failed - attribute_failed - nvme_warning - wear - spare - temperature - media_errors - media_errors_increase - error_log_entries_increase - reallocated_sectors - reallocated_sectors_increase - pending_sectors - pending_sectors_increase - uncorrectable_sectors - uncorrectable_sectors_increase severity: type: string enum: - info - warning - critical message: type: string description: Technical fallback; customer clients localize by condition code. evidence: type: object additionalProperties: type: string description: >- Measured values, source/time/path and condition-specific interpretation or threshold_source (device or guard_policy). recommended_step: type: string description: >- Technical next-step guidance; clients localize recommendations by condition code. first_seen_at: type: string format: date-time last_seen_at: type: string format: date-time resolved_at: type: string format: date-time description: >- Present only after fresh evidence resolves the episode; absence means active, including when later fields are missing. DriveHealthReading: type: object required: - drive_id - device_path - protocol - model - serial - wwn - source - observed_at - status - missing - smart_passed - attribute_failed - temperature_celsius - temperature_warning_celsius - temperature_critical_celsius - critical_warning - percentage_used - available_spare - spare_threshold - media_errors - error_log_entries - self_test_failed - reallocated_sectors - pending_sectors - uncorrectable_sectors - power_on_hours - wear_attributes properties: drive_id: type: string description: >- SHA-256 of hardware identity, or empty when identity could not be read; never derived from the path. pattern: ^(|[a-f0-9]{64})$ device_path: type: string protocol: type: string enum: - ATA - NVMe - SCSI - '' model: type: string maxLength: 256 serial: type: string maxLength: 256 wwn: type: string maxLength: 256 source: type: string enum: - smartctl - nvme_cli - inventory observed_at: type: string format: date-time status: type: string enum: - available - incomplete - unsupported - inaccessible - missing reason: type: string missing: type: - array - 'null' maxItems: 20 uniqueItems: true items: type: string enum: - identity - smart_passed - attribute_failed - temperature_celsius - critical_warning - percentage_used - available_spare - spare_threshold - media_errors - error_log_entries - self_test_failed - reallocated_sectors - pending_sectors - uncorrectable_sectors - power_on_hours smart_passed: type: - boolean - 'null' attribute_failed: type: - boolean - 'null' self_test_failed: type: - boolean - 'null' description: >- Failed latest reported self-test result; null denotes unreported or unavailable evidence, not a passing test. Reading never starts a self-test. temperature_celsius: type: - number - 'null' minimum: -273.15 maximum: 1000 temperature_warning_celsius: type: - number - 'null' minimum: -273.15 maximum: 1000 temperature_critical_celsius: type: - number - 'null' minimum: -273.15 maximum: 1000 description: >- Device-reported critical limit. Missing device limits use advisory Guard policy thresholds (65 C warning, 80 C critical), identified in alert evidence as guard_policy rather than a vendor failure threshold. critical_warning: type: - integer - 'null' minimum: 0 maximum: 255 description: >- NVMe critical-warning bit mask; nonzero bits retain their device meaning. percentage_used: type: - integer - 'null' minimum: 0 maximum: 255 description: >- Manufacturer estimate of consumed rated endurance, which may exceed 100. It is neither remaining life nor a precise failure forecast; crossing 90 or 100 is advisory warning absent independent failing evidence. available_spare: type: - integer - 'null' minimum: 0 maximum: 100 spare_threshold: type: - integer - 'null' minimum: 0 maximum: 100 media_errors: $ref: '#/components/schemas/DriveHealthCounter' error_log_entries: allOf: - $ref: '#/components/schemas/DriveHealthCounter' description: >- Cumulative NVMe error-log entries; command errors alone do not establish media failure. Increases receive an advisory inspect-log condition. reallocated_sectors: $ref: '#/components/schemas/DriveHealthCounter' pending_sectors: $ref: '#/components/schemas/DriveHealthCounter' uncorrectable_sectors: $ref: '#/components/schemas/DriveHealthCounter' power_on_hours: $ref: '#/components/schemas/DriveHealthCounter' wear_attributes: type: - array - 'null' maxItems: 16 items: $ref: '#/components/schemas/DriveHealthWearAttribute' DriveHealthCounter: type: - string - 'null' pattern: ^(0|[1-9][0-9]{0,38})$ description: >- Exact unsigned decimal counter bounded to 128 bits. Null means unreported; clients must preserve precision rather than convert to a floating-point number. DriveHealthWearAttribute: type: object required: - id - name - value - raw - interpretation properties: id: type: integer minimum: 1 maximum: 255 name: type: string value: type: - integer - 'null' minimum: 0 maximum: 255 description: >- Manufacturer-normalized attribute, without universal percentage interpretation. raw: $ref: '#/components/schemas/DriveHealthCounter' interpretation: type: string enum: - vendor_specific responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' DriveHealthUnavailable: description: > Drive evidence cannot be read because persistence is unavailable or its read failed. When persistence is not configured, details.reason_code is drive_health_persistence_unavailable and details.retryable is true. Authentication and hosted organization scope are checked before this error. content: application/json: schema: $ref: '#/components/schemas/DriveHealthUnavailableError' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- OIDC/JWKS bearer token. Self-hosted defaults to Pocket ID; SaaS uses Auth0 through the edge. PocketBase JWT is legacy migration compatibility only. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.