---
title: "REST API Overview"
description: "The HTTP endpoints the heliosdb-full server serves on port 8443, and where each is documented."
---

# REST API Overview

The `heliosdb-full` server includes an HTTP gateway that runs SQL over HTTP and returns
JSON. It listens on `127.0.0.1:8443` (plain HTTP) by default. The complete reference,
including request and response formats, is the
[HTTP/REST API reference](/docs/full/reference/api/http_rest_api/).

## Endpoints

| Method | Path | Authentication | Purpose |
|--------|------|----------------|---------|
| GET | `/health`, `/healthz` | none | Liveness |
| GET | `/ready`, `/readyz` | none | Readiness |
| GET | `/status`, `/api/v1/status` | none | Server status |
| GET | `/` | none | Server name, version and route list |
| POST | `/api/v1/query`, `/query` | API key | Run one SQL statement |
| POST, DELETE | `/api/v1/sessions` | API key | Pinned sessions (opt-in) |
| POST | `/api/v1/chat/completions`, `/api/v1/embeddings`, `/api/v1/audio/transcriptions` | API key | AI provider calls (when a provider is configured) |
| POST | `/api/v1/vectors/stores`, `/api/v1/vectors/stores/{name}/texts`, `/api/v1/vectors/stores/{name}/search/hybrid` | API key | Vector stores and hybrid search |
| GET, POST, DELETE | `/api/v1/agents/memory[/...]` | API key | Agent memory sessions |
| GET, POST, DELETE | `/api/v1/documents[/...]` | API key | Document ingest and search |

Any other path returns `404`. Table listings, statistics, backups, replication and
other administration are done with SQL from a PostgreSQL client (`psql`), for example
`SHOW TABLES` or `SHOW PROTOCOLS`, or with `POST /api/v1/query`.

## Authentication

Set `HELIOSDB_API_KEY` on the server; clients send it as `Authorization: Bearer <key>`
or `X-API-Key: <key>`. See [Authentication](/docs/full/api/rest/authentication/).

## Port, address and TLS

| Setting | Flag | Environment | Default |
|---------|------|-------------|---------|
| Port | `--http-port` | `HELIOSDB_HTTP_PORT` | `8443` |
| Bind address | `--bind-addr` (plus `--allow-external` for non-loopback) | `HELIOSDB_BIND_ADDR`, `HELIOSDB_ALLOW_EXTERNAL` | `127.0.0.1` |
| Disable the gateway | `--no-http` | | enabled |

The gateway itself speaks plain HTTP. Terminate TLS in a reverse proxy or load balancer
in front of it.

## Rate limits

New connections are limited to 500 per minute per client IP (burst 100) on every
listener; `--conn-rate-limit` changes it. SQL queries are not rate-limited unless you
set `--query-rate-limit <per-second>`, which then applies to `POST /api/v1/query` and the
PostgreSQL wire.

## Errors

A SQL error returns HTTP 200 with `{"success": false, "error": "..."}`; check the
`success` field. A missing or invalid API key returns 401 with
`{"error":"unauthorized"}`, a malformed body returns 400, and an unknown path returns
404 with `{"error":"Not found","path":"..."}`.

## Example

```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 customers LIMIT 10"}'
```