Get List Items
Read the publications a list of the target user holds. Any list of the store can be read, private ones included.
This endpoint requires an administrator token. See the Lists API Overview for authentication.
Item payload
| Field | Type | Description |
|---|---|---|
content_id | string | publica.la id of the publication |
isbn | string or null | Primary identifier of the publication, null when it has none |
title | string | Title of the publication |
reader_url | string | URL that opens the publication in the reader |
added_at | string or null | ISO 8601 timestamp of when the publication was added to the list, null for publications added before the platform started recording it |
Items come back in a stable order, the same order on every request, which is what lets a cursor page through a list without repeating or skipping an item. That order is not chronological.
Only publications are returned. Subscription plans a user added to the list from the storefront are omitted, and so are publications that are no longer available in your store.
Get the items of a list
Endpoint
GET /api/v3/lists/{list}/items
Path parameters
| Parameter | Type | Description |
|---|---|---|
list | string | The favorites slug, or the id of one of the user's lists. See Addressing a list |
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
user_external_id | string | - | Your identifier for the user. Required unless user_email is sent |
user_email | string | - | Email of the user. Required unless user_external_id is sent |
per_page | integer | 100 | Items per page, between 1 and 500 |
cursor | string | - | Cursor token, taken from links.next |
Exactly one of user_external_id and user_email must be sent.
Response
Success (200):
{
"data": [
{
"content_id": "468166",
"isbn": "9781234567890",
"title": "Conversations with Donald Hall",
"reader_url": "https://yourstore.publica.la/reader/conversations-with-donald-hall",
"added_at": "2026-08-27T12:00:00.000000Z"
}
],
"links": {
"next": null,
"prev": null
},
"meta": {
"has_more": false
}
}
Examples
The favorites of a user
curl -X GET "https://yourstore.publica.la/api/v3/lists/favorites/items?user_external_id=student-1042" \
-H "X-User-Token: your-api-token" \
-H "Accept: application/json"
Identify the user by email
curl -X GET "https://yourstore.publica.la/api/v3/lists/favorites/[email protected]" \
-H "X-User-Token: your-api-token" \
-H "Accept: application/json"
Next page
curl -X GET "https://yourstore.publica.la/api/v3/lists/favorites/items?user_external_id=student-1042&per_page=100&cursor=eyJwcm9kdWN0X2lkIjo0Njgx..." \
-H "X-User-Token: your-api-token" \
-H "Accept: application/json"
Any other list, by id
curl -X GET "https://yourstore.publica.la/api/v3/lists/9f2d4b1e-6c3a-4f58-9b77-1d0a2e5c8b34/items?user_external_id=student-1042" \
-H "X-User-Token: your-api-token" \
-H "Accept: application/json"
Errors
| Status | Message | Cause |
|---|---|---|
401 | Unauthenticated. | Missing or invalid X-User-Token |
403 | This store cannot access the integrations API. | The store does not have the integrations API enabled |
403 | This token cannot operate on other users' lists. | The token does not belong to a store administrator |
404 | The specified user does not exist in this store. | No user matches the identifier sent |
404 | Not found | Not a list of the target user, an unknown slug, or a reserved storefront collection (cart, save for later) |
422 | First validation error | Neither or both user identifiers, or per_page outside 1 to 500 |
429 | Too Many Requests | Rate limit or daily read quota exceeded |
Reading a user's favorites
The favorites list is addressed by its slug, so no lookup of the list id is needed:
GET /api/v3/lists/favorites/items?user_external_id=student-1042
A user who has never favorited anything has no favorites list yet. That is not an error: the endpoint returns an empty page.
{
"data": [],
"links": {
"next": null,
"prev": null
},
"meta": {
"has_more": false
}
}