REST API Reference

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. 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 repository:

Python SDK
TypeScript SDK
Go SDK
SDKs & Integrations (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)

[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 for every key.

Environment Variables

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 for changes between releases.

Support & Contact

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