---
title: "Swagger UI Quickstart"
---

# Swagger UI Quickstart

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

```bash
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](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:

```json
{ "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](https://www.heliosdb.com/docs/nano/guides/tutorials/auth_and_oauth_tutorial/)). Subsequent calls send the header automatically.

---

## 4. Point at One of Your Tables

Create a table from any client:

```bash
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:

```json
{ "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](https://www.heliosdb.com/docs/nano/guides/tutorials/baas_rest_api_tutorial/). 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:

```bash
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 always matches the binary that serves it.

---

## 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](https://www.heliosdb.com/docs/nano/guides/tutorials/baas_rest_api_tutorial/) — full PostgREST surface.
- [AUTH_AND_OAUTH](https://www.heliosdb.com/docs/nano/guides/tutorials/auth_and_oauth_tutorial/) — get a JWT for the **Authorize** button.
- [REALTIME_WEBSOCKET](https://www.heliosdb.com/docs/nano/guides/tutorials/realtime_websocket_tutorial/) — the only endpoint not in the OpenAPI spec (it's a WebSocket).