> ## 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. # Queue an owned node's typed Advanced or backup operation > Uses the same tenant- and owner-scoped dispatcher as the operator UI. The node executes through its authenticated channel, current release pin, native Advanced catalog and issued operation capability. Techstack never executes Terramate, apply, rollback, backup or restore itself. A mutation requires owner_approved; service locks and active server maintenance are checked before enqueue. Direct backup_run and backup_configure remain Basement-only; managed kits keep their schedule and sealed target-renewal authority. backup_configure derives the node's target and plan from existing custody and accepts no credential fields. advanced_change_set requires candidate_spec; rollback requires an exact rollback_target_ref; restore_drill may reuse a snapshot_anchor_id. ai_provider lets Private AI offer an external OpenAI-compatible provider: the kombify Wallet seals the item wallet_item_id (the provider's API key) to the node, which must be listed as a host target of that item, the node binds it to ai_provider_base_url, and a drift reconcile applies the setting. ai_provider_disable removes it. Restore activation requires exactly one Idempotency-Key header, while other operations have no replay guarantee. Acceptance is not execution success; read the returned job and its scoped result to observe effects. ## OpenAPI ````yaml /techstack/reference/api/openapi.yaml post /api/v1/stacks/{id}/stackkit/operations 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/stacks/{id}/stackkit/operations: post: tags: - Stacks - Jobs summary: Queue an owned node's typed Advanced or backup operation description: >- Uses the same tenant- and owner-scoped dispatcher as the operator UI. The node executes through its authenticated channel, current release pin, native Advanced catalog and issued operation capability. Techstack never executes Terramate, apply, rollback, backup or restore itself. A mutation requires owner_approved; service locks and active server maintenance are checked before enqueue. Direct backup_run and backup_configure remain Basement-only; managed kits keep their schedule and sealed target-renewal authority. backup_configure derives the node's target and plan from existing custody and accepts no credential fields. advanced_change_set requires candidate_spec; rollback requires an exact rollback_target_ref; restore_drill may reuse a snapshot_anchor_id. ai_provider lets Private AI offer an external OpenAI-compatible provider: the kombify Wallet seals the item wallet_item_id (the provider's API key) to the node, which must be listed as a host target of that item, the node binds it to ai_provider_base_url, and a drift reconcile applies the setting. ai_provider_disable removes it. Restore activation requires exactly one Idempotency-Key header, while other operations have no replay guarantee. Acceptance is not execution success; read the returned job and its scoped result to observe effects. operationId: runStackKitLifecycleOperation parameters: - $ref: '#/components/parameters/stackId' - name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 128 description: >- Required for backup_restore_activate; derived identity binds durable replay. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StackKitLifecycleRequest' responses: '202': description: Typed lifecycle job accepted; execution and evidence remain pending content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/StackKitLifecycleAccepted' meta: $ref: '#/components/schemas/ResponseMeta' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: stackId: name: id in: path required: true description: Stack ID schema: type: string schemas: StackKitLifecycleRequest: type: object additionalProperties: false required: - agent_id - operation properties: agent_id: type: string minLength: 1 operation: type: string enum: - plan - apply - verify - upgrade - drift_detect - drift_reconcile - advanced_change_set - rollback - restore_drill - backup_run - backup_configure - backup_status - backup_restore - backup_restore_activate - backup_restore_recover - ai_provider owner_approved: type: boolean target_release: type: string dry_run: type: boolean offline: type: boolean stackkit: type: string description: >- Optional execution binding; normally derived from the stack's managed rollout. candidate_spec: type: object additionalProperties: true description: >- Canonical candidate StackSpec validated by the pinned node executor; required for advanced_change_set. rollback_target_ref: type: string pattern: ^sha256:[a-f0-9]{64}$ description: Exact executor-state snapshot or change-set digest. snapshot_anchor_id: type: string pattern: ^sha256:[a-f0-9]{64}$ restore_result_id: type: string pattern: ^sha256:[a-f0-9]{64}$ activation_operation_id: type: string restore_plan_hash: type: string pattern: ^sha256:[a-f0-9]{64}$ ai_provider_base_url: type: string maxLength: 512 description: >- https base URL of the OpenAI-compatible provider API for ai_provider. wallet_item_id: type: string pattern: ^itm_[a-z2-7]{26}$ description: kombify Wallet item holding the provider's API key for ai_provider. wallet_item_rotate: type: boolean description: Deliver a rotated item that replaces the version the node holds. ai_provider_disable: type: boolean description: Remove the external provider instead of setting it. StackKitLifecycleAccepted: type: object required: - job_id - kit_deployment_id - agent_id - operation - status properties: job_id: type: string kit_deployment_id: type: string agent_id: type: string operation: type: string status: type: string 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. 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' Unauthorized: description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: Request conflicts with existing state 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.