> ## Documentation Index
> Fetch the complete documentation index at: https://docs.publica.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Content API Overview

Manage your store's digital catalog: list, create, update, and delete content items.

## Features

- **Full CRUD operations** for complete catalog management
- **Bulk operations** for importing up to 50 items at once
- **Audiobook track management** for audio content
- **Cursor-based pagination** for efficient, consistent results across large datasets
- **Response shaping** with `include` and `fields` parameters to control payload size
- **Incremental sync** with `updated_at` filters to fetch only changed content
- **Advanced filtering** by query, external_id, file_type, author, audience, and date ranges
- **Sorting** by creation or update date
- **Flexible ID lookup** using internal or external IDs

---

## Authentication

| Header           | Example         | Description                                                          |
| ---------------- | --------------- | -------------------------------------------------------------------- |
| **X-User-Token** | `api-abc123...` | API token generated in your dashboard. **Header-only for security.** |

All requests **must** be performed over HTTPS.

```bash
curl -X GET "https://yourstore.publica.la/api/v3/content" \
  -H "X-User-Token: api-abc123..." \
  -H "Accept: application/json"
```

---

## API Endpoints

### Content CRUD

| Operation      | Method   | Endpoint                | Description                                        |
| -------------- | -------- | ----------------------- | -------------------------------------------------- |
| List content   | `GET`    | `/api/v3/content`       | Retrieve catalog with filters and pagination       |
| Get content    | `GET`    | `/api/v3/content/{id}`  | Retrieve single content by ID                      |
| Create content | `POST`   | `/api/v3/content`       | Add new content to catalog                         |
| Bulk create    | `POST`   | `/api/v3/content/bulk`  | Create up to 50 items at once                      |
| Bulk share     | `POST`   | `/api/v3/content/share` | Share owned collections with other tenants in bulk |
| Update content | `PUT`    | `/api/v3/content/{id}`  | Modify existing content                            |
| Delete content | `DELETE` | `/api/v3/content/{id}`  | Remove content from catalog                        |

### Audiobook Tracks

| Operation      | Method   | Endpoint                              | Description                     |
| -------------- | -------- | ------------------------------------- | ------------------------------- |
| List tracks    | `GET`    | `/api/v3/content/{id}/tracks`         | Get all tracks for an audiobook |
| Add track      | `POST`   | `/api/v3/content/{id}/tracks`         | Upload a new audio track        |
| Update track   | `PUT`    | `/api/v3/content/{id}/tracks/{track}` | Modify track metadata           |
| Reorder tracks | `PUT`    | `/api/v3/content/{id}/tracks/order`   | Change track order              |
| Delete track   | `DELETE` | `/api/v3/content/{id}/tracks/{track}` | Remove a track                  |

---

## Response Shaping

Control your response payload size and content:

### The `include` Parameter

Request additional data blocks:

```bash
GET /api/v3/content?include=prices,description,metadata
```

| Include                   | Description                                 |
| ------------------------- | ------------------------------------------- |
| `prices`                  | Active prices in all currencies             |
| `description`             | Full content description                    |
| `metadata`                | Publisher, author, BISAC, keywords, metrics |
| `geographic_restrictions` | Territorial availability                    |

### The `fields` Parameter

Trim the response to only the fields you need:

```bash
GET /api/v3/content?fields=id,name,cover_url
```

### Combining Both

```bash
GET /api/v3/content?include=prices&fields=id,name,prices
```

---

## Cursor Pagination

Cursor-based pagination provides efficient, consistent results:

```json
{
  "data": [...],
  "links": {
    "next": "https://yourstore.publica.la/api/v3/content?cursor=eyJjcmVhdGVkX2F0...",
    "prev": null
  },
  "meta": {
    "has_more": true
  }
}
```

### Pagination Workflow

1. Make initial request without `cursor`
2. Store `links.next` token
3. Use `cursor=<token>` for next page
4. Continue until `meta.has_more` is `false`

:::tip Best Practice
Always use `meta.has_more` to detect the end of results, not by counting items.
:::

---

## Quick Start

### List All Content

```bash
curl -X GET "https://yourstore.publica.la/api/v3/content?per_page=100" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

### Search by Title

```bash
curl -X GET "https://yourstore.publica.la/api/v3/content?filter[query]=marketing" \
  -H "X-User-Token: your-api-token"
```

### Get Minimal Response

```bash
curl -X GET "https://yourstore.publica.la/api/v3/content?fields=id,name,cover_url&per_page=50" \
  -H "X-User-Token: your-api-token"
```

---

## Error Handling

### Validation Errors (422)

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "filter.updated_at.from": [
      "The filter.updated_at.from field must match the format Y-m-d H:i:s."
    ]
  }
}
```

### Authentication Errors (401)

```json
{
  "message": "Unauthenticated."
}
```

---

## Rate Limiting

Two limits apply: a per-token burst of **60 requests/minute** and a **daily read quota** of 2,000 reads/token plus 5,000/store (`GET`/`HEAD` only; writes and bulk operations are separate). Exceeding either returns `429 Too Many Requests` with a `Retry-After` header.

Cache responses and sync incrementally with `filter[updated_at]` instead of re-fetching the full catalog each cycle. See the [API Overview](../../rest-api/overview.md#rate-limiting-and-flood-protection) for full details.

---

## Next Steps

- **[List Content](./content-v3-list.md)** - Query and filter catalog
- **[Get Content](./content-v3-get.md)** - Retrieve single items
- **[Create Content](./content-v3-create.md)** - Add new content
- **[Bulk Operations](./content-v3-bulk.md)** - Import multiple items
- **[Update Content](./content-v3-update.md)** - Modify existing content
- **[Delete Content](./content-v3-delete.md)** - Remove content
- **[Audiobook Tracks](./content-v3-tracks.md)** - Manage audio tracks
- **[Content Sharing](./content-v3-sharing.md)** - Share content across tenants
- **[Bulk Share Collections](./content-v3-bulk-share.md)** - Share entire collections with multiple tenants in one call
- **[Migration Guide](./content-v3-migration.md)** - Upgrading from API v1

---

## See Also

- [API Authentication](../../rest-api/overview.md)
- [Orders API](../orders/orders-v3-overview.md) - Manage customer purchases