Library
Endpoints for browsing the content library within a specific tenant. All library endpoints use single-tenant mode and require the X-Farfalla-Tenant-Id header.
List Library Sections
GET /api/v2/library
Returns the library shelves (sliders) for the current tenant, including continue reading, latest issues, and taxonomy-based sections.
Request:
curl "https://app.publica.la/api/v2/library?page=1" \
-H "Authorization: Bearer {access_token}" \
-H "X-Farfalla-Tenant-Id: 42" \
-H "Accept: application/json"
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Shelves page number |
per_page | integer | 8 | Items per shelf |
scope | string | owned | owned returns only the user's library; all returns the storefront with commerce fields. See Storefront Mode |
Response: 200 OK
{
"meta": {
"current_page": 1,
"from": 1,
"to": 2,
"last_page": 1,
"per_page": 6,
"total": 2
},
"data": [
{
"filter_name": "section",
"filter_value": "continue_reading",
"title": "Continue Reading",
"data": [
{
"id": 153598,
"tenant_id": 42,
"name": "The Governor and the Rebel",
"slug": "the-governor-and-the-rebel",
"cover_url": "https://cdn.publica.la/issues/cover.jpg",
"published_at": "2020-11-20 03:00:00",
"type": "epub",
"description": "A historical novel...",
"external_id": "9786599001772",
"number_of_pages": 30,
"lang": "pt",
"author": "Azevedo, Israel Belo De",
"publisher": "Editora Prazer Da Palavra",
"bisac": "Fiction > Historical"
}
]
},
{
"filter_name": "section",
"filter_value": "latest_issues",
"title": "Latest Publications",
"data": []
}
]
}
Each section includes filter_name and filter_value which can be used with the filter endpoint to load more items.
The app version header X-FeniceBase-Version determines the response format. Versions >= 1.28.0 use filter_params (query string format) instead of the legacy filter_name/filter_value pair.
Filter Library Section
GET /api/v2/library/filter
Returns a single filtered section with full pagination. The filter parameters come from the library sections response (filter_name/filter_value or filter_params).
Request:
curl "https://app.publica.la/api/v2/library/filter?section=continue_reading&page=1&per_page=10" \
-H "Authorization: Bearer {access_token}" \
-H "X-Farfalla-Tenant-Id: 42" \
-H "Accept: application/json"
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
per_page | integer | 8 | Items per page |
{filter_name} | string | - | Dynamic filter from library section |
scope | string | owned | owned returns only the user's library; all returns the storefront with commerce fields |
Response: 200 OK - Same structure as a single library section, with full pagination metadata.
Storefront Mode (scope=all)
Both /library and /library/filter support an optional scope=all query parameter that turns the endpoint into a storefront view: it returns all eligible content for the tenant (owned and unowned alike) and augments every issue with commerce fields.
curl "https://app.publica.la/api/v2/library?scope=all" \
-H "Authorization: Bearer {access_token}" \
-H "X-Farfalla-Tenant-Id: 42" \
-H "Accept: application/json"
Response: 200 OK (same shape as the default response, with extra fields per issue)
{
"meta": { "...": "..." },
"data": [
{
"filter_name": "section",
"filter_value": "latest_issues",
"title": "Latest Publications",
"data": [
{
"id": 153598,
"tenant_id": 42,
"name": "The Governor and the Rebel",
"slug": "the-governor-and-the-rebel",
"cover_url": "https://cdn.publica.la/issues/cover.jpg",
"type": "epub",
"...": "...",
"can_be_read": false,
"can_be_bought": true,
"free": false,
"prices": [{ "currency": "USD", "amount": 9.99 }],
"purchase_link": null,
"status": "Acquire"
}
]
}
]
}
See Commerce > Commerce Fields for the full field reference and status label logic.
scope=all only works on single-tenant endpoints (these library endpoints, plus /search/store). The multi-tenant endpoints /user/my-content and /search/global ignore the parameter and never include commerce fields, because pricing depends on tenant context.
Check Favorite
GET /api/v2/library/{issue_id}/favorite-issues
Checks if an issue is in the user's favorites.
Request:
curl https://app.publica.la/api/v2/library/153598/favorite-issues \
-H "Authorization: Bearer {access_token}" \
-H "X-Farfalla-Tenant-Id: 42" \
-H "Accept: application/json"
Response: 200 OK
{
"is_favorite": false
}
Toggle Favorite
POST /api/v2/library/{issue_id}/favorite-issues
Toggles the favorite status of an issue. If favorited, removes it. If not, adds it.
Request:
curl -X POST https://app.publica.la/api/v2/library/153598/favorite-issues \
-H "Authorization: Bearer {access_token}" \
-H "X-Farfalla-Tenant-Id: 42" \
-H "Accept: application/json"
Response: 200 OK
{
"is_favorite": true
}