Skip to main content
The Cloud API provides programmatic access to kombify’s managed SaaS platform. Use it to manage subscriptions, access tools, and integrate kombify into your workflows.

​
Base URLs

EnvironmentBase URL
Productionhttps://api.kombify.io/v1
Staginghttps://api.staging.kombify.io/v1

​
Authentication

Cloud supports two authentication methods: Obtain a token via OAuth 2.0 flow or the login endpoint: 
# Login to get token
curl -X POST https://api.kombify.io/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
Response: 
{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_at": "2026-01-27T10:00:00Z",
  "refresh_token": "refresh_abc123..."
}
Use the token in subsequent requests: 
curl -H "Authorization: Bearer $TOKEN" \
  https://api.kombify.io/v1/me

​
API key

For server-to-server integrations, use an API key: 
curl -H "X-API-Key: $API_KEY" \
  https://api.kombify.io/v1/tools
Generate API keys in your kombify dashboard. Keys inherit your account permissions.

​
Endpoint reference

MethodEndpointDescription
Authentication
POST/auth/loginLogin and get JWT
POST/auth/refreshRefresh JWT token
POST/auth/logoutInvalidate token
GET/meGet current user
Subscriptions
GET/subscriptionsList your subscriptions
GET/subscriptions/{id}Get subscription details
POST/subscriptions/{id}/upgradeUpgrade plan
POST/subscriptions/{id}/cancelCancel subscription
Tools
GET/toolsList available tools
GET/tools/{id}Get tool details
POST/tools/{id}/connectConnect tool to homelab
DELETE/tools/{id}/disconnectDisconnect tool
Deployments
GET/deploymentsList deployments
POST/deploymentsCreate deployment
GET/deployments/{id}Get deployment status
DELETE/deployments/{id}Delete deployment

​
Common patterns

# Get user info
curl -H "Authorization: Bearer $TOKEN" \
  https://api.kombify.io/v1/me
Response:
{
  "id": "usr_abc123",
  "email": "you@example.com",
  "name": "Max Mustermann",
  "plan": "hobby",
  "quota": {
    "stacks": {"used": 2, "limit": 5},
    "tools": {"used": 3, "limit": 10}
  }
}

# List available tools
curl -H "Authorization: Bearer $TOKEN" \
  https://api.kombify.io/v1/tools

# Connect Portainer
curl -X POST https://api.kombify.io/v1/tools/portainer/connect \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "homelab_url": "https://homelab.example.com",
    "tunnel_type": "cloudflare"
  }'
Response:
{
  "tool_id": "portainer",
  "status": "connecting",
  "connection": {
    "tunnel_id": "tun_xyz789",
    "dns_record": "portainer.homelab.example.com"
  }
}

curl -X POST https://api.kombify.io/v1/deployments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stackkit": "nextcloud",
    "target": "homelab",
    "config": {
      "domain": "cloud.example.com",
      "storage_size": "100Gi"
    }
  }'
Response:
{
  "id": "dep_abc123",
  "stackkit": "nextcloud",
  "status": "pending",
  "target": "homelab",
  "created_at": "2026-01-26T10:00:00Z"
}

​
Error handling

All errors follow a consistent format: 
{
  "error": {
    "code": "SUBSCRIPTION_LIMIT_EXCEEDED",
    "message": "You've reached your plan limit of 5 stacks",
    "details": {
      "current": 5,
      "limit": 5,
      "plan": "hobby"
    },
    "upgrade_url": "https://app.kombify.io/upgrade"
  }
}

​
Common error codes

CodeHTTP StatusMeaning
INVALID_TOKEN401JWT expired or invalid
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource doesn’t exist
SUBSCRIPTION_LIMIT_EXCEEDED402Upgrade required
RATE_LIMIT_EXCEEDED429Too many requests
HOMELAB_UNREACHABLE503Can’t reach your homelab

​
Webhooks

Cloud can send webhooks to your server when events occur: 
{
  "event": "deployment.completed",
  "timestamp": "2026-01-26T10:05:00Z",
  "data": {
    "deployment_id": "dep_abc123",
    "stackkit": "nextcloud",
    "status": "running"
  }
}
Configure webhooks in your dashboard settings.

​
Rate limits

PlanRequests/minBurst
Free3050
Hobby100200
Pro5001000
Team20005000

​
SDKs and libraries

TypeScript

npm i @kombify/sdk

Python

pip install kombify

Go

go get kombify.io/sdk

​
Next steps

Authentication

OAuth 2.0 and OIDC flows

Tools API

Manage connected tools

Subscriptions

Billing and plan management

Webhooks

Event notifications