API Overview

AI Admin Panel exposes a REST API for programmatic access to all panel functionality. The API is used by the frontend and is available for external integrations, automation, and custom tooling.

Base URL

https://panel.example.com/api

All API endpoints are prefixed with /api. The API is served by the same process as the frontend — no separate API server.

Authentication

The API supports two authentication methods:

1. OIDC Session Cookie (Browser)

When logged in through the browser via Keycloak OIDC, the session cookie authenticates API requests automatically. This is how the frontend communicates with the API.

2. API Key (Programmatic)

For scripts, CI/CD, and integrations, use an API key in the Authorization header:

curl -H "Authorization: Bearer your-api-key" \
  https://panel.example.com/api/services

See Authentication for details on creating and managing API keys.

Response Format

All responses are JSON. Successful responses return the requested data directly:

{
  "id": "svc_abc123",
  "name": "my-app",
  "status": "running",
  "url": "https://my-app.panel.example.com",
  "created_at": "2026-03-29T10:00:00Z"
}

List endpoints return an array with pagination metadata:

{
  "data": [
    { "id": "svc_abc123", "name": "my-app" },
    { "id": "svc_def456", "name": "my-db" }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}

Error Handling

Errors return an appropriate HTTP status code and a JSON error body:

{
  "error": {
    "code": "not_found",
    "message": "Service not found",
    "details": "No service with ID svc_xyz789 exists"
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created (new resource)
204	No Content (successful delete)
400	Bad Request — invalid input or parameters
401	Unauthorized — missing or invalid authentication
403	Forbidden — authenticated but insufficient permissions
404	Not Found — resource does not exist
409	Conflict — resource already exists or state conflict
422	Unprocessable Entity — validation errors
429	Too Many Requests — rate limit exceeded
500	Internal Server Error

Validation Errors

422 responses include field-level details:

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "fields": {
      "name": "Service name is required",
      "plan_id": "Invalid plan ID"
    }
  }
}

Pagination

List endpoints support pagination via query parameters:

Parameter	Default	Description
page	1	Page number (1-indexed)
per_page	20	Items per page (max 100)
sort	varies	Sort field (e.g., name, created_at)
order	asc	Sort order: asc or desc

Example:

curl "https://panel.example.com/api/services?page=2&per_page=10&sort=created_at&order=desc"

Filtering

List endpoints support filtering via query parameters specific to each resource:

# Filter services by status
curl "https://panel.example.com/api/services?status=running"

# Filter services by customer
curl "https://panel.example.com/api/services?customer_id=cust_abc123"

# Filter templates by category
curl "https://panel.example.com/api/templates?category=ai"

Rate Limiting

The API enforces rate limits per API key or session:

Tier	Limit
Default	60 requests/minute
Authenticated	120 requests/minute
Deploy operations	10 requests/minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1711720800

WebSocket

Real-time updates are available via WebSocket at:

wss://panel.example.com/api/ws

The WebSocket connection requires authentication (session cookie or API key as a query parameter). Events include:

• deploy.progress — deployment step updates
• service.status — service status changes
• service.logs — real-time log streaming
• backup.progress — backup job progress

API Endpoints

Section	Endpoints
Authentication	Login flow, API keys, sessions
Services	CRUD, deploy, lifecycle, logs
Templates	List, detail, deploy from template