---
title: "REST API Reference"
description: "The HeliosDB Lite REST API: SQL query and execute, branches, schema inference, health, and which endpoint groups are planned."
---

# 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`:

```bash
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](https://www.heliosdb.com/docs/lite/website/getting-started/authentication/) 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](https://www.heliosdb.com/docs/lite/website/getting-started/authentication/). A built-in token service is planned.

---

## Query Endpoint

### Run a Query

```bash
POST /v1/branches/main/query
```

**Request:**
```json
{
  "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:**
```json
{
  "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

```bash
POST /v1/branches/main/execute
```

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

**Response:**
```json
{
  "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:

```bash
# 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](https://www.heliosdb.com/docs/lite/website/guides/vector-search/).

---

## Schema Inference

```bash
POST /v1/schema/infer
```

```json
{
  "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](https://www.heliosdb.com/docs/lite/website/api/schema-generation/).

---

## Database Branching

### List Branches

```bash
GET /v1/branches
```

### Create Branch

```bash
POST /v1/branches
```

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

### Merge Branch

```bash
POST /v1/branches/feature-testing/merge
```

```json
{
  "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:

```json
{
  "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](https://www.heliosdb.com/docs/lite/website/api/schema-generation/): draft DDL from JSON samples
- [Vector Search Guide](https://www.heliosdb.com/docs/lite/website/guides/vector-search/): similarity queries in SQL
- [Authentication](https://www.heliosdb.com/docs/lite/website/getting-started/authentication/): tokens and roles
- [Full Lite REST reference](https://www.heliosdb.com/docs/lite/api/rest-api/)