Collections

Manage database collections and schemas

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

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

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).

Base collection

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).

Update rules

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

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

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

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

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"