HTTP API Reference

Base URL: http://<host>:2900
Version prefix: /v1

Route Map

Health and status

• GET /health (localhost-only)
• GET /v1/api/healthcheck (localhost-only)
• GET /v1/api/cluster/health (localhost-only)

SQL and files

• POST /v1/api/sql
• GET /v1/files/{namespace}/{table_name}/{subfolder}/{file_id}

WebSocket

• GET /v1/ws

Auth

• POST /v1/api/auth/login
• POST /v1/api/auth/refresh
• POST /v1/api/auth/logout
• GET /v1/api/auth/me
• POST /v1/api/auth/setup
• GET /v1/api/auth/status

Topic HTTP API

• POST /v1/api/topics/consume
• POST /v1/api/topics/ack

Authentication Rules

Bearer token required

1Authorization: Bearer <JWT_TOKEN>

• POST /v1/api/sql
• GET /v1/files/...
• POST /v1/api/topics/consume
• POST /v1/api/topics/ack

Basic auth is rejected on these endpoints.

Cookie or bearer accepted

• POST /v1/api/auth/refresh
• GET /v1/api/auth/me

Public endpoints

• POST /v1/api/auth/login
• POST /v1/api/auth/logout
• POST /v1/api/auth/setup (localhost-only unless auth.allow_remote_setup = true)
• GET /v1/api/auth/status (localhost-only unless remote setup enabled)
• GET /health and GET /v1/api/healthcheck (localhost-only)
• GET /v1/api/cluster/health (localhost-only)

SQL Endpoint

POST /v1/api/sql

Headers:

• Authorization: Bearer <JWT_TOKEN>
• Content-Type: application/json or multipart/form-data

JSON body

1{2  "sql": "SELECT * FROM app.messages WHERE id = $1",3  "params": [123],4  "namespace_id": "app"5}

namespace_id applies only to that request. Interactive clients such as the CLI can store the namespace locally after a successful USE namespace and send it again on later requests.

Multipart body for FILE(...)

Parts:

• sql
• params (optional JSON array string)
• namespace_id (optional request-scoped default namespace)
• file parts named file:<placeholder>

SQL:

1INSERT INTO app.docs (id, attachment) VALUES ('d1', FILE("contract"));

Multipart file key must be file:contract.

Success shape

1{2  "status": "success",3  "results": [4    {5      "schema": [{"name":"id","data_type":"BigInt","index":0}],6      "rows": [[1]],7      "row_count": 1,8      "as_user": "alice"9    }10  ],11  "took": 12.312}

Error shape

1{2  "status": "error",3  "results": [],4  "took": 1.2,5  "error": {6    "code": "INVALID_SQL",7    "message": "...",8    "details": null9  }10}

Common SQL error codes

• INVALID_SQL
• PERMISSION_DENIED
• TABLE_NOT_FOUND
• RATE_LIMIT_EXCEEDED
• NOT_LEADER
• CLUSTER_UNAVAILABLE
• FILE_TOO_LARGE
• TOO_MANY_FILES
• INVALID_MIME_TYPE

File Download

GET /v1/files/{namespace}/{table_name}/{subfolder}/{file_id}

• bearer token required
• optional user_id query parameter for user-table scope resolution
• SYSTEM and STREAM tables are rejected for file paths

Response:

• 200 with binary content
• 400/403/404 for validation, permission, or not-found failures

Auth Endpoints

POST /v1/api/auth/login

1{2  "user": "alice",3  "password": "Secret123!"4}

Returns user profile + access/refresh tokens and sets auth cookie.

POST /v1/api/auth/refresh

Accepts bearer token or cookie. Returns rotated token pair.

POST /v1/api/auth/logout

Clears auth cookie.

GET /v1/api/auth/me

Returns current authenticated user info.

POST /v1/api/auth/setup

Initial bootstrap only, when root has no password yet.

1{2  "user": "admin",3  "password": "AdminPass123!",4  "root_password": "RootPass123!",5  "email": "admin@example.com"6}

Sets root password and creates the DBA user. Does not auto-login.

GET /v1/api/auth/status

Returns setup status:

1{2  "needs_setup": true,3  "message": "Server requires initial setup..."4}

Topic Endpoints

Both require bearer auth and role in {service, dba, system}.

POST /v1/api/topics/consume

1{2  "topic_id": "orders_topic",3  "group_id": "worker_group",4  "start": "Latest",5  "limit": 100,6  "partition_id": 0,7  "timeout_seconds": 108}

Accepted start formats:

• "Latest"
• "Earliest"
• { "Offset": 123 }

POST /v1/api/topics/ack

1{2  "topic_id": "orders_topic",3  "group_id": "worker_group",4  "partition_id": 0,5  "upto_offset": 106}

Health Endpoints

GET /health and GET /v1/api/healthcheck return the same payload and are localhost-only:

1{2  "status": "healthy",3  "version": "...",4  "api_version": "v1",5  "build_date": "..."6}

For live protocol details, continue to WebSocket Protocol.