---
title: "REST API Reference"
description: "HeliosDB Lite REST API reference: SQL query and execute, branches, schema inference, health, error codes and configuration, with planned endpoints marked."
---

# HeliosDB-Lite API Reference

Complete API reference for all HeliosDB-Lite integration points across languages and deployment modes.

---

## REST API (Server Mode)

Base URL: `http://localhost:8080` (default)

> **Status:** `heliosdb-lite start` serves this API on the HTTP port (default 8080) under `/v1` and `/api/v1`. Every `/v1` route needs `Authorization: Bearer <JWT>`, signed with `HELIOSDB_JWT_SECRET`; see [Authentication](/docs/lite/website/getting-started/authentication/). The query, execute, branch, schema-inference and query-cancellation routes work. The vector-store, document, agent-memory and chat routes are mounted but return a not-implemented error; they are planned. The natural-language query and tenant routes below are planned and are not served by the current release. For vector search today, use SQL (`ORDER BY embedding <-> '[...]'`) through the query route or the PostgreSQL wire.

### Endpoints

#### Queries

**Execute SQL Query**

```
POST /v1/branches/{branch}/query
Content-Type: application/json

Request Body:
{
  "sql": "SELECT * FROM users WHERE id = $1",
  "params": [1]
}

Response (200 OK):
{
  "rows": [
    {"id": 1, "name": "Alice", "email": "alice@example.com"}
  ],
  "columns": ["id", "name", "email"],
  "rows_affected": 0
}

Error Response (400):
{
  "error": {
    "code": "42P01",
    "message": "relation \"users\" does not exist"
  }
}
```

**Execute Natural Language Query**

```
POST /v1/nl/query
Content-Type: application/json

Request Body:
{
  "question": "How many users are from California?",
  "branch": "main"
}

Response (200 OK):
{
  "sql": "SELECT COUNT(*) FROM users WHERE state = 'California'",
  "rows": [{"count": 42}],
  "columns": ["count"]
}
```

**Query at Timestamp (Time-Travel)**

```
POST /v1/branches/{branch}/query
Content-Type: application/json

Request Body:
{
  "sql": "SELECT * FROM users",
  "params": [],
  "as_of_timestamp": "2025-01-01T00:00:00Z"
}

Response (200 OK):
{
  "rows": [...],
  "columns": [...],
  "rows_affected": 0
}
```

#### Vector Search

**Text Vector Search**

```
POST /v1/vectors/stores/{store}/search/text
Content-Type: application/json

Request Body:
{
  "text": "machine learning",
  "top_k": 10,
  "min_score": 0.5,
  "filter": {"category": "tech"}
}

Response (200 OK):
{
  "results": [
    {
      "id": "doc_123",
      "score": 0.95,
      "content": "Machine learning is...",
      "metadata": {"category": "tech", "year": 2024}
    }
  ]
}
```

**Vector Search by Vector**

```
POST /v1/vectors/stores/{store}/search
Content-Type: application/json

Request Body:
{
  "vector": [0.1, 0.2, 0.3, ...],
  "top_k": 10,
  "min_score": 0.5
}

Response (200 OK):
{
  "results": [
    {
      "id": "doc_123",
      "score": 0.95,
      "content": "...",
      "metadata": {}
    }
  ]
}
```

**Store Text with Embedding**

```
POST /v1/vectors/stores/{store}/texts
Content-Type: application/json

Request Body:
{
  "texts": ["Document 1", "Document 2"],
  "metadatas": [
    {"source": "blog"},
    {"source": "wiki"}
  ]
}

Response (200 OK):
{
  "ids": ["doc_1", "doc_2"]
}
```

#### Vector Store Management

**List Vector Stores**

```
GET /v1/vectors/stores

Response (200 OK):
{
  "stores": [
    {
      "name": "documents",
      "dimensions": 1536,
      "metric": "cosine",
      "count": 1000
    }
  ]
}
```

**Create Vector Store**

```
POST /v1/vectors/stores
Content-Type: application/json

Request Body:
{
  "name": "documents",
  "dimensions": 1536,
  "metric": "cosine"
}

Response (201 Created):
{
  "name": "documents",
  "dimensions": 1536,
  "metric": "cosine",
  "count": 0
}
```

#### Branching

**List Branches**

```
GET /v1/branches

Response (200 OK):
{
  "branches": [
    {
      "name": "main",
      "parent": null,
      "created_at": "2025-01-01T00:00:00Z"
    },
    {
      "name": "dev",
      "parent": "main",
      "created_at": "2025-01-10T12:30:00Z"
    }
  ]
}
```

**Create Branch**

```
POST /v1/branches
Content-Type: application/json

Request Body:
{
  "name": "feature-branch",
  "from_branch": "main"
}

Response (201 Created):
{
  "name": "feature-branch",
  "parent": "main",
  "created_at": "2025-01-15T10:00:00Z"
}
```

**Merge Branches**

```
POST /v1/branches/{source}/merge
Content-Type: application/json

Request Body:
{
  "target": "main"
}

Response (200 OK):
{
  "status": "merged",
  "changes": 5
}
```

#### Agent Memory

**Add Memory**

```
POST /v1/agents/memory/{session_id}/add
Content-Type: application/json

Request Body:
{
  "role": "user",
  "content": "Hello, how can you help?"
}

Response (200 OK):
{
  "status": "stored"
}
```

**Get Memory**

```
GET /v1/agents/memory/{session_id}/messages?limit=50

Response (200 OK):
{
  "messages": [
    {
      "id": "msg_1",
      "role": "user",
      "content": "Hello",
      "timestamp": "2025-01-15T10:00:00Z"
    }
  ]
}
```

**Search Memory**

```
POST /v1/agents/memory/{session_id}/search
Content-Type: application/json

Request Body:
{
  "query": "What did we discuss about performance?",
  "top_k": 5
}

Response (200 OK):
{
  "results": [
    {
      "id": "msg_123",
      "content": "Performance is critical for production...",
      "score": 0.92
    }
  ]
}
```

#### Document Management

**List Collections**

```
GET /v1/documents/collections

Response (200 OK):
{
  "collections": [
    {
      "name": "knowledge_base",
      "document_count": 150,
      "chunk_count": 1200,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}
```

**Create Collection**

```
POST /v1/documents/collections
Content-Type: application/json

Request Body:
{
  "name": "knowledge_base",
  "chunk_size": 512,
  "chunk_overlap": 50
}

Response (201 Created):
{
  "name": "knowledge_base",
  "chunk_size": 512,
  "chunk_overlap": 50,
  "created_at": "2025-01-15T10:00:00Z"
}
```

**Upload Document**

```
POST /v1/documents/collections/{collection}/documents
Content-Type: multipart/form-data

Form Data:
- file: (binary file content)
- metadata: {"source": "manual", "author": "admin"}

Response (201 Created):
{
  "id": "doc_abc123",
  "filename": "guide.pdf",
  "chunks": 25,
  "status": "processed"
}
```

**Search Documents (RAG)**

```
POST /v1/documents/collections/{collection}/search
Content-Type: application/json

Request Body:
{
  "query": "How do I configure authentication?",
  "top_k": 5,
  "include_content": true
}

Response (200 OK):
{
  "results": [
    {
      "chunk_id": "chunk_123",
      "document_id": "doc_abc",
      "content": "Authentication can be configured...",
      "score": 0.95,
      "metadata": {"source": "guide.pdf", "page": 5}
    }
  ]
}
```

#### Schema Inference

**Infer Schema from JSON**

```
POST /v1/schema/infer
Content-Type: application/json

Request Body:
{
  "format": "json",
  "data": [
    {"id": 1, "name": "Alice", "score": 95.5},
    {"id": 2, "name": "Bob", "score": 87.3}
  ],
  "table_name": "students"
}

Response (200 OK):
{
  "sql": "CREATE TABLE students (\n  id INTEGER,\n  name TEXT,\n  score REAL\n);",
  "columns": [
    {"name": "id", "type": "INTEGER", "nullable": false},
    {"name": "name", "type": "TEXT", "nullable": false},
    {"name": "score", "type": "REAL", "nullable": false}
  ]
}
```

**Infer Schema from CSV**

```
POST /v1/schema/infer
Content-Type: application/json

Request Body:
{
  "format": "csv",
  "data": "id,name,score\n1,Alice,95.5\n2,Bob,87.3",
  "table_name": "students"
}

Response (200 OK):
{
  "sql": "CREATE TABLE students (...);",
  "columns": [...]
}
```

#### Chat Completion (AI)

**Chat Completion**

```
POST /v1/chat/completions
Content-Type: application/json

Request Body:
{
  "session_id": "session_123",
  "message": "What tables have a customer_id column?",
  "include_sql": true
}

Response (200 OK):
{
  "response": "I found 3 tables with a customer_id column: orders, invoices, and support_tickets.",
  "sql_executed": "SELECT table_name FROM pg_columns WHERE column_name = 'customer_id'",
  "results": [
    {"table_name": "orders"},
    {"table_name": "invoices"},
    {"table_name": "support_tickets"}
  ]
}
```

#### Query Management

**Cancel Query**

```
POST /v1/queries/{query_id}/cancel

Response (200 OK):
{
  "status": "cancelled",
  "query_id": "q_abc123"
}
```

**List Active Queries**

```
GET /v1/queries/active

Response (200 OK):
{
  "queries": [
    {
      "id": "q_abc123",
      "sql": "SELECT * FROM large_table",
      "started_at": "2025-01-15T10:00:00Z",
      "duration_ms": 5000,
      "state": "running"
    }
  ]
}
```

#### Tenant Management

**List Tenants**

```
GET /v1/tenants

Response (200 OK):
{
  "tenants": [
    {
      "id": 1,
      "name": "acme_corp",
      "plan": "enterprise",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}
```

**Create Tenant**

```
POST /v1/tenants
Content-Type: application/json

Request Body:
{
  "name": "acme_corp",
  "plan": "enterprise",
  "isolation": "schema"
}

Response (201 Created):
{
  "id": 1,
  "name": "acme_corp",
  "plan": "enterprise",
  "isolation": "schema",
  "created_at": "2025-01-15T10:00:00Z"
}
```

**Get Tenant Usage**

```
GET /v1/tenants/{tenant_id}/usage

Response (200 OK):
{
  "tenant_id": 1,
  "storage_bytes": 1073741824,
  "connections_active": 5,
  "queries_per_second": 100,
  "quota": {
    "storage_bytes": 10737418240,
    "max_connections": 50,
    "max_qps": 1000
  }
}
```

**Set Tenant Context**

```
POST /v1/tenants/context
Content-Type: application/json

Request Body:
{
  "tenant_id": 1
}

Response (200 OK):
{
  "status": "context_set",
  "tenant_id": 1,
  "tenant_name": "acme_corp"
}
```

#### Health

**Health Check**

```
GET /health

Response (200 OK):
{
  "status": "ok"
}
```

---

## PostgreSQL Wire Protocol (Server Mode)

Standard PostgreSQL protocol on port 5432.

### Connection String Format

```
postgresql://[user[:password]@][host][:port]/[database]

Examples:
postgresql://localhost:5432/mydb
postgresql://user:password@db.example.com:5432/mydb
postgres://localhost/mydb
```

### Supported Features

- Standard SQL (DML/DDL)
- Parameterized queries ($1, $2,...)
- Transactions (BEGIN/COMMIT/ROLLBACK)
- Multiple data types
- Indexes
- Transactions with isolation levels

### Supported Client Libraries

- **Python**: psycopg2, asyncpg, sqlalchemy
- **JavaScript/Node**: pg, node-postgres, sequelize
- **Rust**: sqlx, tokio-postgres, diesel
- **Go**: database/sql, pgx, sqlc
- **Java**: JDBC, Hibernate
- **.NET**: Npgsql, Entity Framework
- **PHP**: PDO, php-pgsql

---

## Client SDKs

The Apache-2.0 HeliosDB client SDKs wrap the `/v1` routes above. They are installed from the public
[HeliosDatabase/HeliosDB-SDKs](https://github.com/HeliosDatabase/HeliosDB-SDKs) repository:

- [Python SDK](https://www.heliosdb.com/docs/lite/api/python-sdk/)
- [TypeScript SDK](https://www.heliosdb.com/docs/lite/api/typescript-sdk/)
- [Go SDK](https://www.heliosdb.com/docs/lite/api/go-sdk/)
- [SDKs & Integrations](https://www.heliosdb.com/docs/lite/api/sdks/) (all languages, CLI and platform integrations)

---

## Error Codes & Responses

### HTTP Response Codes

| Code | Meaning | Example |
|------|---------|---------|
| 200 | Success | Query executed |
| 201 | Created | Resource created |
| 400 | Bad Request | Invalid SQL syntax |
| 401 | Unauthorized | Invalid API key |
| 404 | Not Found | Table not found |
| 429 | Rate Limited | Too many requests |
| 500 | Server Error | Internal error |

### PostgreSQL Error Codes (SQLSTATE)

| Code | Class | Meaning |
|------|-------|---------|
| 00000 | SUCCESS | Success |
| 42P01 | SYNTAX_ERROR | Relation does not exist |
| 42P02 | SYNTAX_ERROR | Column does not exist |
| 23505 | INTEGRITY | Unique violation |
| 23503 | INTEGRITY | Foreign key violation |
| 25001 | TRANSACTION | Transaction failed |

---

## Configuration Reference

### Server Configuration (heliosdb.toml)

```toml
[storage]
path = "./heliosdb-data"
cache_size = 536870912

[server]
listen_addr = "127.0.0.1"
port = 5432
max_connections = 100

[performance]
simd_enabled = true
worker_threads = 4

[encryption]
enabled = false
key_source = { Environment = "HELIOSDB_ENCRYPTION_KEY" }

[vector]
enable_pq = true
```

The REST port is set with `heliosdb-lite start --http-port` (default 8080). See the
[Configuration reference](https://www.heliosdb.com/docs/lite/user-guide/configuration/) for every key.

### Environment Variables

```bash
HELIOSDB_JWT_SECRET=...        # required by `heliosdb-lite start` (REST token signing)
HELIOSDB_ENCRYPTION_KEY=...    # read when [encryption] is enabled with the default key source
RUST_LOG=info                  # log level
```

---

## Rate Limits & Quotas

### Rate Limiting (Server Mode)

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. `[server] max_connections` caps
PostgreSQL wire connections (default 100).

### Resource Limits

- Max query size: No hard limit
- Max result rows: Limited by memory
- Max vector dimensions: 4096
- Max text length: 2 GB per cell

---

## Release Notes

See the [Changelog](https://www.heliosdb.com/docs/lite/releases/changelog/) for changes between releases.

---

## Support & Contact

- **Documentation**: https://www.heliosdb.com/docs/lite/
- **Email**: support@heliosdb.com