HTTP API Reference

KalamDB’s HTTP API covers SQL, authentication, files, topics, and procedure calls. GET /v1/api/openapi.json serves an OpenAPI 3.1 document generated from the live routine catalog.

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
• POST /v1/functions/{namespace}/{procedure}
• GET /v1/api/openapi.json
• 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
• POST /v1/api/auth/oidc/exchange-token
• POST /v1/api/auth/oidc/exchange-code
• 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
• POST /v1/functions/{namespace}/{procedure}
• GET /v1/api/openapi.json
• 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/oidc/exchange-token
• POST /v1/api/auth/oidc/exchange-code
• 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

SELECT statements and INSERT ... ON CONFLICT ... DO UPDATE ... RETURNING statements return query rows in results[]:

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}

Plain INSERT, UPDATE, and DELETE statements without RETURNING return an affected-row count instead of data rows. Upsert without RETURNING follows the insert result shape.

Example upsert that returns rows:

1INSERT INTO app.items (id, name)2VALUES (1, 'beta')3ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name4RETURNING id, name;

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

Functions endpoint

POST /v1/functions/{namespace}/{procedure}

Invokes a function or procedure as an HTTP-origin root. The SQL return value is the HTTP body (no {status, result} wrapper). ctx.http is present on this path only.

1POST /v1/functions/app/echo2Authorization: Bearer <JWT_TOKEN>3Content-Type: application/json4 5{ "msg": "hello" }

Success for RETURNS TEXT is the scalar:

1"hello"

Success for a structured RETURNS type is that object. Failures use a typed error envelope (code, message) mapped to HTTP status.

The same procedure can also be invoked with SQL CALL on POST /v1/api/sql or PGWire; that origin sets ctx.http to null. Topic triggers use CREATE TRIGGER ... ON TOPIC ... EXECUTE PROCEDURE and do not go through this route. See Server Functions.

OpenAPI specification

GET /v1/api/openapi.json

Returns an OpenAPI 3.1.0 document for the current routine catalog. The server builds it on each request. It describes POST /v1/functions/{namespace}/{procedure} only. SQL, auth, files, topics, and this endpoint itself are not in the document.

1GET /v1/api/openapi.json2Authorization: Bearer <JWT_TOKEN>

A bearer token is required. Basic auth is rejected. Any authenticated caller receives every catalogued routine. EXECUTE grants do not filter the document, so topic-trigger procedures and routines normally invoked with CALL appear as HTTP operations too.

X-Kalam-Epoch is optional. Omit it to accept the server epoch. When the header is present it must equal the current domain epoch (1). Any other value returns 409:

1{2  "status": "error",3  "code": "EPOCH_MISMATCH",4  "message": "unsupported protocol epoch '0'; current server epoch is 1"5}

Authentication failures use the same bearer-token error envelope as the other authorized routes.

Document shape

1{2  "openapi": "3.1.0",3  "info": {4    "title": "KalamDB Routine & Contract API",5    "version": "epoch-1"6  },7  "paths": {8    "/v1/functions/app/echo": {9      "post": {10        "operationId": "app.echo",11        "summary": "Echo a message",12        "security": [{ "bearerAuth": [] }],13        "requestBody": {14          "required": true,15          "content": {16            "application/json": {17              "schema": {18                "type": "object",19                "properties": {20                  "msg": { "type": "string", "nullable": false }21                },22                "required": ["msg"]23              }24            },25            "application/x-kalam-domain": {26              "schema": { "type": "string", "format": "binary" }27            }28          }29        },30        "responses": {31          "200": { "description": "Validated routine result" }32        }33      }34    }35  },36  "components": {37    "securitySchemes": {38      "bearerAuth": {39        "type": "http",40        "scheme": "bearer",41        "bearerFormat": "JWT"42      }43    }44  }45}

info.version is epoch- plus the server domain epoch. There is no servers array. Paths are rooted at the host, so /v1/functions/app/echo is the invoke URL on the same origin that served the document.

Each catalogued routine is one post operation:

• operationId is the schema-qualified routine id, such as app.echo.
• summary is the routine comment. When the routine has no comment, the summary is the routine id.
• security requires the bearerAuth JWT scheme.
• The JSON body is an object of input parameters (IN, INOUT, and VARIADIC). OUT parameters are omitted.
• A parameter is required when it is NOT NULL and has no default expression. requestBody.required is true only when that list is non-empty.
• application/x-kalam-domain is declared as binary and is not expanded into fields.
• 200 is described as “Validated routine result” and has no response schema. Read the function’s RETURNS clause or procedure’s output parameters for the success body.
• 400, 401, 403, 404, 409, 429, 500, and 504 reference #/components/responses/StructuredError.

Parameter schemas

SQL types map to JSON Schema as follows. Names are matched case-insensitively, and a precision suffix such as (10,2) is ignored.

Array parameters wrap that schema in { "type": "array", "items": ... }.

Every field also has a nullable boolean. That property is not JSON Schema nullability: a nullable TEXT parameter stays "type": "string" with "nullable": true. JSON and JSONB already include null in type. A SQL DEFAULT expression is copied into default as a string, such as "'pending'" or "now()", not as a typed example value.

Structured error

1{2  "type": "object",3  "required": ["status", "code", "message"],4  "properties": {5    "status": { "type": "string", "const": "error" },6    "code": { "type": "string" },7    "message": { "type": "string" },8    "fieldPath": { "type": "string" }9  }10}

fieldPath is optional. This component describes errors from routine invocation. Fetching the document itself returns this shape for EPOCH_MISMATCH, and the bearer-token envelope for authentication failures.

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.