> ## 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. # Send kombify Guard host and container telemetry > Telemetry on the managed transport. A batch carries records of one source epoch with increasing sequence numbers: each record is one collection cycle of the data contract (host CPU, memory, swap, load, disk per mount, uptime and container resource usage; SERVER-CONNECTION-STANDARD section 9) or an explicit gap marker. The control plane repeats the contract filter, stamps tenant, worker and server from the authentication, stores the samples and acknowledges only what it stored (`acked_sequence`), so a Guard that lost an acknowledgement replays without duplicates and keeps everything else. Editions that store no telemetry answer `state: disabled` and the Guard stops collecting. ## OpenAPI ````yaml /techstack/reference/api/openapi.yaml post /api/v1/workers/{id}/telemetry 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/workers/{id}/telemetry: post: tags: - Workers summary: Send kombify Guard host and container telemetry description: >- Telemetry on the managed transport. A batch carries records of one source epoch with increasing sequence numbers: each record is one collection cycle of the data contract (host CPU, memory, swap, load, disk per mount, uptime and container resource usage; SERVER-CONNECTION-STANDARD section 9) or an explicit gap marker. The control plane repeats the contract filter, stamps tenant, worker and server from the authentication, stores the samples and acknowledges only what it stored (`acked_sequence`), so a Guard that lost an acknowledgement replays without duplicates and keeps everything else. Editions that store no telemetry answer `state: disabled` and the Guard stops collecting. operationId: ingestWorkerTelemetry parameters: - $ref: '#/components/parameters/resourceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GuardTelemetryBatch' responses: '200': description: The acknowledgement content: application/json: schema: type: object properties: data: type: object properties: telemetry: $ref: '#/components/schemas/GuardTelemetryAck' '400': $ref: '#/components/responses/BadRequest' '401': description: Access token or proof not accepted '413': description: The batch exceeds its bound '503': $ref: '#/components/responses/ServiceUnavailable' security: - runtimeAgentAuth: [] components: parameters: resourceId: name: id in: path required: true description: Resource ID schema: type: string schemas: GuardTelemetryBatch: type: object additionalProperties: false required: - schema_version - source_epoch - records properties: schema_version: type: string enum: - kombify.guard-telemetry/v1 source_epoch: type: string maxLength: 64 records: type: array minItems: 1 maxItems: 64 items: type: object additionalProperties: false required: - sequence - at properties: sequence: type: integer format: int64 minimum: 1 at: type: string format: date-time samples: type: array maxItems: 600 items: type: object additionalProperties: false required: - name - value properties: name: type: string description: >- A metric of the telemetry contract; anything else is dropped and counted. value: type: number labels: type: object additionalProperties: type: string maxLength: 128 description: >- Only core, mount, container_name and origin, each with a bounded value. gap: type: object additionalProperties: false required: - from - to - from_sequence - to_sequence - reason properties: from: type: string format: date-time to: type: string format: date-time from_sequence: type: integer format: int64 to_sequence: type: integer format: int64 reason: type: string enum: - spool_budget - rejected GuardTelemetryAck: type: object properties: state: type: string enum: - disabled acked_sequence: type: integer format: int64 description: Every record up to this sequence is stored. accepted: type: integer minimum: 0 dropped: type: integer minimum: 0 description: Samples outside the telemetry contract. 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.) responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServiceUnavailable: description: Required control-plane persistence or dependency is unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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. runtimeAgentAuth: type: http scheme: bearer bearerFormat: TechStack-Runtime-Agent description: >- Runtime-agent credential bound to the exact tenant, placement, server, and worker identity. Signed, opaque, and explicit legacy compatibility tokens are validated fail-closed by the worker runtime. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.