API reference

Everything in the console is available through a REST API with JSON requests and responses.

Base URL: https://api.hosting.kasadaai.com/v1

The full machine-readable spec is the OpenAPI 3.1 file at https://api.hosting.kasadaai.com/v1/openapi.yaml — import it into Postman, Insomnia or a code generator.

Authentication

Create a token in the console under Organization → API tokens. Tokens start with khst_ and are shown only once, so store them safely. Send it as a bearer token:

bash

export KHOST_TOKEN=khst_xxxxxxxxxxxxxxxxxxxxxxxx
curl https://api.hosting.kasadaai.com/v1/instances -H "Authorization: Bearer $KHOST_TOKEN"

Read-only tokens can call any GET endpoint but can't change anything — ideal for monitoring.
Tokens can expire after a set number of days. Delete a token to revoke it immediately.
A token acts for the organization it was created in.

Conventions

JSON field names are snake_case; times are RFC 3339 in UTC; IDs are UUIDs.
Money fields ending in _micros are micro-dollars: 19000000 = $19.00. Fields ending in _minor are cents: 2000 = $20.00.
Lists return {"data": [...], "total": n} and accept ?limit= and ?offset=.

Errors

Errors use standard HTTP status codes and always have this shape:

json

{
  "error": {
    "code": "validation_failed",
    "message": "Please fix the highlighted fields.",
    "fields": { "name": "Use letters, numbers and dashes only." }
  }
}

Status	Meaning
400 / 422	Invalid input — see `fields`
401	Missing or invalid token
402	Not enough wallet balance — top up
403	Not allowed (role, read-only token or account limit)
404	Not found
409	Conflict, e.g. `no_capacity` or the resource is busy
429	Rate limited — slow down and retry

Long-running actions

Creating, deleting, powering and resizing servers take a few seconds to a minute. These calls answer immediately with 202 Accepted and an operation. Poll it until status is succeeded, failed or rolled_back:

bash

curl https://api.hosting.kasadaai.com/v1/operations/OPERATION_ID -H "Authorization: Bearer $KHOST_TOKEN"

json

{
  "id": "8f0c…",
  "kind": "instance.create",
  "status": "running",
  "steps": [
    { "name": "reserve_capacity", "status": "done" },
    { "name": "assign_ips", "status": "done" },
    { "name": "install_image", "status": "running" },
    { "name": "start", "status": "pending" }
  ]
}

Examples

List servers

bash

curl "https://api.hosting.kasadaai.com/v1/instances?status=running" \
  -H "Authorization: Bearer $KHOST_TOKEN"

Create a server

bash

curl -X POST https://api.hosting.kasadaai.com/v1/instances \
  -H "Authorization: Bearer $KHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-1",
    "plan": "K2",
    "image": "ubuntu-24.04",
    "region": "us-east",
    "ssh_key_ids": ["SSH_KEY_ID"],
    "backups": true,
    "user_data": "#cloud-config\npackages: [nginx]"
  }'

region is optional and defaults to us-east. Regions: us-east (US East), eu-central (EU Central), us-west (US West) — see GET /catalog.

Response (202): {"instance": {...}, "operation": {...}}.

Power actions

bash

# action: start | stop | shutdown | reboot | reset
curl -X POST https://api.hosting.kasadaai.com/v1/instances/INSTANCE_ID/actions/reboot \
  -H "Authorization: Bearer $KHOST_TOKEN"

Delete a server

bash

curl -X DELETE https://api.hosting.kasadaai.com/v1/instances/INSTANCE_ID -H "Authorization: Bearer $KHOST_TOKEN"

Wallet balance and top-up status

bash

curl https://api.hosting.kasadaai.com/v1/wallet -H "Authorization: Bearer $KHOST_TOKEN"
curl https://api.hosting.kasadaai.com/v1/wallet/topups/PAYMENT_ID -H "Authorization: Bearer $KHOST_TOKEN"

json

{ "id": "…", "provider": "stripe", "method": "card", "status": "succeeded",
  "currency": "USD", "amount_minor": 2000, "usd_micros": 20000000, "receipt_no": "KH-2026-000123" }

Webhooks

Under Organization → Webhooks you can receive events such as instance.running, instance.failed, instance.deleted, snapshot.available, backup.completed, wallet.topup, wallet.low_balance, wallet.negative and billing.powered_off. Each request is signed with X-Kasada-Signature: sha256=<hmac> using your webhook secret.

Building something bigger? The khost CLI and the Terraform provider use this same API.

← Previous

Billing & wallet

CLI (khost)