The REST API is served on port 8080 by default and described by an OpenAPI document. Send Authorization: Bearer <api-key> (or X-Api-Key) on every /api/* call except first-time setup. The tables below list the main routes; use the OpenAPI document for request and response schemas.
Authentication and users#
| Method and path |
Purpose |
GET /api/auth/setup-status |
Whether first-time setup is still needed |
POST /api/auth/setup |
Create the first user and API key. Returns 409 if any user exists |
POST /api/auth/login, POST /api/auth/login/kerberos |
Sign in |
POST /api/auth/me/password |
Change your own password |
GET, POST /api/auth/users |
List and create users |
DELETE /api/auth/users/{userId} |
Remove a user |
POST /api/auth/users/{userId}/activate, /grant-superadmin, /password |
Account administration |
GET, POST /api/auth/users/{userId}/keys, DELETE /api/auth/keys/{keyId} |
List, create and revoke API keys |
Queries#
| Method and path |
Purpose |
POST /api/query |
Run a federated SQL statement with named parameters |
GET, POST /api/virtual-tables, GET, PUT, DELETE /api/virtual-tables/{name} |
Manage virtual tables |
Sagas#
| Method and path |
Purpose |
POST /api/saga |
Execute a saga and return one JSON result |
POST /api/saga/stream |
Execute a saga and stream progress as Server-Sent Events |
GET /api/saga, GET /api/saga/{sagaId} |
List sagas and fetch one |
GET /api/saga/{sagaId}/gaps |
The compensation gap report |
GET /api/saga/state-summary |
Counts by saga state |
GET, POST /api/saved-sagas, GET, PUT, DELETE /api/saved-sagas/{name} |
Manage saga templates |
POST /api/saved-sagas/{name}/execute |
Run a template with parameter values |
Authorisation#
| Method and path |
Purpose |
GET, POST /api/authz/roles, DELETE /api/authz/roles/{roleId} |
Roles |
GET, POST /api/authz/roles/{roleId}/permissions |
Role permissions |
GET, POST /api/authz/roles/{roleId}/row-filters, PUT, DELETE .../{filterId} |
Row filters |
GET, POST /api/authz/roles/{roleId}/column-masks, PUT, DELETE .../{maskId} |
Column masks |
GET, POST /api/authz/groups, .../members, .../roles |
Groups, membership and role assignment |
GET /api/authz/users/{userId}/groups, .../roles |
A user's effective grants |
| Method and path |
Purpose |
GET /api/ai/configs, PUT, DELETE /api/ai/configs/{name} |
AI configurations |
POST /api/ai/configs/{name}/test, /enable, /disable, /set-default |
Test and manage a configuration |
POST /api/ai/sql |
Natural language to SQL |
POST /api/ai/saga |
Natural language to saga JSON |
Administration and telemetry#
| Method and path |
Purpose |
GET, PUT /api/admin/resource-guards-config |
Resource guards |
GET /api/admin/semijoin-config, PUT, DELETE .../{providerKey} |
Per-provider semi-join settings |
GET /api/telemetry/summary, /latency, /requests, /requests/{id}, /users, /table-usage, /compensation-summary |
Telemetry |
POST /export, POST /import |
Encrypted configuration export and import (superadmin) |
Data sources and capabilities are managed under /api/datasources and /api/capabilities.
