Collections API reference

This reference covers the public collection-management API at /api/collections. These operations require superuser authentication. A collection is a schema-backed data container; changes can alter validation, access rules, indexes, and stored data.

Request conventions

Send JSON request bodies with Content-Type: application/json unless the operation accepts another format. Authenticate as a superuser. Use a collection ID or name in {collection}. Successful responses return JSON; malformed input returns 400, missing resources return 404, and missing superuser authorization returns 403.

List collections

GET /api/collections returns a paginated collection result. The implementation supports the query fields id, created, updated, name, system, and type for list queries.

curl --request GET \
  --url http://127.0.0.1:8090/api/collections?page=1&perPage=30&filter=name~'posts'&sort=-created

{ "page": 1, "perPage": 30, "totalItems": 1, "totalPages": 1, "items": [] }

Create a collection

POST /api/collections creates a collection from a type and name, then applies the submitted schema and rules. Use base, view, or auth as the collection type only when that type is appropriate for your model.

curl --request POST \
  --url http://127.0.0.1:8090/api/collections \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "base",
  "name": "posts",
  "fields": [
    {
      "name": "title",
      "type": "text"
    }
  ],
  "listRule": "@request.auth.id != ''",
  "viewRule": "@request.auth.id != ''",
  "createRule": "@request.auth.id != ''",
  "updateRule": "@request.auth.id != ''",
  "deleteRule": "@request.auth.id != ''"
}'

{ "id": "COLLECTION_ID", "name": "posts", "type": "base" }

View, update, and delete a collection

GET /api/collections/{collection} returns a collection. PATCH applies a schema or rule change. DELETE removes the collection and its records, so confirm the target and back up data before using it.

curl --request GET \
  --url http://127.0.0.1:8090/api/collections/posts

{ "id": "COLLECTION_ID", "name": "posts", "type": "base", "fields": [] }

curl --request PATCH \
  --url http://127.0.0.1:8090/api/collections/posts \
  --header 'Content-Type: application/json' \
  --data '{
  "fields": [
    {
      "name": "title",
      "type": "text"
    }
  ],
  "listRule": "@request.auth.id != ''",
  "viewRule": "@request.auth.id != ''",
  "createRule": "@request.auth.id != ''",
  "updateRule": "@request.auth.id != ''",
  "deleteRule": "@request.auth.id != ''"
}'

{ "id": "COLLECTION_ID", "name": "posts", "type": "base" }

curl --request DELETE \
  --url http://127.0.0.1:8090/api/collections/posts

{}

Truncate records

DELETE /api/collections/{collection}/truncate removes every record in a collection while retaining the collection definition. Treat this as destructive and verify the collection name before sending the request.

curl --request DELETE \
  --url http://127.0.0.1:8090/api/collections/posts/truncate

{}

Import collections

PUT /api/collections/import imports collection definitions. Review the complete payload and take a backup first: importing definitions can create, update, or remove schema and rule configuration depending on the submitted data.

curl --request PUT \
  --url http://127.0.0.1:8090/api/collections/import \
  --header 'Content-Type: application/json' \
  --data '{
  "collections": [
    {
      "name": "posts",
      "type": "base",
      "fields": []
    }
  ],
  "deleteMissing": false
}'

{ "collections": [] }

Metadata endpoints

GET /api/collections/meta/scaffolds returns collection scaffolds. GET /api/collections/meta/oauth2-providers discovers OAuth provider metadata. POST /api/collections/meta/dry-run-view evaluates a view definition without saving it. The OAuth metadata and dry-run endpoints are marked experimental in the server route registration; avoid making them a long-term compatibility dependency without testing the target release.

curl --request GET \
  --url http://127.0.0.1:8090/api/collections/meta/scaffolds

{ "scaffolds": [] }

curl --request GET \
  --url http://127.0.0.1:8090/api/collections/meta/oauth2-providers

{ "providers": [] }

curl --request POST \
  --url http://127.0.0.1:8090/api/collections/meta/dry-run-view \
  --header 'Content-Type: application/json' \
  --data '{
  "collection": "\"name\":\"posts\",\"type\":\"view\",\"fields\":[]"
}'

{ "fields": [] }

Related tasks

Use collections and data modeling before creating a schema, and review API rules and filters before exposing records. For record operations, see Records API reference.