Skip to content
HeliosDB HeliosDB Full

HTTP/REST API Protocol

HeliosDB Full includes an HTTP gateway that runs SQL over HTTP and returns JSON. It runs inside the heliosdb-full server process and reads and writes the same tables as the wire-protocol listeners.

Overview

PropertyValue
TransportPlain HTTP/1.1
Default port8443 (--http-port, HELIOSDB_HTTP_PORT)
Bind address127.0.0.1 (--bind-addr; non-loopback needs --allow-external)
EnabledYes (--no-http turns it off)
AuthenticationOne API key, HELIOSDB_API_KEY, sent as Authorization: Bearer <key> or X-API-Key: <key>
SQL endpointPOST /api/v1/query with {"query": "..."}

Port 8443 is only the default number: the gateway does not terminate TLS. Put it behind a TLS-terminating reverse proxy or load balancer for connections that leave the host.

Quick Start

cURL

Terminal window
# Liveness (no key needed)
curl -s http://127.0.0.1:8443/health


# Run SQL
curl -s -X POST http://127.0.0.1:8443/api/v1/query \
  -H "Authorization: Bearer $HELIOSDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT id, name FROM users LIMIT 10"}'

Python (requests)

import os, requests


r = requests.post("http://127.0.0.1:8443/api/v1/query",
                  headers={"Authorization": f"Bearer {os.environ['HELIOSDB_API_KEY']}"},
                  json={"query": "SELECT id, name FROM users WHERE active"},
                  timeout=30)
body = r.json()
if not body.get("success"):
    raise RuntimeError(body.get("error"))
for row in body["rows"]:
    print(row)

JavaScript (fetch)

const res = await fetch("http://127.0.0.1:8443/api/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.HELIOSDB_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "SELECT COUNT(*) AS n FROM orders" }),
});
const body = await res.json();
if (!body.success) throw new Error(body.error);
console.log(body.rows[0][0]);

A successful response has success, columns (name and type), rows (arrays of values) and row_count. A SQL error returns HTTP 200 with success: false and an error message, so always check success.

Documentation