Records

Perform CRUD operations on collection records

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

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

id · 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.

id · 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

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.

JSON

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

id · 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

Update fields

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

id · 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

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