The REST API: query your data over HTTPS

Every project has an HTTPS address, https://<your-project>.pgbhub.app. Anything the SDKs do goes through the endpoints on that address, so you can use them from any language that can send an HTTP request.

Keys

Send a project key in the Authorization header:

Authorization: Bearer pgb_sec_...

• A secret key (pgb_sec_...) has full access to your data. Use it only on a server.
• A publishable key (pgb_pub_...) is safe to ship in an app. Requests made with it are limited by your row-level security policies. Add the signed-in user's token in an X-PGB-User-Token header so policies can tell users apart. See Protect rows with row-level security.

Create and manage keys in the Console: see API keys.

Table endpoints

Table calls are POST requests with a JSON body.

curl -X POST https://my-project.pgbhub.app/v1/data/find \
  -H "Authorization: Bearer pgb_sec_..." -H "Content-Type: application/json" \
  -d '{"table": "users", "filter": {"role": "admin"}, "limit": 10, "orderBy": "created_at", "order": "DESC"}'

Endpoint	Does
POST /v1/data/find	Reads rows. filter matches on equal values, limit is at most 1000 (default 100), plus offset, orderBy and order
POST /v1/data/insert	Inserts a row
POST /v1/data/update	Updates rows that match a filter
POST /v1/data/delete	Deletes rows that match a filter

The response to find is {"rows": [...], "count": n}.

Run SQL

POST /sql runs a parameterised statement:

curl -X POST https://my-project.pgbhub.app/sql \
  -H "Authorization: Bearer pgb_sec_..." -H "Content-Type: application/json" \
  -d '{"sql": "SELECT id, name FROM users WHERE email = $1", "params": ["[email protected]"]}'

The response has rows, row_count and columns. Always pass values in params instead of building the SQL string yourself.

Call actions

curl -X POST https://my-project.pgbhub.app/v1/actions/invoke \
  -H "Authorization: Bearer pgb_sec_..." -H "Content-Type: application/json" \
  -d '{"action": "saveUser", "params": {"email": "[email protected]"}, "dry_run": false}'

dry_run: true runs the action and rolls it back, returning a preview. See Actions.

Other endpoints

Area	Address
Authentication	/auth/signup, /auth/login, /auth/user, /auth/refresh and more
Storage	/storage/...
Functions	/functions/<name>
Mail	/mail/send
Schema description	GET /schema.json

The /schema.json document lists your tables, columns, relationships and actions, and is what type generation reads.

Errors

Errors are JSON with a message. Common statuses: 400 for a bad request, 401 for a missing or wrong key, 403 for a key that is not allowed to do that, 404 for something that does not exist, 429 for too many requests (with a Retry-After header) and 5xx for a problem on the platform's side.

Good to know

• Retry reads after network errors, 429, 502, 503 and 504. Do not blindly retry writes, because repeating one can repeat its effect.
• Browsers can call authentication, storage and mail endpoints directly, but keep secret keys out of the browser.