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

# Collections

> Manage database collections and schemas

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

<Warning>
  All collection management endpoints require superuser authentication.
</Warning>

## List collections

Retrieve a list of all collections.

```bash theme={null}
GET /api/collections
```

<ParamField query="page" type="number" default="1">
  Page number
</ParamField>

<ParamField query="perPage" type="number" default="30">
  Records per page
</ParamField>

<ParamField query="sort" type="string">
  Sort fields (e.g., `-created,name`)
</ParamField>

<ParamField query="filter" type="string">
  Filter expression (e.g., `type='base'`, `system=true`)
</ParamField>

**Authentication:** Superuser required

### Response

Returns paginated list of collection objects.

<CodeGroup>
  ```bash curl theme={null}
  curl http://127.0.0.1:8090/api/collections \
    -H "Authorization: Bearer SUPERUSER_TOKEN"
  ```

  ```bash With filter theme={null}
  curl "http://127.0.0.1:8090/api/collections?filter=type='auth'" \
    -H "Authorization: Bearer SUPERUSER_TOKEN"
  ```
</CodeGroup>

## View collection

Get a single collection by name or ID.

```bash theme={null}
GET /api/collections/{collection}
```

<ParamField path="collection" type="string" required>
  Collection name or ID
</ParamField>

**Authentication:** Superuser required

### Response

Returns the collection object with full configuration.

<ResponseField name="id" type="string">
  Collection unique identifier
</ResponseField>

<ResponseField name="created" type="string">
  Creation timestamp
</ResponseField>

<ResponseField name="updated" type="string">
  Last update timestamp
</ResponseField>

<ResponseField name="name" type="string">
  Collection name (must be unique)
</ResponseField>

<ResponseField name="type" type="string">
  Collection type: `base`, `auth`, or `view`
</ResponseField>

<ResponseField name="system" type="boolean">
  Whether this is a system collection
</ResponseField>

<ResponseField name="fields" type="array">
  Array of field definitions
</ResponseField>

<ResponseField name="indexes" type="array">
  Database indexes configuration
</ResponseField>

<ResponseField name="listRule" type="string | null">
  API rule for listing records
</ResponseField>

<ResponseField name="viewRule" type="string | null">
  API rule for viewing individual records
</ResponseField>

<ResponseField name="createRule" type="string | null">
  API rule for creating records
</ResponseField>

<ResponseField name="updateRule" type="string | null">
  API rule for updating records
</ResponseField>

<ResponseField name="deleteRule" type="string | null">
  API rule for deleting records
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl http://127.0.0.1:8090/api/collections/posts \
    -H "Authorization: Bearer SUPERUSER_TOKEN"
  ```
</CodeGroup>

## Create collection

Create a new collection.

```bash theme={null}
POST /api/collections
```

**Authentication:** Superuser required

### Request body

<ParamField body="name" type="string" required>
  Collection name (alphanumeric and underscores only)
</ParamField>

<ParamField body="type" type="string" required>
  Collection type: `base`, `auth`, or `view`
</ParamField>

<ParamField body="fields" type="array">
  Field definitions
</ParamField>

<ParamField body="indexes" type="array">
  Index definitions
</ParamField>

<ParamField body="listRule" type="string | null">
  List API rule
</ParamField>

<ParamField body="viewRule" type="string | null">
  View API rule
</ParamField>

<ParamField body="createRule" type="string | null">
  Create API rule
</ParamField>

<ParamField body="updateRule" type="string | null">
  Update API rule
</ParamField>

<ParamField body="deleteRule" type="string | null">
  Delete API rule
</ParamField>

### Response

Returns the created collection object (200 OK).

<CodeGroup>
  ```bash Base collection theme={null}
  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"
    }'
  ```

  ```bash Auth collection theme={null}
  curl -X POST http://127.0.0.1:8090/api/collections \
    -H "Authorization: Bearer SUPERUSER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "users",
      "type": "auth",
      "fields": [
        {
          "name": "name",
          "type": "text"
        }
      ]
    }'
  ```
</CodeGroup>

## Update collection

Update an existing collection.

```bash theme={null}
PATCH /api/collections/{collection}
```

<ParamField path="collection" type="string" required>
  Collection name or ID to update
</ParamField>

**Authentication:** Superuser required

### Request body

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

### Response

Returns the updated collection object (200 OK).

<CodeGroup>
  ```bash Update rules theme={null}
  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"
    }'
  ```

  ```bash Add field theme={null}
  curl -X PATCH http://127.0.0.1:8090/api/collections/posts \
    -H "Authorization: Bearer SUPERUSER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "fields": [
        {
          "name": "title",
          "type": "text",
          "required": true
        },
        {
          "name": "featured",
          "type": "bool"
        }
      ]
    }'
  ```
</CodeGroup>

<Warning>
  Modifying collection schema may cause data loss. Always backup before making structural changes.
</Warning>

## Delete collection

Delete a collection and all its records.

```bash theme={null}
DELETE /api/collections/{collection}
```

<ParamField path="collection" type="string" required>
  Collection name or ID to delete
</ParamField>

**Authentication:** Superuser required

### Response

Returns 204 No Content on success.

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE http://127.0.0.1:8090/api/collections/posts \
    -H "Authorization: Bearer SUPERUSER_TOKEN"
  ```
</CodeGroup>

<Warning>
  Deleting a collection permanently removes all its records and cannot be undone. Collections with references from other collections cannot be deleted.
</Warning>

## Truncate collection

Delete all records from a collection without deleting the collection itself.

```bash theme={null}
DELETE /api/collections/{collection}/truncate
```

<ParamField path="collection" type="string" required>
  Collection name or ID to truncate
</ParamField>

**Authentication:** Superuser required

### Response

Returns 204 No Content on success.

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE http://127.0.0.1:8090/api/collections/posts/truncate \
    -H "Authorization: Bearer SUPERUSER_TOKEN"
  ```
</CodeGroup>

<Note>
  View collections cannot be truncated since they don't store their own records.
</Note>

## Import collections

Bulk import/update collections from JSON.

```bash theme={null}
PUT /api/collections/import
```

**Authentication:** Superuser required

### Request body

<ParamField body="collections" type="array" required>
  Array of collection objects to import
</ParamField>

<ParamField body="deleteMissing" type="boolean" default="false">
  Whether to delete collections not present in the import
</ParamField>

### Response

Returns 204 No Content on success.

<CodeGroup>
  ```bash curl theme={null}
  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
    }'
  ```
</CodeGroup>

## Get collection scaffolds

Get empty collection templates for each type.

```bash theme={null}
GET /api/collections/meta/scaffolds
```

**Authentication:** Superuser required

### Response

Returns scaffold objects for `base`, `auth`, and `view` collection types.

<CodeGroup>
  ```bash curl theme={null}
  curl http://127.0.0.1:8090/api/collections/meta/scaffolds \
    -H "Authorization: Bearer SUPERUSER_TOKEN"
  ```
</CodeGroup>

## Collection types

### Base collection

Standard collection for storing records.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "name": "posts_view",
  "type": "view",
  "options": {
    "query": "SELECT id, title, created FROM posts WHERE status = 'published'"
  }
}
```

<Note>
  View collections are read-only. Create, update, and delete operations are not supported.
</Note>

## 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:

<ParamField name="listRule" type="string | null">
  Controls who can list records. `null` = superusers only, `""` = everyone
</ParamField>

<ParamField name="viewRule" type="string | null">
  Controls who can view individual records
</ParamField>

<ParamField name="createRule" type="string | null">
  Controls who can create records
</ParamField>

<ParamField name="updateRule" type="string | null">
  Controls who can update records
</ParamField>

<ParamField name="deleteRule" type="string | null">
  Controls who can delete records
</ParamField>

### Rule examples

```javascript theme={null}
// 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"
```