Data API over HTTP

Every table you create is served as a REST API at /rest/v1/<table>. The TypeScript and Python clients build these requests for you; this page is the reference for the HTTP underneath, for other languages, scripts, curl, and anyone who wants to know exactly what goes over the wire. Your environment’s own, generated reference (with your actual tables, fields and rules) is in Studio’s API Explorer.

Headers

Header	Value	Needed
`apikey`	Your publishable (`pb_pk_…`) or secret (`pb_sk_…`) key	Always
`Authorization`	`Bearer <access token>` of the signed-in person	When acting for a signed-in person
`Content-Type`	`application/json`	On requests with a body

Without a signed-in person, requests are evaluated as anonymous against your access rules. A secret key passes every rule. See Keys and security.

Endpoints

For a table named orders:

Method	Path	Does	Success
`GET`	`/rest/v1/orders`	List records, with filters, sort, pages, search, fields and relations	`200`
`GET`	`/rest/v1/orders/{id}`	Read one record	`200`
`POST`	`/rest/v1/orders`	Create a record	`201` with the record
`PATCH`	`/rest/v1/orders/{id}`	Change the fields you send	`200` with the record
`PUT`	`/rest/v1/orders/{id}`	Accepted, and behaves exactly like `PATCH`	`200` with the record
`DELETE`	`/rest/v1/orders/{id}`	Delete it	`204`, no body
`POST`	`/rest/v1/orders/similar`	Find records by meaning (tables with a vector field)	`200`

Each operation can be switched off for a table, or given its own access rule, in the table’s Access tab. A switched-off operation isn’t served.

List records

curl "$URL/rest/v1/orders?filter[status]=eq.paid&sort=-created_at&per_page=50&page=2" \
  -H "apikey: $PAWABASE_KEY" -H "Authorization: Bearer $ACCESS_TOKEN"

Query parameters

Parameter	Example	Meaning	Default
`filter[<field>]`	`filter[status]=eq.paid`	Filter on a field (see below). Repeat for more fields; all must match.	none
`sort`	`sort=-created_at,title`	Comma-separated fields; `-` for descending	the table’s natural order
`page`	`page=2`	Page number, from 1	1
`per_page`	`per_page=50`	Records per page, 1 to 200	20
`paginate`	`paginate=false`	Return every match in one response, up to 5,000	`true`
`select`	`select=id,status,total`	Only these fields	all readable fields
`expand`	`expand=customer,items`	Include related records by relation name	none
`q`	`q=red mug`	Full-text search over the table’s search fields	none

Filter operators

Write a filter as filter[<field>]=<operator>.<value>. A value with no operator means eq: filter[status]=paid.

Operator	Meaning	Example
`eq`	Equals	`filter[status]=eq.paid`
`neq`	Doesn’t equal	`filter[status]=neq.cancelled`
`gt`, `gte`	Greater than, or equal	`filter[total]=gte.100`
`lt`, `lte`	Less than, or equal	`filter[created_at]=lt.2026-11-01`
`like`	Matches a pattern, case-sensitive; `%` is any run of characters	`filter[title]=like.Mug%`
`ilike`	The same, ignoring case	`filter[email]=ilike.%@example.com`
`in`	One of a comma-separated list	`filter[status]=in.paid,shipped`
`nin`	None of the list	`filter[status]=nin.cancelled,refunded`
`is`	Is `null`, `true` or `false`	`filter[deleted_at]=is.null`
`isnot`	Isn’t `null`, `true` or `false`	`filter[archived]=isnot.true`

Filtering, sorting or selecting a field the table doesn’t have is refused with 400 bad_request, naming the field. URL-encode values that contain &, #, + or spaces.

The response

{
  "data": [
    { "id": "01JD8Z…", "status": "paid", "total": 42.5, "created_at": "2026-11-06T10:02:11+00:00" }
  ],
  "page": 2,
  "per_page": 50,
  "total": 137
}

Field	Meaning
`data`	The records on this page
`page`, `per_page`	The page you got; both `null` with `paginate=false`
`total`	How many records match in all. `null` when a per-row rule is filtering rows after they’re read, because the database count would then be wrong.

With paginate=false, more than 5,000 matches is refused with 400: narrow the filters, or page through.

Search

q searches the fields the table lists as search fields (its list operation’s settings). A table without search fields refuses q with a message saying how to turn it on. See Filter.

Relations

expand includes related records by relation name. Each related record is read under its own table’s rules: if the caller may read the order but not its customer, customer comes back null. See Relations.

Fields that aren’t returned

Write-only fields are never returned. Vector fields are left out unless you ask for them with select=embedding (or vectors=true when reading one record), because they’re thousands of numbers.

Read one record

curl "$URL/rest/v1/orders/01JD8Z…?expand=customer" -H "apikey: $PAWABASE_KEY"

select, expand and vectors work as for lists. A record that doesn’t exist, or that the caller may not read, is 404, so the API never reveals that a hidden record exists.

Create

curl -X POST "$URL/rest/v1/orders" \
  -H "apikey: $PAWABASE_KEY" -H "Authorization: Bearer $ACCESS_TOKEN" -H "content-type: application/json" \
  -d '{"total": 42.5, "status": "pending"}'

Answers 201 with the record as stored, including its id and timestamps. If the table has an owner field and the caller is signed in, it’s filled with their user id. Validation failures are 422, with one entry per field; a duplicate unique value is 409 unique_violation.

Change a record

PATCH changes only the fields you send and answers with the record after the change. PUT is accepted too and does the same: it does not clear fields you leave out. A required field can’t be set to null. The update rule is checked against the record as it is now. And for anyone but a secret key, the fields your update rule reads can’t be changed: if the rule is “the owner may update”, the owner_id field can’t be changed, so nobody can hand a record to someone else (403, naming the field). Change such fields from your server with a secret key, or from a flow.

Delete

DELETE answers 204 with no body. If the rule refuses, a signed-in caller gets 403 and an anonymous caller gets 404.

Find by meaning

POST /rest/v1/<table>/similar takes a text (or a vector), and optionally field, metric, limit and max_distance, and returns the closest records with a distance. It follows the table’s list rule and accepts the same filter[…] parameters. See Vector search.

Events and caching

Successful writes emit <table>.created, .updated and .deleted events and invalidate the table’s cached lists. Lists can be cached when the table’s caching is on.

Errors

Status	When
`400 bad_request`	Unknown field in `filter`, `sort` or `select`; a bad operator value; more than 5,000 matches with `paginate=false`; search on a table without search fields
`401`	The key is missing or invalid, or the operation needs a signed-in person
`403`	The access rule refused, or the key lacks the `data` scope
`404`	No such record, or the caller may not see it; or the table or operation isn’t served
`409 unique_violation`	A unique field already has that value; `details.columns` names it
`422`	The body failed validation, or `constraint_violation` (for example a related record that doesn’t exist)
`429`	A rate limit or plan quota

All error bodies and codes are on Errors.

Versions

/rest/v1 is always your live API. Other API versions are served side by side at /rest/v2 and so on, with the same endpoints and parameters.

Getting started

Define your data

Change safely

Read and write

Protect and shape

Studio tools

Build well

Data API over HTTP

Headers

Endpoints

List records

Query parameters

Filter operators

The response

Search

Relations

Fields that aren’t returned

Read one record

Create

Change a record

Delete

Find by meaning

Events and caching

Errors

Versions

​Headers

​Endpoints

​List records

​Query parameters

​Filter operators

​The response

​Search

​Relations

​Fields that aren’t returned

​Read one record

​Create

​Change a record

​Delete

​Find by meaning

​Events and caching

​Errors

​Versions

Headers

Endpoints

List records

Query parameters

Filter operators

The response

Search

Relations

Fields that aren’t returned

Read one record

Create

Change a record

Delete

Find by meaning

Events and caching

Errors

Versions