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

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

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

<ParamField path="collection" type="string" required>
  The name or ID of the collection
</ParamField>

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

<ParamField query="perPage" type="number" default="30">
  Number of records per page (max 500)
</ParamField>

<ParamField query="sort" type="string">
  Sort order (e.g., `-created,title`). Prefix with `-` for descending order
</ParamField>

<ParamField query="filter" type="string">
  Filter expression (e.g., `status='active' && created>'2023-01-01'`)
</ParamField>

<ParamField query="expand" type="string">
  Comma-separated relation fields to expand
</ParamField>

<ParamField query="fields" type="string">
  Comma-separated fields to return
</ParamField>

**Authentication:** Required if the collection's `listRule` is not empty. Superusers can access all records.

### Response

<ResponseField name="page" type="number">
  Current page number
</ResponseField>

<ResponseField name="perPage" type="number">
  Records per page
</ResponseField>

<ResponseField name="totalItems" type="number">
  Total number of records
</ResponseField>

<ResponseField name="totalPages" type="number">
  Total number of pages
</ResponseField>

<ResponseField name="items" type="array">
  Array of record objects
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl "http://127.0.0.1:8090/api/collections/posts/records?page=1&perPage=20&sort=-created"
  ```

  ```bash With filter theme={null}
  curl "http://127.0.0.1:8090/api/collections/posts/records?filter=status='published'"
  ```

  ```bash With expand theme={null}
  curl "http://127.0.0.1:8090/api/collections/posts/records?expand=author,categories"
  ```
</CodeGroup>

## View record

Retrieve a single record by ID.

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

<ParamField path="collection" type="string" required>
  The name or ID of the collection
</ParamField>

<ParamField path="id" type="string" required>
  The record ID
</ParamField>

<ParamField query="expand" type="string">
  Comma-separated relation fields to expand
</ParamField>

<ParamField query="fields" type="string">
  Comma-separated fields to return
</ParamField>

**Authentication:** Required if the collection's `viewRule` is not empty.

### Response

Returns the record object with all its fields.

<ResponseField name="id" type="string">
  Record ID
</ResponseField>

<ResponseField name="created" type="string">
  Creation timestamp (ISO 8601)
</ResponseField>

<ResponseField name="updated" type="string">
  Last update timestamp (ISO 8601)
</ResponseField>

<ResponseField name="collectionId" type="string">
  ID of the parent collection
</ResponseField>

<ResponseField name="collectionName" type="string">
  Name of the parent collection
</ResponseField>

Additional fields depend on your collection schema.

<CodeGroup>
  ```bash curl theme={null}
  curl http://127.0.0.1:8090/api/collections/posts/records/RECORD_ID
  ```

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

## Create record

Create a new record in a collection.

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

<ParamField path="collection" type="string" required>
  The name or ID of the collection
</ParamField>

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

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

  ```bash With file theme={null}
  curl -X POST http://127.0.0.1:8090/api/collections/posts/records \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -F "title=My post with image" \
    -F "content=Content here" \
    -F "image=@/path/to/image.jpg"
  ```
</CodeGroup>

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

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

<ParamField path="collection" type="string" required>
  The name or ID of the collection
</ParamField>

<ParamField path="id" type="string" required>
  The record ID to update
</ParamField>

**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`

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

  ```bash Array modifiers theme={null}
  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 '{
      "tags+": ["new-tag"],
      "tags-": ["old-tag"]
    }'
  ```
</CodeGroup>

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

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

<ParamField path="collection" type="string" required>
  The name or ID of the collection
</ParamField>

<ParamField path="id" type="string" required>
  The record ID to delete
</ParamField>

**Authentication:** Required if the collection's `deleteRule` is not empty.

### Response

Returns 204 No Content on success.

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

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

```bash theme={null}
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):

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

<Note>
  When a rule is `null`, only superusers can perform the action. An empty string `""` allows anyone (including guests).
</Note>

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

```bash theme={null}
# 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