Skip to content
ParticleDB
Release candidateParticleDB 1.1.19-rc.17 is not yet GA or ready for production data.Release status →

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.

http://localhost:7173

Configure it with:

Terminal window
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.

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

When authentication is enabled, every /v1/* endpoint except /v1/version requires credentials. See Authentication. The /health* endpoints never do.

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

Response:

{
"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:

Terminal window
printf 'SELECT 1 AS ok' | curl -X POST http://localhost:7173/v1/sql --data-binary @-
Terminal window
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:

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

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:

Terminal window
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.

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

Terminal window
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:

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.

Terminal window
curl http://localhost:7173/v1/tables

Response:

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

Only table names are returned.

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

CREATE TABLE kv_store (
key TEXT PRIMARY KEY,
value TEXT
);
Terminal window
curl -X POST http://localhost:7173/v1/kv/set \
-H "Content-Type: application/json" \
-d '{"table":"kv_store","key":"user:1001","value":"{\"name\":\"Alice\"}"}'
{
"ok": true
}
Terminal window
curl -X POST http://localhost:7173/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 ({"error":"key not found: user:1001"}).

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

Response:

OK
{
"status": "alive",
"uptime_seconds": 42
}
{
"status": "ready",
"tables_loaded": 3,
"connections_active": 1,
"connections_max": 2000,
"connections_available": 1999
}
{
"status": "healthy",
"ready": true
}

Prometheus metrics are covered on the Monitoring page.

Terminal window
curl http://localhost:7173/v1/version
{
"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().

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.

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

Terminal window
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.

  • 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).

Documentation home · Troubleshooting