DocsAPI & clients
REST API
The HTTP API every collection gets, with its filters, sorting, paging, related records and errors.
Every collection gets a REST API as soon as it exists. The browser client is a thin layer over it, so anything it does can be done with plain HTTP. To list records:
GET /api/collections/orders/records?filter=total%20%3E%3D%20100&sort=-created_at&perPage=20
Authorization: Bearer eyJ…The answer holds items, page, perPage, totalItems and totalPages.
To sign the request in, send Authorization: Bearer <token>, with the token from sign-in. Without it, the request is anonymous. Either way, the collection’s rules decide what is allowed.
Records
| Method and path | What it does |
|---|---|
GET /api/collections/{name}/records | List records, a page at a time |
POST /api/collections/{name}/records | Create one; answers 201 and the record |
GET /api/collections/{name}/records/{id} | Get one record |
PATCH /api/collections/{name}/records/{id} | Update only the fields given |
DELETE /api/collections/{name}/records/{id} | Delete (to the recycle bin); answers { "bin": … } |
GET /api/collections/{name}/aggregate | Count, sum, average, minimum or maximum, grouped |
A list takes these parameters:
| Parameter | |
|---|---|
filter | status = "open" && priority > 2 (see Filters) |
sort | Fields separated by commas, - for descending: -created_at,title |
page, perPage | Paging |
search | Full-text search in the searchable fields |
asOf | The collection as it stood at a date, if it keeps history: 2026-06-30 |
near, on | Search by meaning: most alike first; on picks the fields |
expand | Related records, embedded: expand=customer,customer.company (see Related records) |
fields | Only these fields in the answer: fields=id,name,expand.org.name |
Add to a number
To add to a number instead of replacing it, follow the field’s name with + or -. This suits likes, stock or a balance: two people adding at the same moment both count, and in a swarm the same holds whichever node they reach.
{ "likes+": 1, "stock-": 2 }curl -X PATCH http://127.0.0.1:8090/api/collections/posts/records/k3j9x2m1 \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "likes+": 1 }'The answer is the record as it is now, with likes one higher than it was.
Filters
Filters are a small expression language compiled to SQL; they never reach the database as raw text. Field names are checked against the collection, and values are always bound parameters.
| Compare | = != > >= < <= |
| Contains, doesn’t contain | ~ !~: title ~ "trip" |
| Starts, ends with | ^= $=: title ^= "Re:", file $= ".pdf" |
| In a list, not in it | status in ("open", "waiting"), status not in ("done") |
| Has the words (full-text) | @@: title @@ "museum trip". Searches the collection’s full-text index. Every word must be found, and a word also matches the start of a longer one. |
| Any of a list field’s values | ?= ?!= ?~: tags ?= "urgent" (a JSON array; a plain value counts as a list of one) |
| Combine | && ||, parentheses, and !(…) to negate a group |
| Values | "text" or 'text', numbers, true, false, null |
status in ("open", "waiting") && priority >= 2 && !(title ~ "test" || tags ?= "draft")An empty text also stands for a value never set, as in PocketBase: parent = "" finds the rows with no parent, empty or null, and parent != "" leaves both out.
Through relations
A dot follows a relation field to a field of the record it points at, up to four relations deep:
customer.company.name = "Acme" && customer.first_name ^= "Li"This compiles to a subquery, not one query per row. Each related collection’s list rule applies as it would to the caller listing it directly: a path through records they can’t list finds nothing, and a path can’t be used to probe fields they can’t see. Paths work in filter for lists, /aggregate and deleteMany.
A path can also start from the records that point at this one. comments_via_post means the comments whose post field is this record, so this finds the posts Ann has commented on:
comments_via_post.author = "ann"Words in related records
@@ works along a path too, to find records by the words in the records they point at. Each collection’s own full-text index is used:
org.name @@ "acme" members whose organisation's name has "acme"
org @@ "warehouse" any searchable field of the organisation
org.country.name @@ "belg" two relations deep
members_via_org.name @@ "bob" organisations with a member called BobTo get each organisation with its members, in the same request, add expand=org:
GET /api/collections/members/records?filter=org.name%20%40%40%20%22acme%22&expand=orgOnly fields the caller may read are searched. A hidden field can’t be searched by name, and searching a whole relation leaves it out.
Ranking
A list with @@ or search= comes back best match first, unless you give a sort. Each row has _scores, one score for each part of the query, named by what it searched, and _score, their sum:
{ "name": "Ana", "_score": 2.1, "_scores": { "search": 1.2, "org.name": 0.9, "org.country.name": null } }A path scores the best of the related records it matched. null means that part found nothing for the row, which can happen with ||. To weigh the parts differently, sort in the browser with _scores. For example, to make the organisation’s name count double:
const { items } = await members.list({ search: "ana", filter: `org.name @@ "acme"` });
items.sort((a, b) => score(b) - score(a));
function score(r) { return (r._scores.search ?? 0) + 2 * (r._scores["org.name"] ?? 0); }With near=, the rows come closest in meaning first. _score is then the closeness, also given as _scores.near, beside the scores of any @@ in the filter and of search=. Using near and search together is hybrid search: the words narrow the rows, and meaning orders them.
Related records
expand embeds the records a relation field points at, under expand, beside the ids. Dotted paths go further, up to four relations deep:
GET /api/collections/orders/records?expand=customer,customer.company{ "id": "…", "total": 90, "customer": "u1",
"expand": { "customer": { "id": "u1", "name": "Lisa", "company": "c4a",
"expand": { "company": { "id": "c4a", "name": "Acme" } } } } }It costs one query per relation, not one per row. Related records go through their own collection’s list rule: one the caller couldn’t list directly is left out, and only its id remains. expand works on a single record too (/records/{id}?expand=customer), and in the client: list({ expand }), getOne(id, { expand }), listAll({ expand }).
The records that point here
comments_via_post embeds, as a list, the comments whose post field is the row. By default, that’s up to 100 each, in the order they were made. To choose which, in what order and how many, give expand as an object instead of paths:
await posts.list({
expand: { author: true, comments_via_post: { sort: "-created_at", limit: 3, filter: "hidden = false", expand: "author" } },
});Each row gets its own: the three newest comments of every post, not three in all. The limit goes up to 1,000. Each list goes through the comments’ own list rule, like any related record.
In a synced list, expanded rows stay current: when a related record changes, the rows showing it are sent again, including when a comment is added or moved to another post.
Choose the fields
fields says which fields come back, at any depth. * means every field at one level:
await members.list({ expand: "org.country", fields: "name,expand.org.name,expand.org.expand.country.name" });
// [{ name: "Ana", expand: { org: { name: "Acme", expand: { country: { name: "Belgium" } } } } }]GET /api/collections/members/records?expand=org&fields=id,name,expand.org.nameThe object form of expand can also take fields for each relation. The record itself still comes back whole:
await members.list({ expand: { org: { fields: "name" } } });Fields are picked after the records are read, so rules and filters can still use the ones you leave out. getOne takes fields too.
Search by meaning
near=museum trips answers the most alike rows first, each with a _score (1 is identical). It compares the searchable fields, or those in on=title,body. Rules and filter apply as usual. See Search by meaning.
const { items } = await sluurp.collection("notes").list({ near: "museum trips" });Count and sum
GET /api/collections/{name}/aggregate takes op (count, sum, avg, min, max), field (except for count) and group (one or more fields), with filter and asOf as for lists:
GET /api/collections/orders/aggregate?op=avg&field=total&group=regionHistory and the recycle bin
For collections that keep history:
| Method and path | |
|---|---|
GET …/records/{id}/history | Every version of a record, newest first, with who and why |
POST …/records/{id}/history/{seq}/restore | Put a version back |
GET /api/collections/{name}/changes?since=N | Every change after sequence N, in order |
To give a reason for any write, send the X-Sluurp-Reason header; it is kept with the version.
Deleted records go to the recycle bin. POST /api/bin/{bin}/restore puts them back, with anything the delete cascaded to.
Files
| Method and path | |
|---|---|
GET /api/files/{collection}/{id}/{field} | Download. For images, ?w=, ?h=, ?fit=, ?format= and ?q= resize and convert |
POST /api/files/{collection}/{id}/{field} | Upload, multipart, with a part named file |
DELETE /api/files/{collection}/{id}/{field} | Delete |
Sign in
| Method and path | |
|---|---|
POST /api/collections/{name}/auth-with-password | { "identity", "password" } → a token and the record |
POST /api/collections/{name}/auth-refresh | Exchange a token for a fresh one |
POST /api/collections/{name}/signup | Make an account, if sign-up is allowed |
POST /api/collections/{name}/request-password-reset | Email a link to reset the password |
OpenAPI
GET /api/openapi.json describes the API as it is now, as an OpenAPI 3.1 document: every collection’s endpoints, with its fields as a schema and its rules written out; signing in; and the app’s own functions, with their method and rule.
It is made from the live schema, so it can’t drift. It is for superusers, since it describes every collection. Point a client generator at it for a typed client in any language; see OpenAPI and client generators.
The admin’s API screen reads it. Pick an endpoint, fill in its parameters and body, and send it as yourself: you see the status, the time and the answer, and can copy the request as curl.
Errors
An error is a status and a message: { "status": 404, "message": "record orders/x not found" }.
| Status | Means |
|---|---|
400 | A bad request |
401 | Not signed in |
403 | Refused by a rule |
404 | Not found, or not visible to you |
409 | A conflict |
429 | Too many requests; try again shortly |
More
- Several writes as one transaction:
POST /api/batch. - Server functions:
GETorPOST /api/fn/{name}(Server functions). - Live data over a WebSocket: Sync.
- Events from outside:
POST /api/events/{name}.