REST API Reference

REST API Reference

Complete API documentation for HeliosDB Nano

---

Base URL

http://localhost:6543/api/v1

Authentication

All API requests require a Bearer token:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     http://localhost:6543/api/v1/...

See Authentication Guide for token management.

---

API Endpoints Overview

Core Database

Endpoint	Method	Description
/query	POST	Execute SQL queries
/branches	GET	List database branches
/branches	POST	Create new branch
/branches/:name	DELETE	Delete branch
/branches/:name/merge	POST	Merge branch

REST/CRUD (Supabase-Compatible)

Endpoint	Method	Description
/rest/v1/:table	GET	Select rows
/rest/v1/:table	POST	Insert rows
/rest/v1/:table	PATCH	Update rows
/rest/v1/:table	DELETE	Delete rows

AI/ML Features

Endpoint	Method	Description
/vectors/search	POST	Vector similarity search
/vectors/upsert	POST	Insert/update vectors
/documents/chunk	POST	Chunk documents
/documents/embed	POST	Generate embeddings

Schema Management

Endpoint	Method	Description
/schema/infer	POST	Infer schema from JSON
/schema/infer/batch	POST	Batch schema inference
/schema/validate	POST	Validate DDL
/schema/compare	POST	Compare schemas
/schema/optimize	POST	Suggest optimizations

Chat/Completions (OpenAI-Compatible)

Endpoint	Method	Description
/chat/completions	POST	Chat completion
/embeddings	POST	Generate embeddings

Agent Memory

Endpoint	Method	Description
/agents/sessions	GET	List sessions
/agents/sessions	POST	Create session
/agents/sessions/:id	GET	Get session
/agents/sessions/:id/messages	POST	Add message
/agents/sessions/:id/summarize	POST	Summarize session

---

Query Endpoint

Execute SQL

POST /api/v1/query

Request:

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

Response:

{
  "success": true,
  "data": {
    "columns": ["id", "name", "age", "email"],
    "rows": [
      [1, "Alice", 25, "alice@example.com"],
      [2, "Bob", 30, "bob@example.com"]
    ],
    "row_count": 2,
    "execution_time_ms": 5
  }
}

Parameterized Queries

POST /api/v1/query

{
  "sql": "SELECT * FROM users WHERE email = $1",
  "params": ["alice@example.com"]
}

Batch Queries

POST /api/v1/query/batch

{
  "queries": [
    {"sql": "SELECT COUNT(*) FROM users"},
    {"sql": "SELECT COUNT(*) FROM orders"},
    {"sql": "SELECT SUM(amount) FROM orders"}
  ]
}

---

REST/CRUD Endpoints

Select (GET)

# Basic select
GET /rest/v1/users?select=id,name,email

# With filters
GET /rest/v1/users?select=*&age=gt.21&name=ilike.*alice*

# With ordering
GET /rest/v1/users?select=*&order=created_at.desc

# With pagination
GET /rest/v1/users?select=*&limit=10&offset=20

# With embedding
GET /rest/v1/posts?select=*,author:users(name,email)

Filter Operators:

Operator	Description	Example
eq	Equal	status=eq.active
neq	Not equal	status=neq.deleted
gt	Greater than	age=gt.21
gte	Greater than or equal	age=gte.21
lt	Less than	price=lt.100
lte	Less than or equal	price=lte.100
like	LIKE pattern	name=like.*smith*
ilike	Case-insensitive LIKE	name=ilike.*SMITH*
in	In list	status=in.(active,pending)
is	IS NULL/NOT NULL	deleted_at=is.null

Insert (POST)

POST /rest/v1/users
Content-Type: application/json

{
  "name": "Alice",
  "email": "alice@example.com",
  "age": 25
}

Bulk Insert:

[
  {"name": "Alice", "email": "alice@example.com"},
  {"name": "Bob", "email": "bob@example.com"}
]

With RETURNING:

POST /rest/v1/users?select=id,created_at
Prefer: return=representation

Update (PATCH)

PATCH /rest/v1/users?id=eq.1
Content-Type: application/json

{
  "name": "Alice Updated",
  "updated_at": "2024-01-15T00:00:00Z"
}

Delete (DELETE)

DELETE /rest/v1/users?id=eq.1

Upsert

POST /rest/v1/users
Prefer: resolution=merge-duplicates

{
  "id": 1,
  "name": "Alice",
  "email": "alice_new@example.com"
}

---

Vector Search

Similarity Search

POST /api/v1/vectors/search

{
  "table": "documents",
  "column": "embedding",
  "query_vector": [0.1, 0.2, 0.3, ...],
  "limit": 10,
  "metric": "cosine",
  "filter": {
    "category": "technology"
  }
}

Response:

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "doc-123",
        "content": "Introduction to machine learning...",
        "distance": 0.123,
        "metadata": {"category": "technology"}
      }
    ]
  }
}

Vector Upsert

POST /api/v1/vectors/upsert

{
  "table": "documents",
  "vectors": [
    {
      "id": "doc-001",
      "embedding": [0.1, 0.2, 0.3, ...],
      "metadata": {
        "content": "Hello world",
        "category": "greeting"
      }
    }
  ]
}

---

Schema Inference

See detailed Schema Generation Guide.

Quick Example

POST /api/v1/schema/infer

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

Response:

{
  "success": true,
  "data": {
    "table_name": "products",
    "columns": [
      {"name": "id", "sql_type": "INTEGER", "nullable": false},
      {"name": "name", "sql_type": "VARCHAR(18)", "nullable": false},
      {"name": "price", "sql_type": "NUMERIC", "nullable": true}
    ],
    "ddl": "CREATE TABLE products (\n    id INTEGER NOT NULL,\n    name VARCHAR(18) NOT NULL,\n    price NUMERIC,\n    PRIMARY KEY (id)\n);",
    "confidence": 0.85
  }
}

---

Database Branching

List Branches

GET /api/v1/branches

Response:

{
  "success": true,
  "data": {
    "branches": [
      {"name": "main", "created_at": "2024-01-01T00:00:00Z", "is_current": true},
      {"name": "feature-x", "created_at": "2024-01-10T00:00:00Z", "parent": "main"}
    ]
  }
}

Create Branch

POST /api/v1/branches

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

Switch Branch

POST /api/v1/branches/feature-testing/use

Merge Branch

POST /api/v1/branches/feature-testing/merge

{
  "target": "main",
  "strategy": "three-way"
}

---

Agent Memory API

Create Session

POST /api/v1/agents/sessions

{
  "agent_id": "assistant-v1",
  "metadata": {
    "user_id": "user-123",
    "conversation_type": "support"
  }
}

Add Message

POST /api/v1/agents/sessions/:session_id/messages

{
  "role": "user",
  "content": "How do I reset my password?",
  "metadata": {"timestamp": "2024-01-15T10:00:00Z"}
}

Get Session with Messages

GET /api/v1/agents/sessions/:session_id?include=messages

Summarize Session

POST /api/v1/agents/sessions/:session_id/summarize

{
  "target_tokens": 500
}

---

Error Handling

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_QUERY",
    "message": "Syntax error near 'SELEC'",
    "details": {
      "line": 1,
      "column": 1
    }
  }
}

Common Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid token
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
INVALID_QUERY	400	SQL syntax error
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error

---

Rate Limiting

Plan	Requests/Second	Burst
Free	10	20
Starter	100	200
Pro	1,000	2,000
Enterprise	Unlimited	Unlimited

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1702640000

---

OpenAPI Specification

Full OpenAPI 3.0 spec available at:

GET /api/v1/openapi.json
GET /api/v1/openapi.yaml

Interactive documentation:

GET /api/v1/docs

---

Next Steps

• Schema Generation Guide - AI-friendly schema inference
• Vector Search Guide - Semantic similarity queries
• Authentication - Token management