HeliosDB HTTP API Reference

Default Port: 8443 (plain HTTP) | License: SSPL-1.0

---

Overview

HeliosDB exposes a REST API for executing SQL queries via HTTP. No database driver required — send SQL as JSON and receive results as JSON.

Base URL

http://localhost:8443

Configure the port via CLI flag --http-port or environment variable HELIOSDB_HTTP_PORT; --no-http turns the gateway off. The gateway does not terminate TLS, so put a TLS-terminating proxy in front when it leaves the host.

Authentication

/health, /ready, /status and / answer without credentials. Every other route, including /api/v1/query, needs the API key set in HELIOSDB_API_KEY when the server starts, sent as Authorization: Bearer <key> or X-API-Key: <key>. Without HELIOSDB_API_KEY those routes are refused. The examples below read the key from the HELIOSDB_API_KEY variable in your shell.

---

Endpoints

Execute SQL Query

Execute any SQL statement and receive results as JSON.

Endpoints: POST /api/v1/query | POST /query

Request:

{
    "query": "SELECT id, name, salary FROM employees WHERE salary > 70000"
}

Response (success):

{
    "success": true,
    "columns": [
        {"name": "id", "type": "integer"},
        {"name": "name", "type": "text"},
        {"name": "salary", "type": "numeric"}
    ],
    "rows": [
        [1, "Alice", 85000],
        [3, "Charlie", 90000]
    ],
    "row_count": 2
}

Response (error):

{
    "success": false,
    "error": "Syntax error near 'SELECTT'"
}

Health Check

Check if the server is running.

Endpoints: GET /health | GET /healthz

Response:

{"status": "healthy", "version": "x.y.z"}

Readiness Check

Check if the server is ready to accept queries.

Endpoints: GET /ready | GET /readyz

Response:

{"ready": true}

Server state

Get Server state and enabled protocols.

Endpoints: GET /status | GET /api/v1/status

Response:

{"status": "running", "version": "x.y.z", "protocols": ["postgresql", "mysql", "http"]}

Server Info

Get server identification and available endpoints.

Endpoint: GET /

Response:

{"name": "HeliosDB", "version": "x.y.z", "endpoints": ["/health", "/status", "/api/v1/query"]}

---

SQL Support

All SQL features supported by the PostgreSQL wire protocol are available via the HTTP API:

• DDL: CREATE TABLE, DROP TABLE, ALTER TABLE, CREATE INDEX, CREATE VIEW
• DML: INSERT, UPDATE, DELETE, TRUNCATE, SELECT with all clauses
• Queries: WHERE, ORDER BY, GROUP BY, HAVING, DISTINCT, LIMIT, OFFSET
• Joins: INNER, LEFT, RIGHT, FULL OUTER, CROSS
• Set Operations: UNION, INTERSECT, EXCEPT
• Subqueries: IN, NOT IN, EXISTS, scalar subqueries
• CTEs: WITH, WITH RECURSIVE
• Aggregates: COUNT, SUM, AVG, MIN, MAX
• Window Functions: ROW_NUMBER, RANK, DENSE_RANK, LAG, LEAD, NTILE
• Functions: String, math, date/time, CASE WHEN, COALESCE
• Transactions: BEGIN, COMMIT, ROLLBACK (per HTTP connection context)
• Stored Functions: CREATE FUNCTION, CALL

See SQL Reference for complete syntax documentation.

---

Value Types in Responses

SQL Type	JSON Type	Example
INTEGER, BIGINT	number	42
REAL, NUMERIC	number	3.14
BOOLEAN	boolean	true
VARCHAR, TEXT	string	"hello"
NULL	null	null
DATE, TIMESTAMP	string	"2024-01-15"

---

Examples

curl

# Simple query
curl -s -X POST http://localhost:8443/api/v1/query \
  -H "Authorization: Bearer $HELIOSDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT 1 + 2"}' | python3 -m json.tool

# Create table and insert data
curl -s -X POST http://localhost:8443/api/v1/query \
  -H "Authorization: Bearer $HELIOSDB_API_KEY" \
  -d '{"query": "CREATE TABLE users (id INTEGER, name VARCHAR)"}'

curl -s -X POST http://localhost:8443/api/v1/query \
  -H "Authorization: Bearer $HELIOSDB_API_KEY" \
  -d '{"query": "BEGIN"}'

curl -s -X POST http://localhost:8443/api/v1/query \
  -H "Authorization: Bearer $HELIOSDB_API_KEY" \
  -d '{"query": "INSERT INTO users VALUES (1, '\''Alice'\'')"}'

curl -s -X POST http://localhost:8443/api/v1/query \
  -H "Authorization: Bearer $HELIOSDB_API_KEY" \
  -d '{"query": "COMMIT"}'

# Query with aggregates
curl -s -X POST http://localhost:8443/api/v1/query \
  -H "Authorization: Bearer $HELIOSDB_API_KEY" \
  -d '{"query": "SELECT COUNT(*), AVG(id) FROM users"}'

# Health check
curl -s http://localhost:8443/health

Python (requests)

import os
import requests

BASE_URL = "http://localhost:8443"
HEADERS = {"Authorization": f"Bearer {os.environ['HELIOSDB_API_KEY']}"}

def sql(query):
    resp = requests.post(f"{BASE_URL}/api/v1/query", json={"query": query},
                         headers=HEADERS, timeout=10)
    return resp.json()

# Create and populate table
sql("CREATE TABLE products (id INTEGER, name VARCHAR, price NUMERIC)")
sql("BEGIN")
sql("INSERT INTO products VALUES (1, 'Widget', 9.99)")
sql("INSERT INTO products VALUES (2, 'Gadget', 24.99)")
sql("COMMIT")

# Query
result = sql("SELECT name, price FROM products ORDER BY price DESC")
if result["success"]:
    for row in result["rows"]:
        print(f"{row[0]}: ${row[1]}")

# Cleanup
sql("BEGIN")
sql("DROP TABLE products")
sql("COMMIT")

JavaScript (fetch)

// apiKey: the HELIOSDB_API_KEY value, from your server-side configuration
async function sql(query) {
    const resp = await fetch("http://localhost:8443/api/v1/query", {
        method: "POST",
        headers: {"Content-Type": "application/json", "Authorization": `Bearer ${apiKey}`},
        body: JSON.stringify({query})
    });
    return resp.json();
}

const result = await sql("SELECT COUNT(*) AS total FROM users");
console.log(`Total users: ${result.rows[0][0]}`);

---

Error Handling

Scenario	HTTP State	Response
Valid query, success	200	{"success": true,...}
SQL syntax error	200	{"success": false, "error": "..."}
Table not found	200	{"success": true, "row_count": 0, "rows": []}
Empty query	200	{"success": true,...}
Malformed JSON	400	Error message

---

CORS

The API includes Access-Control-Allow-Origin: * headers for browser compatibility.

---

Cloud Compatibility APIs (planned)

Snowflake, Databricks and Pinecone compatibility APIs are planned; today the /snowflake/, /dbsql/ and /pinecone/ paths answer 501 Not Implemented.

---

Part of the HeliosDB Full workspace. See also: Feature Matrix | SQL Reference