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, automation, and MCP connections, use an API key in the Authorization header:

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

API keys support:

• Role scoping — keys operate with a specific role (admin, customer, viewer, etc.)
• Permission restrictions — deny specific permissions beyond the role
• Expiry — keys automatically rejected after expiry date
• Rate limiting — configurable requests per minute

Creating an API Key

Navigate to Settings > API Keys, or use the API:

curl -X POST https://panel.example.com/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-script", "role": "admin", "rateLimitRpm": 120}'

See Authentication for details on creating and managing API keys.

Swagger UI

Interactive API documentation is available at /api/docs on your panel instance. The Swagger UI lets you browse all 158 endpoints, view request/response schemas, and try API calls directly from the browser.

OpenAPI Spec

Download the full OpenAPI 3.1 specification at /api/openapi.yaml. Use this spec with code generators (openapi-generator, oapi-codegen) to create typed API clients in Go, Python, TypeScript, and other languages.

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

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:

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:

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