LearnAPI
PgPaw exposes a small HTTP API.
| Method | Path | Purpose |
|---|---|---|
GET |
/healthz |
Check replica status and watermark. |
POST |
/query |
Run one read-only SQL query. |
GET |
/q/{hash}/{version} |
Fetch a cached public snapshot. |
POST |
/query?live=true |
Run a query and stream realtime changes. |
All query requests use JSON:
{
"sql": "select id, email from users where id = 7"
}Health
curl http://127.0.0.1:8080/healthzHealthy:
{ "status": "ok", "watermark": 12345678 }Halted:
{ "status": "halted", "reason": "replication error details" }A halted replica returns HTTP 503.
Error shape
Errors are JSON:
{
"name": "RejectedError",
"message": "only read-only SELECT queries are cacheable; writes and DDL are not supported"
}Status codes
| Status | Meaning |
|---|---|
303 |
Public query accepted; follow Location for
the snapshot.
|
200 |
Private query response, snapshot cursor hit, live stream, or health OK. |
400 |
SQL parse failure or rejected SQL. |
401 |
Missing, malformed, expired, or unverifiable bearer token. |
403 |
Postgres denied the query under the caller's role. |
404 |
Snapshot cursor is unknown or evicted. |
503 |
Replica is halted. |
500 |
Unexpected server error. |