REST API Overview
The heliosdb-full server includes an HTTP gateway that runs SQL over HTTP and returns
JSON. It listens on 127.0.0.1:8443 (plain HTTP) by default. The complete reference,
including request and response formats, is the
HTTP/REST API reference.
Endpoints
| Method | Path | Authentication | Purpose |
|---|---|---|---|
| GET | /health, /healthz | none | Liveness |
| GET | /ready, /readyz | none | Readiness |
| GET | /status, /api/v1/status | none | Server status |
| GET | / | none | Server name, version and route list |
| POST | /api/v1/query, /query | API key | Run one SQL statement |
| POST, DELETE | /api/v1/sessions | API key | Pinned sessions (opt-in) |
| POST | /api/v1/chat/completions, /api/v1/embeddings, /api/v1/audio/transcriptions | API key | AI provider calls (when a provider is configured) |
| POST | /api/v1/vectors/stores, /api/v1/vectors/stores/{name}/texts, /api/v1/vectors/stores/{name}/search/hybrid | API key | Vector stores and hybrid search |
| GET, POST, DELETE | /api/v1/agents/memory[/...] | API key | Agent memory sessions |
| GET, POST, DELETE | /api/v1/documents[/...] | API key | Document ingest and search |
Any other path returns 404. Table listings, statistics, backups, replication and
other administration are done with SQL from a PostgreSQL client (psql), for example
SHOW TABLES or SHOW PROTOCOLS, or with POST /api/v1/query.
Authentication
Set HELIOSDB_API_KEY on the server; clients send it as Authorization: Bearer <key>
or X-API-Key: <key>. See Authentication.
Port, address and TLS
| Setting | Flag | Environment | Default |
|---|---|---|---|
| Port | --http-port | HELIOSDB_HTTP_PORT | 8443 |
| Bind address | --bind-addr (plus --allow-external for non-loopback) | HELIOSDB_BIND_ADDR, HELIOSDB_ALLOW_EXTERNAL | 127.0.0.1 |
| Disable the gateway | --no-http | enabled |
The gateway itself speaks plain HTTP. Terminate TLS in a reverse proxy or load balancer in front of it.
Rate limits
New connections are limited to 500 per minute per client IP (burst 100) on every
listener; --conn-rate-limit changes it. SQL queries are not rate-limited unless you
set --query-rate-limit <per-second>, which then applies to POST /api/v1/query and the
PostgreSQL wire.
Errors
A SQL error returns HTTP 200 with {"success": false, "error": "..."}; check the
success field. A missing or invalid API key returns 401 with
{"error":"unauthorized"}, a malformed body returns 400, and an unknown path returns
404 with {"error":"Not found","path":"..."}.
Example
curl -s -X POST http://127.0.0.1:8443/api/v1/query \ -H "Authorization: Bearer $HELIOSDB_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "SELECT id, name FROM customers LIMIT 10"}'