Swagger UI Quickstart

Available since: v3.8.0 (2026-04-02) Build: default — no feature flag required Endpoints: GET /docs, GET /openapi.json, GET /openapi.yaml, GET /redoc

UVP

Most embedded databases force you to read a manual to learn their HTTP surface. HeliosDB Nano embeds the OpenAPI 3.0 spec at compile time and serves an interactive Swagger UI at /docs — every endpoint, every parameter, every response shape, with a “Try it out” button. Open one URL in a browser and you can hit the database without leaving the tab. ReDoc lives at /redoc for read-only browsing; the raw spec is at /openapi.json and /openapi.yaml for codegen.

1. Start the Server

heliosdb-nano start --memory

The HTTP listener comes up on 127.0.0.1:8080 by default.

2. Open the Explorer

Browse to http://localhost:8080/docs.

You see the embedded swagger-ui-dist@5.9.0 viewer with the live spec already loaded — no spec URL to paste in. The page lists every operation grouped by tag:

Health — /health, /version
Branches — list, create, drop, merge
Data — table CRUD operations
Tables — schema introspection
Vectors — collection / search / k-NN
Documents — RAG ingest
Time Travel — AS OF queries

Each operation can be expanded to see the request body shape, parameter list, and example responses.

3. Run a Query Inline

Click any POST /v1/query route, hit Try it out, paste a JSON body:

{ "sql": "SELECT 1 + 1 AS answer" }

…and click Execute. The UI sends the request to the same server you started in step 1 and renders the JSON response, status code, and response headers.

If your server has BaaS auth enabled, click Authorize at the top and paste Bearer <jwt> (the token from POST /auth/v1/token — see AUTH_AND_OAUTH). Subsequent calls send the header automatically.

4. Point at One of Your Tables

Create a table from any client:

psql "postgresql://postgres@127.0.0.1:5432/postgres" \
  -c "CREATE TABLE notes (id SERIAL PRIMARY KEY, body TEXT)"

Now in Swagger UI, find the Data tag → POST /v1/data/{table}/insert. Set table = notes, body:

{ "rows": [{ "body": "first note" }, { "body": "second note" }] }

Execute. You see the inserted row count in the response, and a follow-up GET on the same table lists what you wrote.

The PostgREST-compatible surface at /rest/v1/{table} is documented separately — see BAAS_REST_API. The REST endpoints share the same OpenAPI spec page.

5. Codegen from the Raw Spec

The same spec is available at:

URL	Format	Use for
`/openapi.json`	OpenAPI 3.0 JSON	`openapi-generator`, `oapi-codegen`, IDE preview
`/openapi.yaml`	OpenAPI 3.0 YAML	hand-editable forks, CI diff checks
`/docs`	Swagger UI HTML	interactive exploration
`/redoc`	ReDoc HTML	read-only single-page reference

Generate a TypeScript client in one shell:

npx @openapitools/openapi-generator-cli generate \
  -i http://localhost:8080/openapi.json \
  -g typescript-fetch \
  -o ./src/heliosdb-client

The spec is embedded at compile time (include_str!("openapi.yaml")) so it can never drift from the binary it ships with.

Troubleshooting

Symptom	Cause	Fix
`/docs` returns 404	HTTP listener not started — bound only to PG/MySQL ports	Default `start` exposes 8080 unless you override `--http-port`
CSS / JS fails to load	Network blocks `unpkg.com` (Swagger assets are CDN-hosted)	Self-host the assets and patch the HTML, or use ReDoc at `/redoc` (also CDN, alternative provider)
`Failed to parse OpenAPI spec` 500	`openapi.yaml` was patched in a fork and the YAML is now invalid	Validate with `swagger-cli validate openapi.yaml` before rebuilding

Where Next

BAAS_REST_API — full PostgREST surface.
AUTH_AND_OAUTH — get a JWT for the Authorize button.
REALTIME_WEBSOCKET — the only endpoint not in the OpenAPI spec (it’s a WebSocket).