Skip to main content
The Stack API lets you automate everything you can do in the dashboard — create stacks, manage nodes, trigger deployments, and monitor status.
Base URL: http://localhost:5260/api/v1 (self-hosted) or https://stack.kombify.io/api/v1 (managed)

​
Quick start

​
1. Get an authentication token

# Authenticate via Zitadel OIDC
# 1. Obtain a token from your Zitadel instance
TOKEN=$(curl -s -X POST https://auth.kombify.dev/oauth/v2/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=openid" | jq -r '.access_token')

# 2. Use the token in API requests
curl http://localhost:5260/api/v1/stacks \
  -H "Authorization: Bearer $TOKEN"
Response: 
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid"
}

​
2. Use the token in requests

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:5260/api/v1/stacks

​
API endpoints

Stacks

Create, list, update, and delete infrastructure stacks

Workers

Manage node agents and their status

Jobs

Track deployment jobs and their progress

Validation

Validate configurations and generate IaC

​
Endpoint reference

EndpointMethodDescription
/api/v1/healthGETHealth check and version info
/api/v1/stacksGETList all stacks
/api/v1/stacksPOSTCreate a new stack
/api/v1/stacks/{id}GETGet stack details
/api/v1/stacks/{id}PUTUpdate stack configuration
/api/v1/stacks/{id}DELETEDelete a stack
/api/v1/stacks/{id}/applyPOSTApply stack to infrastructure
/api/v1/stacks/{id}/planPOSTPreview changes without applying
/api/v1/workersGETList registered workers
/api/v1/workersPOSTRegister a new worker
/api/v1/workers/{id}GETGet worker status and details
/api/v1/workers/{id}DELETEUnregister a worker
/api/v1/jobsGETList all jobs
/api/v1/jobs/{id}GETGet job details and logs
/api/v1/unifier/validatePOSTValidate a kombination.yaml
/api/v1/unifier/generatePOSTGenerate IaC from configuration

​
Common patterns

# 1. Create the stack
STACK_ID=$(curl -s -X POST http://localhost:5260/api/v1/stacks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-homelab",
    "stackkit": "base-kit",
    "config": {
      "services": ["traefik", "immich", "homepage"]
    }
  }' | jq -r '.id')

# 2. Preview changes
curl -X POST "http://localhost:5260/api/v1/stacks/$STACK_ID/plan" \
  -H "Authorization: Bearer $TOKEN"

# 3. Apply to infrastructure
curl -X POST "http://localhost:5260/api/v1/stacks/$STACK_ID/apply" \
  -H "Authorization: Bearer $TOKEN"

# 4. Check job status
curl "http://localhost:5260/api/v1/jobs?stack_id=$STACK_ID" \
  -H "Authorization: Bearer $TOKEN"

# List all workers with status
curl http://localhost:5260/api/v1/workers \
  -H "Authorization: Bearer $TOKEN"
Response:
{
  "workers": [
    {
      "id": "worker_abc123",
      "name": "proxmox-01",
      "status": "online",
      "last_seen": "2026-01-26T10:30:00Z",
      "resources": {
        "cpu_cores": 8,
        "memory_gb": 32,
        "disk_gb": 500
      }
    }
  ]
}

# Validate a kombination.yaml
curl -X POST http://localhost:5260/api/v1/unifier/validate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/yaml" \
  --data-binary @kombination.yaml
Response (success):
{
  "valid": true,
  "warnings": [],
  "resolved": {
    "services": ["traefik", "immich", "homepage"],
    "dependencies": {
      "traefik": [],
      "immich": ["traefik"],
      "homepage": ["traefik"]
    }
  }
}
Response (error):
{
  "valid": false,
  "errors": [
    {
      "path": "services.immich.storage",
      "message": "storage path '/data/photos' does not exist on node 'proxmox-01'"
    }
  ]
}

​
Error handling

All errors follow a consistent format: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid configuration",
    "details": [
      {
        "field": "services",
        "message": "At least one service is required"
      }
    ]
  }
}
HTTP CodeMeaning
200Success
201Created
400Bad request — check your input
401Unauthorized — token missing or invalid
403Forbidden — insufficient permissions
404Not found
500Server error

​
Rate limits

PlanRequests/minuteRequests/hour
Self-hostedUnlimitedUnlimited
Cloud Free601,000
Cloud Pro30010,000
Cloud Team1,00050,000

​
Next steps

Stacks API

Full stacks endpoint documentation

Workers API

Worker management endpoints

Jobs API

Job tracking and logs

Validation API

Validation and generation