# HTTP API

JSON SQL, KV, health, and streaming endpoints on the HTTP server.

Source: https://particledb.ai/connectivity/http-api/

ParticleDB serves a lightweight HTTP API on port `7173`, the ParticleDB port, next to a small HTML index page at `/`: run SQL and get JSON back, stream results as Server-Sent Events, read and write simple key-value tables, and probe health. Use it from `curl`, `fetch`, or any HTTP client.

## Base URL

```text
http://localhost:7173
```

Configure it with:

```bash
particledb start --http-addr 0.0.0.0:7173
```

Use the HTTP address for these requests. SQL drivers and other clients have separate connection addresses. See [connection addresses](/installation/ports/).

## Endpoints

| Path | Method | Purpose |
|---|---|---|
| `/v1/sql` | `POST` | Execute one SQL statement and return JSON rows |
| `/v1/sql/stream` | `POST` | Stream SQL results as Server-Sent Events |
| `/v1/tables` | `GET` | List public tables |
| `/v1/kv/get` | `POST` | Read a single KV row by key |
| `/v1/kv/set` | `POST` | Upsert a KV row |
| `/v1/kv/delete` | `POST` | Delete a KV row |
| `/v1/version` | `GET` | Fixed name/protocol metadata (not the server release) |
| `/health` | `GET` | Plain-text health check (`OK`) |
| `/health/live` | `GET` | Liveness probe JSON |
| `/health/ready` | `GET` | Readiness probe JSON |
| `/health/deep` | `GET` | Deep health JSON |
| `/metrics` | `GET` | Prometheus text metrics; see [Monitoring](/operations/monitoring/) |

When authentication is enabled, every `/v1/*` endpoint except `/v1/version`
requires credentials. See [Authentication](#authentication). The `/health*`
endpoints never do.

## SQL

### `POST /v1/sql`

```bash
curl -X POST http://localhost:7173/v1/sql \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT 1 AS ok"}'
```

Response:

```json
{
  "rows": [
    { "ok": 1 }
  ],
  "row_count": 1,
  "columns": ["ok"],
  "notices": []
}
```

`notices` carries any warnings the statement produced. A statement that fails
returns `400` with an `error` field, for example
`{"error":"table not found: nosuch"}`.

Each request runs **one** statement. A body with several statements
(`SELECT 1; SELECT 2`) is refused with `400`.

The server also accepts raw SQL as a plain-text body:

```bash
printf 'SELECT 1 AS ok' | curl -X POST http://localhost:7173/v1/sql --data-binary @-
```

### DDL / DML examples

```bash
curl -X POST http://localhost:7173/v1/sql \
  -H "Content-Type: application/json" \
  -d '{"sql":"CREATE TABLE events (id BIGINT PRIMARY KEY, name TEXT)"}'

curl -X POST http://localhost:7173/v1/sql \
  -H "Content-Type: application/json" \
  -d "{\"sql\":\"INSERT INTO events (id, name) VALUES (1, 'signup')\"}"

curl -X POST http://localhost:7173/v1/sql \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT id, name FROM events"}'
```

DDL answers with a `result` row and DML with an `affected_rows` row:

```json
{"rows":[{"result":"TABLE CREATED"}],"row_count":1,"columns":["result"],"notices":[]}
{"rows":[{"affected_rows":1}],"row_count":1,"columns":["affected_rows"],"notices":[]}
```

### Parameter handling

`POST /v1/sql` binds `$1`-style placeholders from a `params` array, in order. Values are
JSON numbers, strings, booleans or `null`, and are never spliced into the SQL text:

```bash
curl --fail-with-body http://localhost:7173/v1/sql \
  -H 'Content-Type: application/json' \
  -d '{"sql":"SELECT id, title FROM tasks WHERE id = $1","params":[1]}'
```

A request whose `params` count differs from the statement's placeholders is rejected with
status 400, for example `request supplies 0 parameters, but the statement requires 1`.
`POST /v1/sql/stream` binds `params` the same way. A count mismatch there arrives inside
the stream as an `error` event (SQLSTATE `08P01`) followed by `done`.

## Streaming SQL

### `POST /v1/sql/stream`

Streams results as Server-Sent Events (SSE), one event per row.

```bash
curl -N -X POST http://localhost:7173/v1/sql/stream \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT * FROM events"}'
```

The stream emits a `columns` event with each column's name and type, one `row` event
per row, then a `metadata` event and a `done` event:

```text
event: columns
data: {"columns":[{"name":"id","type":"integer"},{"name":"name","type":"text"}]}

event: row
data: {"columns":["id","name"],"values":[1,"signup"]}

event: metadata
data: {"rows_affected":1,"elapsed_ms":0.309}

event: done
data: {}
```

There is no WebSocket endpoint; use SSE for incremental results in the browser.

## Tables

### `GET /v1/tables`

```bash
curl http://localhost:7173/v1/tables
```

Response:

```json
{
  "tables": ["events", "kv_store"]
}
```

Only table names are returned.

## KV Helpers

The KV endpoints read and write a table that has a `key` column and a `value`
column. Create the table first:

```sql
CREATE TABLE kv_store (
  key TEXT PRIMARY KEY,
  value TEXT
);
```

### `POST /v1/kv/set`

```bash
curl -X POST http://localhost:7173/v1/kv/set \
  -H "Content-Type: application/json" \
  -d '{"table":"kv_store","key":"user:1001","value":"{\"name\":\"Alice\"}"}'
```

```json
{
  "ok": true
}
```

### `POST /v1/kv/get`

```bash
curl -X POST http://localhost:7173/v1/kv/get \
  -H "Content-Type: application/json" \
  -d '{"table":"kv_store","key":"user:1001"}'
```

```json
{
  "key": "user:1001",
  "value": "{\"name\":\"Alice\"}"
}
```

If the key is missing, the server returns `404` with an `error` field
(`{"error":"key not found: user:1001"}`).

### `POST /v1/kv/delete`

```bash
curl -X POST http://localhost:7173/v1/kv/delete \
  -H "Content-Type: application/json" \
  -d '{"table":"kv_store","key":"user:1001"}'
```

```json
{
  "ok": true
}
```

## Health and Metrics

### `GET /health`

```bash
curl http://localhost:7173/health
```

Response:

```text
OK
```

### `GET /health/live`

```json
{
  "status": "alive",
  "uptime_seconds": 42
}
```

### `GET /health/ready`

```json
{
  "status": "ready",
  "tables_loaded": 3,
  "connections_active": 1,
  "connections_max": 2000,
  "connections_available": 1999
}
```

### `GET /health/deep`

```json
{
  "status": "healthy",
  "ready": true
}
```

### Metrics

Prometheus metrics are covered on the [Monitoring](/operations/monitoring/) page.

## Version

### `GET /v1/version`

```bash
curl http://localhost:7173/v1/version
```

```json
{
  "name": "ParticleDB",
  "version": "0.1.0",
  "protocol": "pg-wire"
}
```

The `version` field is a fixed value and does not report the server
release. To read the server release, call the gRPC
health method or run `SELECT version()`.

## CORS

The built-in HTTP server responds with permissive CORS headers:

- `Access-Control-Allow-Origin: *`
- `Access-Control-Allow-Methods: GET, POST, OPTIONS`
- `Access-Control-Allow-Headers: Content-Type, authorization`

It also answers generic `OPTIONS` requests with `204 No Content`.

## Authentication

When the server runs with authentication (the default), send a database user's
name and password with HTTP Basic authentication:

```bash
curl -u app_user:app_password -X POST http://localhost:7173/v1/sql \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT 1 AS ok"}'
```

A request without credentials gets `401 Unauthorized`
(`{"error":"authentication required: provide an Authorization header"}`). On
`/v1/sql/stream` the rejection arrives inside the stream instead, as an `error`
event followed by `done`.
Under `--no-auth` or `--auth-method trust`, no credentials are needed.

## Security Notes

- Basic credentials travel in clear text over plain HTTP. Start the server with
  `--tls-cert` / `--tls-key` and port 7173 serves HTTPS only (a dedicated
  health port stays plain HTTP), or put a
  TLS-terminating reverse proxy in front of it. Add
  `--require-tls-for-credentials` to refuse Basic credentials sent without TLS.
- Restrict who can reach port 7173 (`--http-addr 127.0.0.1:7173` binds this HTTP endpoint to loopback only).

## Next Steps

- [SQL client compatibility](/connectivity/pg-wire/). Primary SQL interface for applications and ORMs
- [gRPC](/connectivity/grpc/). Typed RPC interface with protobuf messages
- [TLS / Security](/connectivity/tls/). PG/gRPC/Redis TLS details and HTTP deployment notes

## Related

[Documentation home](/docs/) · [Troubleshooting](/guides/troubleshooting/)
