---
title: "HeliosDB HTTP API Reference"
---

# 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**:
```json
{
    "query": "SELECT id, name, salary FROM employees WHERE salary > 70000"
}
```

**Response (success)**:
```json
{
    "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)**:
```json
{
    "success": false,
    "error": "Syntax error near 'SELECTT'"
}
```

### Health Check

Check if the server is running.

**Endpoints**: `GET /health` | `GET /healthz`

**Response**:
```json
{"status": "healthy", "version": "x.y.z"}
```

### Readiness Check

Check if the server is ready to accept queries.

**Endpoints**: `GET /ready` | `GET /readyz`

**Response**:
```json
{"ready": true}
```

### Server state

Get Server state and enabled protocols.

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

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

### Server Info

Get server identification and available endpoints.

**Endpoint**: `GET /`

**Response**:
```json
{"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

```bash
# 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)

```python
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)

```javascript
// 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*