davila7/PocketBase API Rules

PocketBase API Rules & Filter Expressions

Rule Types

Each collection has 5 rule types. Each rule is a filter expression that must evaluate to true for the request to proceed.

| Rule | Controls | Locked = | Empty string = | |------|----------|----------|----------------| | List | GET /api/collections/{name}/records | superusers only | everyone can list | | View | GET /api/collections/{name}/records/{id} | superusers only | everyone can view | | Create | POST /api/collections/{name}/records | superusers only | everyone can create | | Update | PATCH /api/collections/{name}/records/{id} | superusers only | everyone can update | | Delete | DELETE /api/collections/{name}/records/{id} | superusers only | everyone can delete |

Critical: null/locked means only superusers can perform the action (regular users and guests are denied). Empty string "" means EVERYONE including guests. Superusers always bypass API rules entirely — see below.

Superuser Bypass

Superusers (formerly admins) always bypass API rules. Rules only apply to regular auth records and guests.

Filter Syntax

Operators

| Operator | Meaning | Example | |----------|---------|---------| | = | Equal | status = "active" | | != | Not equal | status != "draft" | | > | Greater than | count > 5 | | >= | Greater or equal | count >= 5 | | < | Less than | count < 10 | | <= | Less or equal | count <= 10 | | ~ | LIKE (contains) | title ~ "hello" | | !~ | NOT LIKE | title !~ "spam" | | ?= | Any/has (array contains) | tags ?= "TAG_ID" | | ?!= | None (array not contains) | tags ?!= "TAG_ID" | | ?> | Any greater than | scores ?> 90 | | ?>= | Any greater or equal | scores ?>= 90 | | ?< | Any less than | scores ?< 10 | | ?<= | Any less or equal | scores ?<= 10 | | ?~ | Any LIKE | emails ?~ "@gmail.com" | | ?!~ | Any NOT LIKE | emails ?!~ "@test.com" |

Critical: use ?= (not =) for multi-valued fields (multi-select, multi-relation, multi-file). = checks the raw JSON string, ?= checks individual values.

Logical Operators

status = "active" && author = @request.auth.id
status = "active" || status = "featured"

Parentheses for grouping: (a = 1 || b = 2) && c = 3

Values

• Strings: "value" or 'value'
• Numbers: 123, 45.67
• Booleans: true, false
• null — empty/missing value
• Identifiers: field names, macros

Request Macros (@request.*)

Access the current request context in rules:

| Macro | Type | Description | |-------|------|-------------| | @request.auth.id | string | Current auth record ID (empty if guest) | | @request.auth.email | string | Current auth record email | | @request.auth.verified | bool | Whether email is verified | | @request.auth.collectionId | string | Auth collection ID | | @request.auth.collectionName | string | Auth collection name | | @request.auth.* | any | Any field from the auth record | | @request.body.fieldName | any | Field value from request body | | @request.query.paramName | string | URL query parameter | | @request.headers.name | string | Request header (lowercase key) | | @request.method | string | HTTP method (GET/POST/PATCH/DELETE) |

Auth record relations

You can traverse relations on the auth record:

@request.auth.team.owner = @request.auth.id

Collection Macros (@collection.*)

Cross-collection lookups without explicit joins:

@collection.memberships.user ?= @request.auth.id &&
@collection.memberships.team ?= team

This checks if a record exists in the memberships collection where the user matches the current auth user and the team matches the current record's team field.

Note: @collection.* performs an implicit EXISTS subquery. It's powerful but can be slow on large datasets — add indexes.

Field Modifiers

Use in create/update rules to validate specific field behaviors:

| Modifier | Works on | Description | |----------|----------|-------------| | :isset | @request.body.* | True if the field was sent in the request (even if empty) | | :changed | record field | True if the field value differs from current stored value (update only) | | :length | string/array | Returns the length | | :each | array | Applies the condition to each element | | :lower | string | Lowercased value |

Examples

// Only allow changing status if user is owner
status:changed = false || author = @request.auth.id

// Prevent setting role on create
@request.body.role:isset = false

// Require at least 2 tags
@request.body.tags:length >= 2

// Check each tag is from allowed list
@request.body.tags:each ?= @collection.allowed_tags.id

Datetime Macros

| Macro | Example output | |-------|----------------| | @now | 2024-01-15 10:30:00.000Z | | @second | 2024-01-15 10:30:00.000Z | | @minute | 2024-01-15 10:30:00.000Z | | @hour | 2024-01-15 10:00:00.000Z | | @day | 2024-01-15 00:00:00.000Z | | @month | 2024-01-01 00:00:00.000Z | | @year | 2024-01-01 00:00:00.000Z | | @todayStart | 2024-01-15 00:00:00.000Z | | @todayEnd | 2024-01-15 23:59:59.999Z | | @monthStart | 2024-01-01 00:00:00.000Z | | @monthEnd | 2024-01-31 23:59:59.999Z | | @yearStart | 2024-01-01 00:00:00.000Z | | @yearEnd | 2024-12-31 23:59:59.999Z |

Arithmetic: @now - 7d, @now + 1h, @now - 30m

geoDistance()

For location-based filtering:

geoDistance(lat, lon, 40.7128, -74.0060) <= 10000

Arguments: geoDistance(latField, lonField, targetLat, targetLon) — returns meters.

Common Patterns

Owner-only access

// View/Update/Delete rule:
author = @request.auth.id

Authenticated users only

@request.auth.id != ""

Verified users only

@request.auth.verified = true

Role-based access

@request.auth.role = "admin" || author = @request.auth.id

Team membership

@collection.team_members.user ?= @request.auth.id &&
@collection.team_members.team ?= team

Public read, owner write

// List/View: ""  (empty = everyone)
// Create: @request.auth.id != ""
// Update/Delete: author = @request.auth.id

Prevent field modification

// Update rule: prevent changing `owner` after creation
owner:changed = false

Time-limited access

expires > @now