---
title: "HeliosDB API Reference Overview"
---

# 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](/docs/full/guides/user/connecting/) and the
[Server Configuration Reference](/docs/full/reference/configuration/).

---

## 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 |

```bash
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](/docs/full/reference/api/http_rest_api/).

---

## 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](https://github.com/HeliosDatabase/HeliosDB-SDKs).

### Python Example

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

```go
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](/docs/full/guides/user/connecting/#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](/docs/full/reference/api/http_rest_api/#rate-limits).

## Related Documentation

- [HTTP/REST API reference](/docs/full/reference/api/http_rest_api/)
- [Connecting](/docs/full/guides/user/connecting/)
- [Server Configuration Reference](/docs/full/reference/configuration/)
- [Protocol reference](/docs/full/reference/protocols/)