Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pocketbase/pocketbase/llms.txt

Use this file to discover all available pages before exploring further.

The Collections API allows superusers to manage database collections, schemas, and configurations. All collection endpoints require superuser authentication.
All collection management endpoints require superuser authentication.

​
List collections

Retrieve a list of all collections. 
GET /api/collections
​
page
number
default:"1"
Page number
​
perPage
number
default:"30"
Records per page
​
sort
string
Sort fields (e.g., -created,name)
​
filter
string
Filter expression (e.g., type='base', system=true)
Authentication: Superuser required

​
Response

Returns paginated list of collection objects. 
curl http://127.0.0.1:8090/api/collections \
  -H "Authorization: Bearer SUPERUSER_TOKEN"

​
View collection

Get a single collection by name or ID. 
GET /api/collections/{collection}
​
collection
string
required
Collection name or ID
Authentication: Superuser required

​
Response

Returns the collection object with full configuration.
​
id
string
Collection unique identifier
​
created
string
Creation timestamp
​
updated
string
Last update timestamp
​
name
string
Collection name (must be unique)
​
type
string
Collection type: base, auth, or view
​
system
boolean
Whether this is a system collection
​
fields
array
Array of field definitions
​
indexes
array
Database indexes configuration
​
listRule
string | null
API rule for listing records
​
viewRule
string | null
API rule for viewing individual records
​
createRule
string | null
API rule for creating records
​
updateRule
string | null
API rule for updating records
​
deleteRule
string | null
API rule for deleting records
curl http://127.0.0.1:8090/api/collections/posts \
  -H "Authorization: Bearer SUPERUSER_TOKEN"

​
Create collection

Create a new collection. 
POST /api/collections
Authentication: Superuser required

​
Request body

​
name
string
required
Collection name (alphanumeric and underscores only)
​
type
string
required
Collection type: base, auth, or view
​
fields
array
Field definitions
​
indexes
array
Index definitions
​
listRule
string | null
List API rule
​
viewRule
string | null
View API rule
​
createRule
string | null
Create API rule
​
updateRule
string | null
Update API rule
​
deleteRule
string | null
Delete API rule

​
Response

Returns the created collection object (200 OK). 
curl -X POST http://127.0.0.1:8090/api/collections \
  -H "Authorization: Bearer SUPERUSER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "posts",
    "type": "base",
    "fields": [
      {
        "name": "title",
        "type": "text",
        "required": true
      },
      {
        "name": "content",
        "type": "editor"
      }
    ],
    "listRule": "",
    "viewRule": "",
    "createRule": "@request.auth.id != '""'",
    "updateRule": "@request.auth.id = author",
    "deleteRule": "@request.auth.id = author"
  }'

​
Update collection

Update an existing collection. 
PATCH /api/collections/{collection}
​
collection
string
required
Collection name or ID to update
Authentication: Superuser required

​
Request body

Same as create collection. Only include fields you want to update.

​
Response

Returns the updated collection object (200 OK). 
curl -X PATCH http://127.0.0.1:8090/api/collections/posts \
  -H "Authorization: Bearer SUPERUSER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "listRule": "status = '"published'" || @request.auth.id = author",
    "viewRule": "status = '"published'" || @request.auth.id = author"
  }'
Modifying collection schema may cause data loss. Always backup before making structural changes.

​
Delete collection

Delete a collection and all its records. 
DELETE /api/collections/{collection}
​
collection
string
required
Collection name or ID to delete
Authentication: Superuser required

​
Response

Returns 204 No Content on success. 
curl -X DELETE http://127.0.0.1:8090/api/collections/posts \
  -H "Authorization: Bearer SUPERUSER_TOKEN"
Deleting a collection permanently removes all its records and cannot be undone. Collections with references from other collections cannot be deleted.

​
Truncate collection

Delete all records from a collection without deleting the collection itself. 
DELETE /api/collections/{collection}/truncate
​
collection
string
required
Collection name or ID to truncate
Authentication: Superuser required

​
Response

Returns 204 No Content on success. 
curl -X DELETE http://127.0.0.1:8090/api/collections/posts/truncate \
  -H "Authorization: Bearer SUPERUSER_TOKEN"
View collections cannot be truncated since they don’t store their own records.

​
Import collections

Bulk import/update collections from JSON. 
PUT /api/collections/import
Authentication: Superuser required

​
Request body

​
collections
array
required
Array of collection objects to import
​
deleteMissing
boolean
default:"false"
Whether to delete collections not present in the import

​
Response

Returns 204 No Content on success. 
curl -X PUT http://127.0.0.1:8090/api/collections/import \
  -H "Authorization: Bearer SUPERUSER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collections": [
      {
        "name": "posts",
        "type": "base",
        "fields": [...]
      },
      {
        "name": "users",
        "type": "auth",
        "fields": [...]
      }
    ],
    "deleteMissing": false
  }'

​
Get collection scaffolds

Get empty collection templates for each type. 
GET /api/collections/meta/scaffolds
Authentication: Superuser required

​
Response

Returns scaffold objects for base, auth, and view collection types. 
curl http://127.0.0.1:8090/api/collections/meta/scaffolds \
  -H "Authorization: Bearer SUPERUSER_TOKEN"

​
Collection types

​
Base collection

Standard collection for storing records. 
{
  "name": "posts",
  "type": "base",
  "fields": [
    {"name": "title", "type": "text", "required": true},
    {"name": "content", "type": "editor"}
  ]
}

​
Auth collection

Collection for user authentication with built-in auth fields. 
{
  "name": "users",
  "type": "auth",
  "fields": [
    {"name": "name", "type": "text"}
  ]
}
Auth collections automatically include:
  • email - User email address
  • verified - Email verification status
  • emailVisibility - Whether email is publicly visible
  • password - Hashed password

​
View collection

Virtual collection based on SQL query. 
{
  "name": "posts_view",
  "type": "view",
  "options": {
    "query": "SELECT id, title, created FROM posts WHERE status = 'published'"
  }
}
View collections are read-only. Create, update, and delete operations are not supported.

​
Field types

Supported field types:
  • text - Single line text
  • editor - Rich text editor
  • number - Numeric value
  • bool - Boolean (true/false)
  • email - Email address
  • url - URL
  • date - Date only
  • select - Single select dropdown
  • json - JSON data
  • file - File upload
  • relation - Relation to another collection
  • autodate - Auto-updated timestamp

​
API rules

API rules control record access:

​
Rule examples

// Anyone can read, only auth users can create
listRule: ""
viewRule: ""
createRule: "@request.auth.id != ''"

// Only owners can update/delete
updateRule: "@request.auth.id = author"
deleteRule: "@request.auth.id = author"

// Admin or owner
updateRule: "@request.auth.role = 'admin' || @request.auth.id = author"

Build docs developers (and LLMs) love

Get started for freeTalk to us