API Reference

The KairOS Red Network v10 REST API allows programmatic management of devices, VNIs, policies, and users. All API endpoints are available at https://api.kairosnetwork.red/v1.

Authentication

All API requests require authentication via Bearer token:

Authorization: Bearer <your-api-token>

Getting an API Token

1. Log in to the KairOS Red Console
2. Navigate to Settings → API Tokens
3. Click Generate New Token
4. Select the appropriate permissions for your use case
5. Copy the token and store it securely

Token Scopes

Rate Limiting

API requests are rate-limited per token. Limits vary by plan:

Rate limit headers are returned with every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1623456789

Endpoints

Devices

List Devices

GET /v1/devices

Query Parameters:
  page     int     Page number (default: 1)
  per_page int     Items per page (default: 20, max: 100)
  status   string  Filter by status: online, offline, enrolled
  vni_id   string  Filter by VNI ID

Response:
{
  "data": [
    {
      "id": "dev_abc123",
      "name": "prod-server-01",
      "status": "online",
      "vni_ids": ["vni_xyz789"],
      "tags": ["production", "us-east-1"],
      "created_at": "2026-05-15T10:30:00Z",
      "last_seen": "2026-05-28T15:45:00Z",
      "public_key": "0x..."
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 42
  }
}

Get Device

GET /v1/devices/:id

Response:
{
  "id": "dev_abc123",
  "name": "prod-server-01",
  "status": "online",
  "vni_ids": ["vni_xyz789"],
  "tags": ["production", "us-east-1"],
  "created_at": "2026-05-15T10:30:00Z",
  "last_seen": "2026-05-28T15:45:00Z",
  "public_key": "0x...",
  "metadata": {
    "os": "linux",
    "arch": "x86_64",
    "version": "10.1.0"
  }
}

Enroll Device

POST /v1/devices/enroll

Request:
{
  "name": "prod-server-01",
  "public_key": "0x...",
  "tags": ["production", "us-east-1"],
  "metadata": {
    "os": "linux",
    "arch": "x86_64"
  }
}

Response (201):
{
  "id": "dev_abc123",
  "enrollment_token": "tok_xyz789",
  "certificate": "-----BEGIN CERTIFICATE-----\n..."
}

Delete Device

DELETE /v1/devices/:id

Response (204): No Content

Virtual Network Interfaces (VNIs)

List VNIs

GET /v1/vnis

Response:
{
  "data": [
    {
      "id": "vni_xyz789",
      "name": "corporate",
      "cidr": "10.0.0.0/16",
      "device_count": 12,
      "status": "active",
      "created_at": "2026-05-10T08:00:00Z"
    }
  ]
}

Create VNI

POST /v1/vnis

Request:
{
  "name": "corporate",
  "cidr": "10.0.0.0/16",
  "description": "Corporate network segment"
}

Response (201):
{
  "id": "vni_xyz789",
  "name": "corporate",
  "cidr": "10.0.0.0/16",
  "status": "active",
  "created_at": "2026-05-28T16:00:00Z"
}

Get VNI

GET /v1/vnis/:id

Delete VNI

DELETE /v1/vnis/:id

Response (204): No Content

Policies

List Policies

GET /v1/policies

Create Policy

POST /v1/policies

Request:
{
  "name": "allow-corporate-access",
  "description": "Allow devices in corporate VNI to access internal services",
  "rego": "package kairos\n\ndefault allow = false\n\nallow {\n    input.vni == \"corporate\"\n    input.action == \"connect\"\n}\n",
  "enabled": true,
  "vni_ids": ["vni_xyz789"]
}

Evaluate Policy

POST /v1/policies/evaluate

Request:
{
  "policy_id": "pol_def456",
  "input": {
    "vni": "corporate",
    "action": "connect",
    "device_id": "dev_abc123",
    "source_ip": "10.0.0.15"
  }
}

Response:
{
  "result": true,
  "decisions": [
    {
      "policy_name": "allow-corporate-access",
      "rule": "allow",
      "decision": true
    }
  ]
}

Health

GET /v1/health

Response:
{
  "status": "healthy",
  "version": "10.1.0",
  "uptime": "72h15m30s",
  "services": {
    "database": "connected",
    "kv_store": "connected",
    "queue": "connected"
  }
}

Error Responses

The API uses standard HTTP status codes:

Error bodies follow this format:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "API rate limit exceeded. Retry after 30 seconds.",
    "details": {
      "retry_after": 30
    }
  }
}