HeliosDB API Reference Overview

Applications reach HeliosDB Full through the database clients they already use, over the wire protocols the heliosdb-full server opens, or through its HTTP gateway.

Interfaces

Interface	Default port	Enabled	Use case
PostgreSQL wire	5432	yes	Application code, ORMs, SQL tools, migrations
HTTP gateway	8443 (plain HTTP; terminate TLS in a proxy)	yes	Scripts, serverless functions, tools without a database driver
MySQL wire	3306	--enable-mysql	Existing MySQL applications
Oracle TNS	1521	--enable-oracle	Existing Oracle thin-client applications
MongoDB wire	27017	--enable-mongodb	Existing MongoDB applications
Cassandra CQL	9042	--enable-cassandra	Existing Cassandra applications
Redis (RESP)	6379	--enable-redis	Key-value access
SQL Server (TDS)	1433	--enable-sqlserver	Existing TDS clients

The server has no WebSocket, GraphQL or gRPC API. Credentials, ports and TLS for each listener are described in Connecting and the Server Configuration Reference.

---

HTTP gateway

Method	Path	Purpose
GET	/health, /ready, /status	Probes and server status (no key needed)
POST	/api/v1/query	Run one SQL statement: {"query": "..."}
POST, DELETE	/api/v1/sessions	Pinned sessions for transactions (--http-sessions)
POST	/api/v1/chat/completions, /api/v1/embeddings, /api/v1/audio/transcriptions	AI provider routes
various	/api/v1/vectors/..., /api/v1/agents/memory/..., /api/v1/documents/...	Vector stores, agent memory, documents

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 WHERE status = '"'"'active'"'"' LIMIT 10"}'

The gateway has no bind parameters; use a PostgreSQL driver when you need them. Port, bind address, API key, sessions and rate limits: HTTP/REST API reference.

---

Application Drivers

HeliosDB Full does not expose a gRPC API. Applications connect over the PostgreSQL wire protocol (port 5432) with any standard PostgreSQL driver, or over the HTTP gateway described above.

Language	Driver	Installation
Python	psycopg	pip install "psycopg[binary]"
Go	pgx	go get github.com/jackc/pgx/v5
Java	PostgreSQL JDBC	org.postgresql:postgresql (Maven/Gradle)
Node.js	node-postgres	npm install pg
Rust	tokio-postgres / sqlx	cargo add tokio-postgres

HTTP clients for the REST API are in HeliosDatabase/HeliosDB-SDKs.

Python Example

import psycopg

with psycopg.connect("host=localhost port=5432 user=helios password=secret dbname=heliosdb sslmode=require") as conn:
    rows = conn.execute("SELECT * FROM users WHERE age > %s", (21,)).fetchall()
    for row in rows:
        print(row)

Go Example

package main

import (
    "context"
    "log"

    "github.com/jackc/pgx/v5"
)

func main() {
    ctx := context.Background()
    conn, err := pgx.Connect(ctx, "postgres://helios:secret@localhost:5432/heliosdb?sslmode=require")
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close(ctx)

    rows, err := conn.Query(ctx, "SELECT id, name FROM users LIMIT 10")
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()
    for rows.Next() {
        var id int64
        var name string
        if err := rows.Scan(&id, &name); err != nil {
            log.Fatal(err)
        }
        log.Println(id, name)
    }
}

---

Authentication

Interface	How clients authenticate
PostgreSQL	Database roles with SCRAM-SHA-256 (postgres with HELIOSDB_SUPERUSER_PASSWORD, or CREATE ROLE ... LOGIN PASSWORD); optional TLS
HTTP gateway	One shared API key, HELIOSDB_API_KEY, as Authorization: Bearer or X-API-Key
Other listeners	See Credentials per listener

Rate limiting

New connections per client IP are limited on all listeners (default 500 per minute, --conn-rate-limit); per-IP query limits on the PostgreSQL wire and POST /api/v1/query are opt-in (--query-rate-limit). HELIOSDB_RATE_LIMITING=false turns both off. See Rate limits.

Related Documentation

• HTTP/REST API reference
• Connecting
• Server Configuration Reference
• Protocol reference