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 pathWhat it does
GET /api/collections/{name}/recordsList records, a page at a time
POST /api/collections/{name}/recordsCreate 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}/aggregateCount, sum, average, minimum or maximum, grouped

A list takes these parameters:

Parameter
filterstatus = "open" && priority > 2 (see Filters)
sortFields separated by commas, - for descending: -created_at,title
page, perPagePaging
searchFull-text search in the searchable fields
asOfThe collection as it stood at a date, if it keeps history: 2026-06-30
near, onSearch by meaning: most alike first; on picks the fields
expandRelated records, embedded: expand=customer,customer.company (see Related records)
fieldsOnly 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 itstatus 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"

@@ 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 Bob

To 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=org

Only 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:

app.ts
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.

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:

app.ts
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:

app.ts
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.name

The object form of expand can also take fields for each relation. The record itself still comes back whole:

app.ts
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.

app.ts
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=region

History and the recycle bin

For collections that keep history:

Method and path
GET …/records/{id}/historyEvery version of a record, newest first, with who and why
POST …/records/{id}/history/{seq}/restorePut a version back
GET /api/collections/{name}/changes?since=NEvery 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-refreshExchange a token for a fresh one
POST /api/collections/{name}/signupMake an account, if sign-up is allowed
POST /api/collections/{name}/request-password-resetEmail 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" }.

StatusMeans
400A bad request
401Not signed in
403Refused by a rule
404Not found, or not visible to you
409A conflict
429Too many requests; try again shortly

More

View as Markdown