HTTP API

JSON over HTTPS. Everything the console and SDKs do goes through it.

Authentication

Authorization: Bearer <key or token>, or HTTP Basic with the database name and secret from its URL.

Credential	Looks like	Scope
Server admin key	from `propus init`, `/etc/propus/admin-key`	Every database, server endpoints
Database key	the secret in the database's URL, `pk_…`	One database, as admin
Role key	`pk_…`, made with `POST keys`	One database, a role, a tenant and a user
Token	`pt_…`, from `POST tokens`, 30 s to 1 h	The key it came from; dies with it

Database endpoints live under /v1/db/<name>/. A database's own key may leave the name out: /v1/query.

{"error": {"code": "23505", "message": "duplicate key value violates unique constraint …"}}

code is a PostgreSQL SQLSTATE; the HTTP status matches (400, 401, 403, 404, 409, …).

Method	Path	Does
GET	`/v1/health`	Health
GET, POST	`/v1/databases`	List, create (`{"name"}`; the answer holds the key once)
DELETE	`/v1/databases/<name>`	Drop
GET, POST	`/v1/databases/<name>/url`	Its URLs; POST resets the key
GET	`/v1/stats`, `/v1/db/<name>/stats`	Latency, slow queries, engine numbers
GET	`/v1/engines`	Every engine checked now (server admin): overall `status`, and per engine `status` (`ok`, `idle`, `warn`, `error`, `off`), `summary`, `metrics`, `items` per database
GET	`/metrics`	Prometheus

Method	Path	Body / query
POST	`query`	`{"sql", "params": []}`
POST	`transaction`	`{"statements": [{"sql", "params"}]}`, all or nothing
POST	`tx`	Begins an interactive transaction; then `/v1/tx/<id>/query`, `/commit`, `/rollback`
GET	`schema`	Tables, columns, indexes, policies, grants
POST	`verify`	Integrity check
GET, POST	`backups`	List, take
GET	`audit?limit=`	Audit log
GET, POST	`keys`; DELETE `keys/<id>`	Role keys
POST	`tokens`	`{"ttlSeconds"}` short-lived token
GET	`changes?since=&limit=`	The change feed; WebSocket at `/v1/db/<name>/changes/ws?since=&token=`

Method	Path	Does
GET, POST	`streams`	List, create (`{"name", "partitions", "config"}`)
GET, POST, PATCH, DELETE	`streams/<name>`	Read (`?from=&limit=&partition=`), publish, change config, delete
GET	`streams/<name>/offsets`	Offsets per partition
POST	`streams/<name>/compact`, `streams/<name>/trim`	Compaction, trimming
GET, DELETE	`streams/<name>/groups/<group>`	Lag, reset
POST	`streams/<name>/groups/<group>/next`, `/ack`, `/nack`	Consume, acknowledge, retry or dead-letter
GET	`groups`; GET, DELETE `groups/<group>`	Kafka consumer groups
POST	`groups/<group>/join`, `/heartbeat`, `/leave`, `/commit`; GET `/offsets`	Group membership and offsets
WS	`/v1/db/<name>/streams/<name>/ws`	Messages pushed as they arrive

Method	Path	Does
GET, POST	`buckets`	List, create (`{"name", "public"}`)
PATCH, DELETE	`buckets/<bucket>`	Change, delete
GET	`objects/<bucket>?prefix=&delimiter=`	List
GET, HEAD, PUT, DELETE	`objects/<bucket>/<key>`	Object
any	`/s3/…`	The S3 API (SigV4)
GET	`/o/<db>/<bucket>/<key>`	Public buckets, no credentials

Method	Path	Does
GET	`search?q=&table=&limit=`	Ranked hits with highlights
GET, POST	`search/indexes`	Status and lag, index a table (`{"table", "fields", "tenantColumn"}`)
DELETE	`search/indexes/<table>`	Remove
POST	`search/indexes/<table>/rebuild`	Rebuild

Method	Path	Does
POST	`migrations/inspect`	`{"source"}`: what will carry over
GET, POST	`migrations`	List, start (`{"source", "follow", "prefix", "tables"}`)
GET, DELETE	`migrations/<id>`	Progress, remove
POST	`migrations/<id>/cutover`, `/rollback`, `/cancel`	Steps

An admin can send x-propus-run-as with a role, tenant and user to see exactly what that caller would; the console's Run as uses it.