---
title: "HTTP/REST API Compatibility"
---

# HTTP/REST API Compatibility

What the HTTP gateway of `heliosdb-full` supports. The gateway is a SQL-over-HTTP
interface of its own; it does not emulate another vendor's REST API.

## Transport and authentication

| Feature | Supported | Notes |
|---------|-----------|-------|
| HTTP/1.1 | Yes | Plain HTTP; default port 8443 |
| TLS (HTTPS) | Through a reverse proxy | The gateway does not terminate TLS |
| API key | Yes | `HELIOSDB_API_KEY`, sent as `Authorization: Bearer` or `X-API-Key` |
| Per-user accounts, JWT, OAuth, Basic, mTLS | No | Use the PostgreSQL listener and database roles for per-user logins |
| CORS | Yes | `Access-Control-Allow-Origin: *` on responses |
| WebSocket | No | |
| Server-sent events | Chat route only | `"stream": true` on `/api/v1/chat/completions` |

## Request and response

| Feature | Supported | Notes |
|---------|-----------|-------|
| JSON request body | Yes | `{"query": "<one SQL statement>"}` |
| Bind parameters | No | Validate values in the application or use a PostgreSQL driver |
| Several statements per request | No | Send one statement per request |
| JSON response | Yes | `success`, `columns` (name, type), `rows`, `row_count` |
| Column types in responses | `integer`, `float`, `boolean`, `text` | Other SQL types are reported as `text` |
| Streaming large results | No | Page with `LIMIT` and keyset conditions |

## SQL

| Feature | Supported | Notes |
|---------|-----------|-------|
| SELECT, INSERT, UPDATE, DELETE, DDL | Yes | Same SQL engine as the PostgreSQL listener |
| Transactions | With pinned sessions | Start the server with `--http-sessions`; plain requests are reset after each request |
| Temporary tables, `SET` across requests | With pinned sessions | |

## Other routes

| Route family | Supported | Notes |
|--------------|-----------|-------|
| Health, readiness, status | Yes | No key needed |
| AI: chat, embeddings, transcription | Yes | Needs a configured provider (`HELIOSDB_AI_*`) |
| Vector stores, agent memory, documents | Yes | Stored in HeliosDB; embeddings from the configured provider |
| `/snowflake/`, `/dbsql/`, `/pinecone/` paths | No | Answered with `501 Not Implemented` |

See the [HTTP/REST API reference](/docs/full/reference/api/http_rest_api/).