HTTP API

ParticleDB exposes a lightweight HTTP surface on the same port as the built-in status page. The current server implements JSON SQL execution, KV helpers, health endpoints, Prometheus metrics, and SSE streaming for incremental results.

Base URL

http://localhost:8080

Configure it with:

particledb start --http-addr 0.0.0.0:8080

What Is Actually Implemented

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	Return server name/version metadata
/health	GET	Legacy 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

There is no /query, /bulk, or /tables/:name route in the current server.

SQL

POST /v1/sql

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

Response:

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

The server also accepts a plain-text body if you want to post raw SQL:

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

DDL / DML examples

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

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

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

Parameter handling

The HTTP handler currently executes the sql string directly. It does not bind a separate JSON params array the way the PG wire or gRPC clients do. For HTTP calls today, send the final SQL text you want executed.

Streaming SQL

POST /v1/sql/stream

The server can stream incremental results as Server-Sent Events (SSE).

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

The stream emits event: frames such as:

event: row
data: {"id":1,"name":"signup"}

event: done
data: {"full_text":"...","elapsed_ms":1.2}

Use this transport today for browser-friendly incremental results. The repo contains WebSocket protocol definitions, but the default HTTP server currently exposes SSE, not a live WebSocket upgrade endpoint.

Tables

GET /v1/tables

curl http://localhost:8080/v1/tables

Response:

{
  "tables": ["events", "products"]
}

The current route returns table names only.

KV Helpers

The KV endpoints are simple HTTP wrappers over SQL. They assume a table with a key column and a value column already exists.

Create one:

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

POST /v1/kv/set

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

{
  "ok": true
}

POST /v1/kv/get

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

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

If the key is missing, the server returns 404 with an error field.

POST /v1/kv/delete

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

{
  "ok": true
}

Health and Metrics

GET /health

curl http://localhost:8080/health

Response:

OK

GET /health/live

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

GET /health/ready

{
  "status": "ready",
  "tables_loaded": 3,
  "connections_active": 1,
  "connections_max": 100,
  "connections_available": 99
}

GET /health/deep

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

GET /metrics

curl http://localhost:9090/metrics

By default metrics are served from the dedicated metrics port, not the main HTTP port:

particledb start --metrics-port 9090

Version

GET /v1/version

curl http://localhost:8080/v1/version

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

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

It also answers generic OPTIONS requests with 204 No Content.

Security Notes

• The built-in HTTP server is plain HTTP today. Terminate TLS at your reverse proxy or ingress if you need HTTPS.
• The current /v1/* routes do not perform the PG/gRPC-style username/password auth flow. For production, put the HTTP port behind your normal network perimeter, reverse proxy, or API gateway.

Next Steps

• PostgreSQL Wire Protocol — Primary SQL interface for applications and ORMs
• gRPC — Typed RPC interface with protobuf messages
• TLS / Security — PG/gRPC/Redis TLS details and HTTP deployment notes