Data API
Data API
Read and write a branch's tables over one HTTP endpoint with per-branch keys.
Apps read and write a branch's tables over POST /data/v1/query with per-branch keys. The gateway checks the key; the rest service (services/rest) turns the request into SQL and runs it.
Endpoints
| Endpoint | Does |
|---|---|
POST /data/v1/query | Runs one operation (or a batch) from a JSON tree. See Query language. |
GET /data/v1/schema | Describes what the key's role can reach. ?database=<name> picks another served database; the response's databases lists the served databases the key reaches. |
GET /data/v1/types | The generated db.ts (or JSON with format=json) for the key's schema. See Generated types. |
All three take the key in the Authorization: Bearer <key> header. GET /data/v1/schema and GET /data/v1/types need a secret key: a public key gets 401 unauthorized. Requests go to the gateway (http://api.chelabase.localhost:8000 in development).
curl -s http://api.chelabase.localhost:8000/data/v1/query \
-H "Authorization: Bearer $CHELABASE_DATA_KEY" \
-H "Content-Type: application/json" \
-d '{ "v": 1, "op": "select", "from": "orders", "limit": 10 }'The body is limited to 1 MiB. A failed request answers {"error": {"code", "message", "detail"?, "hint"?, "sqlstate"?}}; every status and code is listed once, on Error codes.
Where to go next
- Keys: public and secret keys, roles, rotation and revocation.
- Serving more databases: enable other Postgres databases of a branch.
- Allow-lists: limit a key to some databases.
- Query language: the operations and filters.
- Settings and Limits.
- TypeScript client: a typed SDK over this endpoint.
- How a request flows, and which objects a key can reach.