API Reference
CH-UI REST API reference
Base URL (default local):
| Method | Path | Purpose |
|---|
GET | /health | Health status |
POST | /connect | WebSocket tunnel upgrade (agent) |
GET | /api/license | License info |
POST | /api/auth/login | Session login |
POST | /api/auth/logout | Session logout |
GET | /api/auth/session | Session details |
GET | /api/auth/connections | Login-time connection list |
POST | /api/auth/switch-connection | Switch active connection |
All below require chui_session cookie.
| Method | Path | Purpose |
|---|
POST | /api/query/run | Execute SQL query |
POST | /api/query/stream | Stream query results via NDJSON/SSE |
POST | /api/query/format | Format/beautify SQL |
POST | /api/query/explain | EXPLAIN output |
POST | /api/query/plan | Parsed query plan tree |
POST | /api/query/profile | Query log metrics for exact SQL |
POST | /api/query/sample | Sample rows (per-shard or global) |
GET | /api/query/databases | List databases |
GET | /api/query/tables | List tables (?database=) |
GET | /api/query/columns | List columns (?database=&table=) |
GET | /api/query/data-types | List ClickHouse data types |
GET | /api/query/clusters | List clusters |
POST | /api/query/schema/database | Create database |
POST | /api/query/schema/database/drop | Drop database |
POST | /api/query/schema/table | Create table |
POST | /api/query/schema/table/drop | Drop table |
POST | /api/query/upload/discover | Detect schema from uploaded file |
POST | /api/query/upload/ingest | Insert uploaded data into table |
| Method | Path | Purpose |
|---|
GET | /api/connections | List connections |
POST | /api/connections | Create connection |
GET | /api/connections/{id} | Get connection |
DELETE | /api/connections/{id} | Delete connection |
POST | /api/connections/{id}/test | Test connection |
GET | /api/connections/{id}/token | Get tunnel token |
POST | /api/connections/{id}/regenerate-token | Regenerate tunnel token |
| Method | Path | Purpose |
|---|
GET | /api/saved-queries | List saved queries |
POST | /api/saved-queries | Create saved query |
GET | /api/saved-queries/{id} | Get saved query |
PUT | /api/saved-queries/{id} | Update saved query |
DELETE | /api/saved-queries/{id} | Delete saved query |
POST | /api/saved-queries/{id}/duplicate | Duplicate saved query |
| Method | Path | Purpose |
|---|
GET | /api/dashboards | List dashboards |
POST | /api/dashboards | Create dashboard |
GET | /api/dashboards/{id} | Get dashboard + panels |
PUT | /api/dashboards/{id} | Update dashboard |
DELETE | /api/dashboards/{id} | Delete dashboard + panels |
POST | /api/dashboards/{id}/panels | Create panel |
PUT | /api/dashboards/{id}/panels/{panelId} | Update panel |
DELETE | /api/dashboards/{id}/panels/{panelId} | Delete panel |
POST | /api/dashboards/query | Execute panel query with time-range interpolation |
| Method | Path | Purpose |
|---|
GET | /api/brain/models | List active models |
GET | /api/brain/chats | List user's chats (?includeArchived=) |
POST | /api/brain/chats | Create chat |
GET | /api/brain/chats/{chatID} | Get chat |
PUT | /api/brain/chats/{chatID} | Update chat (title, model, archive, context) |
DELETE | /api/brain/chats/{chatID} | Archive/delete chat |
GET | /api/brain/chats/{chatID}/messages | Get chat messages |
POST | /api/brain/chats/{chatID}/messages/stream | Stream LLM response (SSE) |
GET | /api/brain/chats/{chatID}/artifacts | List artifacts |
POST | /api/brain/chats/{chatID}/artifacts/query | Execute & persist SQL artifact |
GET | /api/brain/skills | Get active skill |
POST | /api/brain/chat | Legacy streaming endpoint (deprecated) |
| Method | Path | Purpose |
|---|
GET | /api/models | List models |
POST | /api/models | Create model |
GET | /api/models/{id} | Get model |
PUT | /api/models/{id} | Update model |
DELETE | /api/models/{id} | Delete model |
GET | /api/models/validate | Validate all models (refs, cycles) |
POST | /api/models/run | Execute all models |
POST | /api/models/{id}/run | Execute single model + upstream deps |
GET | /api/models/dag | Get DAG for visualization |
GET | /api/models/runs | List runs (?limit=&offset=) |
GET | /api/models/runs/{runId} | Get run + per-model results |
GET | /api/models/pipelines | List pipelines (connected components) |
POST | /api/models/pipelines/{anchorId}/run | Execute pipeline |
GET | /api/models/schedules | List model schedules |
GET | /api/models/schedule/{anchorId} | Get pipeline schedule |
PUT | /api/models/schedule/{anchorId} | Create/update pipeline schedule |
DELETE | /api/models/schedule/{anchorId} | Delete pipeline schedule |
| Method | Path | Purpose |
|---|
GET | /api/pipelines | List pipelines |
POST | /api/pipelines | Create pipeline |
GET | /api/pipelines/{id} | Get pipeline |
PUT | /api/pipelines/{id} | Update pipeline |
DELETE | /api/pipelines/{id} | Delete pipeline |
POST | /api/pipelines/{id}/start | Start pipeline |
POST | /api/pipelines/{id}/stop | Stop pipeline |
GET | /api/pipelines/{id}/status | Get pipeline status + metrics |
GET | /api/pipelines/{id}/logs | Get pipeline logs |
POST | /api/pipelines/webhook/{id} | Webhook source endpoint |
GET | /api/pipelines/connectors | List available connectors |
POST | /api/pipelines/validate | Validate pipeline config |
| Method | Path | Purpose |
|---|
GET | /api/admin/stats | System statistics (users, connections, queries) |
GET | /api/admin/users | List users with login history |
GET | /api/admin/user-roles | Get role overrides |
PUT | /api/admin/user-roles/{username} | Set role override |
DELETE | /api/admin/user-roles/{username} | Remove role override |
GET | /api/admin/connections | List connections with tunnel status |
GET | /api/admin/clickhouse-users | Query system.users from ClickHouse |
POST | /api/admin/clickhouse-users | Create ClickHouse user |
PUT | /api/admin/clickhouse-users/{username}/password | Change password |
DELETE | /api/admin/clickhouse-users/{username} | Drop ClickHouse user |
GET | /api/admin/brain/providers | List brain providers |
POST | /api/admin/brain/providers | Create brain provider |
PUT | /api/admin/brain/providers/{id} | Update brain provider |
DELETE | /api/admin/brain/providers/{id} | Delete brain provider |
POST | /api/admin/brain/providers/{id}/sync-models | Sync models from provider |
GET | /api/admin/brain/models | List all models (all states) |
PUT | /api/admin/brain/models/{id} | Update model flags |
POST | /api/admin/brain/models/bulk | Bulk model action |
GET | /api/admin/brain/skills | List skills |
POST | /api/admin/brain/skills | Create skill |
PUT | /api/admin/brain/skills/{id} | Update skill |
GET | /api/admin/langfuse | Get Langfuse config |
PUT | /api/admin/langfuse | Save Langfuse config |
DELETE | /api/admin/langfuse | Remove Langfuse config |
POST | /api/admin/langfuse/test | Test Langfuse credentials |
Pro endpoints require a valid license.
| Method | Path | Purpose |
|---|
GET | /api/schedules | List schedules |
GET | /api/schedules/{id} | Get schedule |
POST | /api/schedules | Create schedule |
PUT | /api/schedules/{id} | Update schedule |
DELETE | /api/schedules/{id} | Delete schedule |
POST | /api/schedules/{id}/run | Manual execution |
GET | /api/schedules/{id}/runs | Run history |
| Method | Path | Purpose |
|---|
GET | /api/governance/overview | Summary stats |
POST | /api/governance/sync | Trigger full sync |
POST | /api/governance/sync/{type} | Trigger single sync (metadata/query_log/access) |
GET | /api/governance/sync/status | Sync state for all workers |
GET | /api/governance/databases | List databases |
GET | /api/governance/tables | List tables (?database=) |
GET | /api/governance/tables/{db}/{table} | Table detail + columns + tags + lineage |
GET | /api/governance/tables/{db}/{table}/notes | Table notes |
GET | /api/governance/tables/{db}/{table}/columns/{col}/notes | Column notes |
POST | /api/governance/tables/{db}/{table}/notes | Create table note |
POST | /api/governance/tables/{db}/{table}/columns/{col}/notes | Create column note |
DELETE | /api/governance/notes/{id} | Delete note |
PUT | /api/governance/tables/{db}/{table}/comment | Update table comment |
PUT | /api/governance/tables/{db}/{table}/columns/{col}/comment | Update column comment |
GET | /api/governance/schema-changes | List schema changes |
GET | /api/governance/query-log | Ingested query log |
GET | /api/governance/query-log/top | Top queries by frequency |
GET | /api/governance/clickhouse-query-log | Live system.query_log |
GET | /api/governance/lineage | Lineage for table |
GET | /api/governance/lineage/graph | Full lineage graph |
GET | /api/governance/tags | List tags |
POST | /api/governance/tags | Create tag |
DELETE | /api/governance/tags/{id} | Delete tag |
GET | /api/governance/access/users | List ClickHouse users |
POST | /api/governance/access/users | Create ClickHouse user |
DELETE | /api/governance/access/users/{name} | Drop ClickHouse user |
GET | /api/governance/access/roles | List roles |
GET | /api/governance/access/matrix | Access matrix (?user=) |
GET | /api/governance/access/over-permissions | Unused privileges (?days=) |
GET | /api/governance/policies | List policies |
POST | /api/governance/policies | Create policy |
GET | /api/governance/policies/{id} | Get policy |
PUT | /api/governance/policies/{id} | Update policy |
DELETE | /api/governance/policies/{id} | Delete policy |
GET | /api/governance/violations | List violations |
POST | /api/governance/violations/{id}/incident | Create incident from violation |
GET | /api/governance/incidents | List incidents |
GET | /api/governance/incidents/{id} | Get incident |
POST | /api/governance/incidents | Create manual incident |
PUT | /api/governance/incidents/{id} | Update incident |
GET | /api/governance/incidents/{id}/comments | List incident comments |
POST | /api/governance/incidents/{id}/comments | Add incident comment |
GET | /api/governance/audit-logs | Query audit log |
| Method | Path | Purpose |
|---|
GET | /api/governance/alerts/channels | List alert channels |
POST | /api/governance/alerts/channels | Create channel |
PUT | /api/governance/alerts/channels/{id} | Update channel |
DELETE | /api/governance/alerts/channels/{id} | Delete channel |
POST | /api/governance/alerts/channels/{id}/test | Test channel delivery |
GET | /api/governance/alerts/rules | List rules (with routes) |
POST | /api/governance/alerts/rules | Create rule |
PUT | /api/governance/alerts/rules/{id} | Update rule |
DELETE | /api/governance/alerts/rules/{id} | Delete rule |
GET | /api/governance/alerts/events | List alert events |
# 1) Login
curl -i -X POST http://localhost:3488/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"username":"default",
"password":"secret",
"connectionId":"<connection-id>"
}'
# 2) Reuse set-cookie value as chui_session
curl -X POST http://localhost:3488/api/query/run \
-H "Content-Type: application/json" \
-H "Cookie: chui_session=<session-token>" \
-d '{"query":"SELECT version()"}'
