Query, Events, and Overview API

Execute read-only SQL, subscribe to changes, inspect schema history, and read namespace health.

1 min read Updated 2026-07-26 #api#sql#sse#overview

Read-only query

POST /v1/{ns}/query
Content-Type: application/json

Single query:

{
  "sql": "SELECT * FROM contacts WHERE status = ?",
  "params": ["active"]
}

Response:

{"data":[{"id":1,"name":"Ada","status":"active"}]}

Batch:

{
  "statements": [
    {"sql":"SELECT COUNT(*) AS count FROM contacts","params":[]},
    {"sql":"SELECT * FROM contacts WHERE id = ?","params":[1]}
  ]
}

Batch responses use {"results":[{"data":[...]},{"data":[...]}]}. Statements execute sequentially. They are not a write transaction.

SSE subscription

GET /v1/{ns}/subscribe?tables=contacts,orders
Accept: text/event-stream

The server flushes a connection comment immediately and a keepalive comment every 25 seconds. Event names match the mutation action. Data is JSON:

{
  "table": "contacts",
  "action": "update",
  "row": {"id":1,"status":"inactive"},
  "_meta": {"actor":"user-1"},
  "timestamp": "2026-07-26T12:00:00Z"
}

Close the HTTP request to unsubscribe.

Schema changelog

GET /v1/{ns}/changelog?table=contacts&limit=50&offset=0

The endpoint returns a JSON array of schema events. Default limit is 50. Entries contain id, timestamp, action, table, detail, and optional _meta.

Namespace overview

GET /v1/{ns}/overview?window=24h

Windows are 1h, 24h, 7d, and 30d; the default is 24h. The response combines live storage/schema values with bounded telemetry. See Quotas and overview for field semantics.