API Overview

AI Admin Panel's REST API supports panel administration and automation. This guide describes the v2.12.8 interface. The Partner API is a separate service for commercial licensing and uses different tokens, routes, and schemas.

Base URL

https://panel.example.com/api/v1

Resource routes such as /services, /templates, and /api-keys use this base. The panel serves the frontend and API from the same process. Documentation routes and the WebSocket and MCP transports have their own paths below.

Authentication

Browser requests use the oidc_session cookie after Keycloak sign-in. Automation uses a panel API key in the Authorization header:

curl 'https://panel.example.com/api/v1/services?page=1&pageSize=20' \
  -H "Authorization: Bearer ${PANEL_API_KEY}"

PANEL_API_KEY is a placeholder environment variable for your securely supplied key; never put a real key in documentation or source control. This services route requires the admin role. Customer portal routes use a separate /api/v1/portal surface; an admin resource URL is not a customer-scoped integration endpoint. See Authentication for key creation and the known OIDC token-storage limitation.

Swagger UI

Open /api/docs on your panel to browse the bundled API description. Interactive requests can change real resources; use a test instance when trying mutations.

API specification

curl -O https://panel.example.com/api/openapi.yaml

These are bundled build artifacts generated from handler annotations. They are useful for client generation, but annotations can differ from registered routes or response serializers. In particular, v2.12.8 contains both resource-relative paths and already-prefixed auth paths: check the final URL before sending a generated request. The routes and examples on these pages have been reconciled against the v2.12.8 router and handlers. No fixed path count is a coverage promise.

Response Format

Follow each endpoint's schema. Services return camelCase fields such as deploymentType and createdAt; Git creation and AI analysis also use some snake_case request fields. There is no global field-name conversion.

Pagination

Do not assume a list accepts sort, order, or a customer filter. Use only the parameters documented for that endpoint.

Error Handling

Many panel handlers use this error envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "composeYaml is required"
  }
}

Here validation_failed maps to 400 Bad Request. Authentication/authorization failures commonly use 401/403, missing resources 404, conflicts 409, and rate limiting 429. Some middleware and analysis/deployment errors return a string error and additional fields instead; do not assume every failure has nested field-level validation details.

Rate Limiting

Panel keys have a rateLimitRpm setting (creation defaults to 60). When the per-key limiter is wired, key-authenticated requests include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. These are not a universal set of session or deployment tiers, and the headers are not present on every response. Back off on 429 and honor Retry-After when supplied.

WebSocket

The real-time transport is wss://panel.example.com/ws. The hub accepts an OIDC session cookie or a JWT through its token query parameter; this is not a panel API-key query parameter. Prefer the browser's existing session. Avoid recording URLs containing authentication material. MCP uses the separate routes described in MCP Server.

API Endpoints