Records - PocketBase

The Records API provides endpoints for creating, reading, updating, and deleting records in your collections.

List records

Retrieve a paginated list of records from a collection.

GET /api/collections/{collection}/records

collection

string

required

The name or ID of the collection

page

number

default:"1"

Page number

perPage

number

default:"30"

Number of records per page (max 500)

sort

string

Sort order (e.g., -created,title). Prefix with - for descending order

filter

string

Filter expression (e.g., status='active' && created>'2023-01-01')

expand

string

Comma-separated relation fields to expand

fields

string

Comma-separated fields to return

Authentication: Required if the collection’s listRule is not empty. Superusers can access all records.

Response

page

number

Current page number

perPage

number

Records per page

totalItems

number

Total number of records

totalPages

number

Total number of pages

items

array

Array of record objects

curl "http://127.0.0.1:8090/api/collections/posts/records?page=1&perPage=20&sort=-created"

View record

Retrieve a single record by ID.

GET /api/collections/{collection}/records/{id}

collection

string

required

The name or ID of the collection

string

required

The record ID

expand

string

Comma-separated relation fields to expand

fields

string

Comma-separated fields to return

Authentication: Required if the collection’s viewRule is not empty.

Response

Returns the record object with all its fields.

string

Record ID

created

string

Creation timestamp (ISO 8601)

updated

string

Last update timestamp (ISO 8601)

collectionId

string

ID of the parent collection

collectionName

string

Name of the parent collection

Additional fields depend on your collection schema.

curl http://127.0.0.1:8090/api/collections/posts/records/RECORD_ID

Create record

Create a new record in a collection.

POST /api/collections/{collection}/records

collection

string

required

The name or ID of the collection

Authentication: Required if the collection’s createRule is not empty. The rule determines whether the user can create records.

Request body

The request body should contain the field values for the new record. Use multipart/form-data for file uploads.

curl -X POST http://127.0.0.1:8090/api/collections/posts/records \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "title": "My new post",
    "content": "Post content here",
    "status": "draft"
  }'

Response

Returns the created record object (200 OK).

Common errors

Code	Description
400	Validation error or unsupported collection type (views)
403	Insufficient permissions (createRule not satisfied)
404	Collection not found

Update record

Update an existing record.

PATCH /api/collections/{collection}/records/{id}

collection

string

required

The name or ID of the collection

string

required

The record ID to update

Authentication: Required if the collection’s updateRule is not empty.

Request body

Provide only the fields you want to update. Use multipart/form-data for file uploads. Field modifiers:

Append + suffix to add values: tags+
Append - suffix to remove values: tags-
Prefix with + to prepend: +items

curl -X PATCH http://127.0.0.1:8090/api/collections/posts/records/RECORD_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "title": "Updated title",
    "status": "published"
  }'

Response

Returns the updated record object (200 OK).

Common errors

Code	Description
400	Validation error or unsupported collection type
403	Insufficient permissions (updateRule not satisfied)
404	Record or collection not found

Delete record

Delete a record from a collection.

DELETE /api/collections/{collection}/records/{id}

collection

string

required

The name or ID of the collection

string

required

The record ID to delete

Authentication: Required if the collection’s deleteRule is not empty.

Response

Returns 204 No Content on success.

curl -X DELETE http://127.0.0.1:8090/api/collections/posts/records/RECORD_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Common errors

Code	Description
400	Record is part of a required relation reference
403	Insufficient permissions (deleteRule not satisfied)
404	Record or collection not found

Working with files

When creating or updating records with file fields, use multipart/form-data encoding.

Upload files

curl -X POST http://127.0.0.1:8090/api/collections/posts/records \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "title=Post with files" \
  -F "document=@/path/to/file.pdf" \
  -F "images=@/path/to/image1.jpg" \
  -F "images=@/path/to/image2.jpg"

Update files

To replace files, submit new file(s):

curl -X PATCH http://127.0.0.1:8090/api/collections/posts/records/RECORD_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "document=@/path/to/new-file.pdf"

To append files without removing existing ones:

curl -X PATCH http://127.0.0.1:8090/api/collections/posts/records/RECORD_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "images+=@/path/to/new-image.jpg"

To remove specific files:

curl -X PATCH http://127.0.0.1:8090/api/collections/posts/records/RECORD_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "images-": ["existing_filename.jpg"]
  }'

API rules

Each collection has API rules that control access:

listRule - Controls who can list records
viewRule - Controls who can view individual records
createRule - Controls who can create records
updateRule - Controls who can update records
deleteRule - Controls who can delete records

When a rule is null, only superusers can perform the action. An empty string "" allows anyone (including guests).

Rules use a filter expression syntax similar to the filter parameter:

@request.auth.id != "" && @request.auth.id = author

This rule allows authenticated users to only access their own records.

Filter syntax

The filter parameter supports a rich expression syntax:

Operators

=, != - Equality
>, >=, <, <= - Comparison
~ - LIKE operator
!~ - NOT LIKE
?=, ?!= - Array contains/not contains
&&, || - Logical AND/OR

Examples

# Simple equality
filter=status='active'

# Multiple conditions
filter=status='active' && views>100

# Date comparison
filter=created>'2023-01-01'

# Array contains
filter=tags?='featured'

# LIKE pattern
filter=title~'tutorial%'

# Relation field
filter=author.name='John'

Special @request fields

In API rules and filters, you can access request context:

@request.auth.id - ID of the authenticated user
@request.auth.* - Any field from the auth record
@request.method - HTTP method (GET, POST, etc.)
@request.query.* - Query parameters
@request.data.* - Request body data

Response enrichment

All record responses include these system fields:

id - Unique record identifier
created - Creation timestamp
updated - Last update timestamp
collectionId - Parent collection ID
collectionName - Parent collection name

For auth collections, additional fields:

email - User email (respects emailVisibility)
verified - Email verification status
emailVisibility - Whether email is public

​List records

​Response

​View record

​Response

​Create record

​Request body

​Response

​Common errors

​Update record

​Request body

​Response

​Common errors

​Delete record

​Response

​Common errors

​Working with files

​Upload files

​Update files

​API rules

​Filter syntax

​Operators

​Examples

​Special @request fields

​Response enrichment

List records

Response

View record

Response

Create record

Request body

Response

Common errors

Update record

Request body

Response

Common errors

Delete record

Response

Common errors

Working with files

Upload files

Update files

API rules

Filter syntax

Operators

Examples

Special @request fields

Response enrichment