List Content

Retrieve a paginated list of your store's catalog with powerful filtering, sorting, and response shaping capabilities.

Endpoint

GET /api/v3/content

---

Query Parameters

Pagination

Parameter	Type	Default	Description
per_page	integer	100	Items per page (1-500)
cursor	string	-	Cursor token from links.next or links.prev

Includes

Parameter	Type	Description
include	string	Comma-separated: prices, description, metadata, geographic_restrictions

Fields Selection

Parameter	Type	Description
fields	string	Comma-separated list of fields to return

Sorting

Parameter	Type	Default	Description
sort	string	-published_at	Sort field. Prefix with - for descending

Allowed sort fields: created_at, updated_at

Filters

Parameter	Type	Description
filter[query]	string	Search by title/name
filter[external_id]	string	Exact match by external_id/ISBN-13
filter[id]	integer	Filter by internal ID
filter[external_id]	string	Filter by external ID (ISBN, SKU)

Date Range Filters

Parameter	Type	Format	Description
filter[created_at][from]	datetime	YYYY-MM-DD HH:mm:ss	Content created after this date
filter[created_at][to]	datetime	YYYY-MM-DD HH:mm:ss	Content created before this date
filter[updated_at][from]	datetime	YYYY-MM-DD HH:mm:ss	Content updated after this date
filter[updated_at][to]	datetime	YYYY-MM-DD HH:mm:ss	Content updated before this date

Date Range Rules

• updated_at filter: both from and to must be within the last month
• created_at filter: can point to any past date
• Range between from and to must not exceed 1 month
• Future dates are rejected

---

Response Structure

Core Object

Always present in the response:

{
  "id": 468166,
  "external_id": "9781496822482",
  "name": "Conversations with Donald Hall",
  "slug": "conversations-with-donald-hall",
  "lang": "en",
  "file_type": "epub",
  "cover_url": "https://.../468166.jpg",
  "reader_url": "https://.../read/...",
  "product_url": "https://.../book/...",
  "created_at": "2021-03-19T00:00:00Z",
  "published_at": "2019-09-13T00:00:00Z",
  "license": "retail",
  "free": {
    "enabled": false,
    "until": "2025-12-12T00:00:00Z",
    "require_login": false
  },
  "preview": {
    "enabled": true,
    "require_login": false
  }
}

Optional Includes

Prices Block (include=prices)

{
  "prices": [
    {
      "currency_id": "USD",
      "amount": 9.99
    },
    {
      "currency_id": "EUR",
      "amount": 8.50
    }
  ]
}

Description Block (include=description)

{
  "description": "A comprehensive collection of interviews with Donald Hall..."
}

Metadata Block (include=metadata)

{
  "publisher": ["Vintage"],
  "author": ["Jane Doe"],
  "bisac": [
    { "code": "FIC019000", "label": "Fiction > Literary" },
    { "code": "FIC000000", "label": "Fiction > General" }
  ],
  "keywords": ["fiction", "literary", "contemporary"],
  "metrics": {
    "total_pages": 320,
    "total_words": 85000,
    "total_seconds": 0
  }
}

Geographic Restrictions Block (include=geographic_restrictions)

Indicates which countries can sell or access the content based on territorial rights.

Possible Values:

• null: No restrictions, content is available worldwide
• Object with included and excluded arrays: Territorial rights information

No restrictions (worldwide):

{
  "geographic_restrictions": null
}

Whitelist (available only in specific countries):

{
  "geographic_restrictions": {
    "included": ["AR", "CL", "UY"],
    "excluded": []
  }
}

Blacklist (worldwide except specific countries):

{
  "geographic_restrictions": {
    "included": ["WORLD"],
    "excluded": ["US", "CA"]
  }
}

Response Wrapper

{
  "data": [ /* content items */ ],
  "links": {
    "next": "https://.../content?cursor=abc123&per_page=100",
    "prev": null
  },
  "meta": {
    "has_more": true
  }
}

---

Field Reference

Core Fields

Field	Type	Description
id	integer	Unique issue identifier
external_id	string	ISBN-13 or external reference
name	string	Publication title
slug	string	URL-friendly identifier
lang	string	Language code
file_type	string	Content type: pdf, epub, audio, physical
audience	string	Target audience
cover_url	string	Cover image URL
reader_url	string	Direct reader link
product_url	string	Storefront product page
created_at	string	Issue creation date (ISO 8601)
published_at	string	Publication date (ISO 8601)
license	string	License type: retail, ppu, shared, owner
free	object	Free access information
preview	object	Preview access information

Free Access Object

Field	Type	Description
enabled	boolean	Whether free access is available
until	string	Free access expiration date
require_login	boolean	Whether login is required for free access

Preview Object

Field	Type	Description
enabled	boolean	Whether preview is available
require_login	boolean	Whether login is required for preview

---

Examples

Basic List

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

With Includes

curl -X GET "https://yourstore.publica.la/api/v3/content?include=prices,description" \
  -H "X-User-Token: your-api-token"

Search by Title

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

Search by ISBN

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

Sparse Fieldsets

# Only return id, name, and cover_url
curl -X GET "https://yourstore.publica.la/api/v3/content?fields=id,name,cover_url" \
  -H "X-User-Token: your-api-token"

Selective Fields with Includes

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

Incremental Sync (Updated Content)

# Content updated in the last 7 days
curl -X GET "https://yourstore.publica.la/api/v3/content?filter[updated_at][from]=2024-12-25 00:00:00&filter[updated_at][to]=2024-12-31 23:59:59" \
  -H "X-User-Token: your-api-token"

Filter by Creation Date

curl -X GET "https://yourstore.publica.la/api/v3/content?filter[created_at][from]=2024-01-01 00:00:00&filter[created_at][to]=2024-12-31 23:59:59" \
  -H "X-User-Token: your-api-token"

Sort by Update Date

# Newest updates first
curl -X GET "https://yourstore.publica.la/api/v3/content?sort=-updated_at" \
  -H "X-User-Token: your-api-token"

# Oldest first
curl -X GET "https://yourstore.publica.la/api/v3/content?sort=created_at" \
  -H "X-User-Token: your-api-token"

Get Geographic Restrictions

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

Combined Filters

curl -X GET "https://yourstore.publica.la/api/v3/content?\
filter[created_at][from]=2024-01-01 00:00:00&\
sort=-updated_at&\
include=prices&\
fields=id,name,created_at,updated_at,prices&\
per_page=50" \
  -H "X-User-Token: your-api-token"

Pagination Flow

# First page
curl -X GET "https://yourstore.publica.la/api/v3/content?per_page=100" \
  -H "X-User-Token: your-api-token"

# Response includes:
# "links": { "next": "...?cursor=eyJjcmVhdGVkX2F0IjoiMjAyNC0xMi0wMyAxMDoxMDowNCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" }

# Next page
curl -X GET "https://yourstore.publica.la/api/v3/content?per_page=100&cursor=eyJjcmVhdGVkX2F0..." \
  -H "X-User-Token: your-api-token"

---

Error Handling

Validation Errors (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "filter.unknown_key": ["The selected filter.unknown_key is invalid."],
    "filter.created_at.from": ["The filter.created_at.from field must match the format Y-m-d H:i:s."],
    "per_page": ["The per page must be between 1 and 500."]
  }
}

Invalid Includes (422)

{
  "message": "Requested include(s) are not allowed. Allowed include(s) are: prices, description, metadata, geographic_restrictions"
}

Authentication Errors (401)

{
  "message": "Unauthenticated."
}

---

Best Practices

1. Use per_page wisely - Higher values reduce API calls but increase payload size
2. Always check meta.has_more - Don't assume based on item count
3. Use fields parameter - Reduce payload size by requesting only needed fields
4. Cache cursor tokens - Store the last cursor for resumable syncs
5. Use incremental sync - For regular updates, use updated_at filter instead of fetching everything

---

OpenAPI Specification

Download the machine-readable contract: content_v3.yml.

---

See Also

• Overview - API overview and authentication
• Migration Guide - Upgrading from API v1
• Sandbox - Test environment

---