REST API Reference

REST endpoints served by heliosdb-lite start

Base URL

http://127.0.0.1:8080/v1

heliosdb-lite start serves the REST API on the HTTP port (--http-port, default 8080) at the --listen address (default 127.0.0.1). Every route below is also served under /api/v1. Lite serves PostgreSQL wire and REST; for anything this API does not cover, use SQL over either one.

Authentication

Every /v1 route requires a JWT signed with HELIOSDB_JWT_SECRET:

curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     http://127.0.0.1:8080/v1/branches

The token’s sub claim is the database role the request runs as. See the Authentication Guide for the required claims and for how to mint a token.

API Endpoints Overview

Available Today

Endpoint	Method	Description
`/v1/branches/{branch}/query`	POST	Run a query and return rows
`/v1/branches/{branch}/execute`	POST	Run DDL or DML and return the affected row count
`/v1/branches`	GET	List branches
`/v1/branches`	POST	Create a branch
`/v1/branches/{name}`	GET, DELETE	Get or delete a branch
`/v1/branches/{name}/merge`	POST	Merge a branch into a target
`/v1/schema/infer`	POST	Draft a `CREATE TABLE` from JSON samples
`/v1/schema/infer/batch`	POST	Draft several tables at once
`/v1/queries`	GET	List running queries
`/v1/queries/{query_id}/cancel`	POST	Cancel a running query
`/health`, `/version`, `/metrics`	GET	Health, version and metrics (no token needed)

Planned

These route groups are mounted today but return a not-implemented error or placeholder data. Their behaviour is planned:

Route group	Planned capability	Use today
`/v1/vectors/stores/...` (search, upsert, insert, text and hybrid search)	REST vector stores	SQL vector search: `ORDER BY embedding <-> '[...]'`
`/v1/documents/...`	Document collections, chunking and similarity search	Tables plus SQL vector search
`/v1/agents/memory/...`	Agent memory sessions	Tables keyed by session
`/v1/chat/...` (completions, embeddings, models)	Chat completions and embeddings	Your model provider’s API
`/v1/schema/{validate,compare,optimize,generate,templates}`, `/v1/schema/infer/file`	Schema validation, diffing, optimization and generation	`/v1/schema/infer` plus review

Lite does not serve Supabase-style /rest/v1/{table} routes or /auth/v1 sign-up and token endpoints. Use the query and execute routes for data, and mint tokens as described in Authentication. A built-in token service is planned.

Query Endpoint

Run a Query

POST /v1/branches/main/query

Request:

{
  "sql": "SELECT * FROM users WHERE age > $1 ORDER BY name",
  "params": [{"type": "int4", "value": 21}],
  "timeout_ms": 30000
}

params is optional. Each parameter is typed: null, int4, int8, float4, float8, string, boolean or json. timeout_ms accepts 1 to 600000. The request can also carry as_of for time travel, for example {"type": "timestamp", "value": 1735689600000} (Unix milliseconds).

Response:

{
  "columns": ["id", "name", "age"],
  "column_types": ["INTEGER", "TEXT", "INTEGER"],
  "rows": [
    {"id": 1, "name": "Alice", "age": 25},
    {"id": 2, "name": "Bob", "age": 30}
  ],
  "row_count": 2,
  "execution_time_ms": 5
}

Execute DDL or DML

POST /v1/branches/main/execute

{
  "sql": "UPDATE users SET name = $1 WHERE id = $2",
  "params": [{"type": "string", "value": "Alice Updated"}, {"type": "int4", "value": 1}]
}

Response:

{
  "statement_type": "UPDATE",
  "affected_rows": 1,
  "execution_time_ms": 3
}

Vector Search over SQL

The REST vector-store endpoints are planned. Today, store embeddings in a VECTOR(n) column and query them with SQL, over REST or the PostgreSQL wire:

# Create the table and an HNSW index
curl -X POST http://127.0.0.1:8080/v1/branches/main/execute \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"sql": "CREATE TABLE documents (id INTEGER PRIMARY KEY, content TEXT, embedding VECTOR(3))"}'

curl -X POST http://127.0.0.1:8080/v1/branches/main/execute \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"sql": "CREATE INDEX documents_embedding_idx ON documents USING hnsw (embedding)"}'

# Nearest neighbours
curl -X POST http://127.0.0.1:8080/v1/branches/main/query \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"sql": "SELECT id, content, embedding <-> '\''[0.1, 0.2, 0.3]'\'' AS distance FROM documents ORDER BY distance LIMIT 10"}'

See Vector Search.

Schema Inference

POST /v1/schema/infer

{
  "samples": [
    {"id": 1, "name": "Product A", "price": 29.99},
    {"id": 2, "name": "Product B", "price": null}
  ],
  "table_name": "products"
}

The response ({"success": true, "data": {...}}) holds the inferred columns and a draft ddl. Review the draft before you run it; see the Schema Generation Guide.

Database Branching

List Branches

GET /v1/branches

Create Branch

POST /v1/branches

{
  "name": "feature-testing",
  "parent": "main"
}

Merge Branch

POST /v1/branches/feature-testing/merge

{
  "target": "main"
}

Branches are also managed in SQL: CREATE DATABASE BRANCH feature_testing FROM main AS OF NOW, USE BRANCH feature_testing and MERGE BRANCH feature_testing INTO main.

Error Handling

Errors return an HTTP status and a JSON body:

{
  "error": "BadRequest",
  "message": "SQL query exceeds maximum size of 1MB"
}

Status	`error`	Meaning
400	`BadRequest`	Invalid request (for example, too many parameters or a bad `timeout_ms`)
401	`Unauthorized`	Missing, invalid or expired token
404	`NotFound`	Branch or object not found
408	`QueryTimeout`	The query exceeded `timeout_ms`
422	`UnprocessableEntity`	The statement failed to execute
500	`InternalServerError`	Server error

Rate Limiting

The stock heliosdb-lite start applies no REST rate limit. If you expose the API, put a reverse proxy with rate limiting in front of it.

OpenAPI Specification

The server publishes its OpenAPI document and interactive viewers under the API prefix, behind the same token:

GET /v1/openapi.json
GET /v1/openapi.yaml
GET /v1/docs
GET /v1/redoc

Next Steps

Schema Generation Guide: draft DDL from JSON samples
Vector Search Guide: similarity queries in SQL
Authentication: tokens and roles
Full Lite REST reference