HeliosDB HTTP API Reference

HeliosDB HTTP API Reference

Version: 7.2.0 | Default Port: 18443 | License: Apache-2.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:18443

Configure the port via CLI flag --http-port or environment variable HELIOSDB_HTTP_PORT.

---

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": "7.2.0"}

Readiness Check

Check if the server is ready to accept queries.

Endpoints: GET /ready | GET /readyz

Response:

{"ready": true}

Server Status

Get server status and enabled protocols.

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

Response:

{"status": "running", "version": "7.2.0", "protocols": ["postgresql", "mysql", "http"]}

Server Info

Get server identification and available endpoints.

Endpoint: GET /

Response:

{"name": "HeliosDB", "version": "7.2.0", "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:18443/api/v1/query \
  -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:18443/api/v1/query \
  -d '{"query": "CREATE TABLE users (id INTEGER, name VARCHAR)"}'

curl -s -X POST http://localhost:18443/api/v1/query \
  -d '{"query": "BEGIN"}'

curl -s -X POST http://localhost:18443/api/v1/query \
  -d '{"query": "INSERT INTO users VALUES (1, '\''Alice'\'')"}'

curl -s -X POST http://localhost:18443/api/v1/query \
  -d '{"query": "COMMIT"}'

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

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

Python (requests)

import requests

BASE_URL = "http://localhost:18443"

def sql(query):
    resp = requests.post(f"{BASE_URL}/api/v1/query", json={"query": query}, 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)

async function sql(query) {
    const resp = await fetch("http://localhost:18443/api/v1/query", {
        method: "POST",
        headers: {"Content-Type": "application/json"},
        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 Status	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

HeliosDB also exposes cloud database compatibility endpoints:

API	Path Prefix	Auth	Description
Snowflake	/snowflake/*	JWT	Snowflake REST API compatibility
Databricks	/dbsql/*	Bearer token	Databricks SQL API compatibility
Pinecone	/pinecone/*	API key (x-api-key header)	Pinecone Vector API compatibility

---

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