Content API v3

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

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 100 items at once
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:

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:

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

Combining Both

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

---

Cursor Pagination

Cursor-based pagination provides efficient, consistent results:

{
  "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

Best Practice

Always use meta.has_more to detect the end of results, not by counting items.

---

Quick Start

List All Content

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

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

Get Minimal Response

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)

{
  "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)

{
  "message": "Unauthenticated."
}

---

Next Steps

• List Content - Query and filter catalog
• Get Content - Retrieve single items
• Create Content - Add new content
• Bulk Operations - Import multiple items
• Update Content - Modify existing content
• Delete Content - Remove content
• Audiobook Tracks - Manage audio tracks
• Content Sharing - Share content across tenants
• Migration Guide - Upgrading from API v1

---

See Also

• API Authentication
• Orders API v3 - Manage customer purchases
• Content API v1 (Deprecated)