HTTP API Reference

Use this page when integrating KalamDB over HTTP (outside SDK abstractions), building backend services, or debugging with curl/Postman.

• Base URL: http://<host>:8080
• API 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 and session

• 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 by endpoint

Bearer token required

Authorization: Bearer <JWT_TOKEN>

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

Cookie or bearer

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

Public (no auth)

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

WebSocket auth flow

GET /v1/ws upgrades unauthenticated, then authenticate in-band:

{"type":"authenticate","method":"jwt","token":"..."}

See WebSocket Protocol.

SQL API

POST /v1/api/sql

Execute SQL using JSON or multipart payload.

Headers

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

JSON request body

{
  "sql": "SELECT * FROM default.users WHERE id = $1",
  "params": [123],
  "namespace_id": "default"
}

Multipart request body (FILE columns)

Expected parts:

• sql (required)
• params (optional JSON array string)
• namespace_id (optional)
• file:<placeholder> file parts

SQL placeholder mapping:

• SQL uses FILE("name") or FILE('name')
• Multipart part name must be file:name

File download API

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

• Bearer token required
• Optional user_id query for user-table scopes
• 200 returns binary content, otherwise 400/403/404 based on validation/permission/not found

Topic HTTP API

For detailed consume/ack payload examples, see Topic Pub/Sub HTTP API.