Send to AI

Manage List Items

Add and remove publications in any list of any user of your store: the favorites list, a custom list the user created, or a list the user collaborates on. What you write here is what the user sees in the storefront and in the reader.

Both endpoints require an administrator token. See the Lists API Overview for authentication, the target user parameters and how a list is addressed.

Items only

The API writes the contents of lists, not the lists themselves. It does not create, rename, delete or share lists, does not change list privacy and does not manage collaborators. Those operations exist only in the storefront. The favorites list is the exception, see Working with favorites.

Both operations are idempotent

These endpoints are not toggles. Repeating a call leaves the list in the same state as the first call did, which makes them safe to retry:

Call	Result
Add a publication that is not in the list	`200`, the publication is added
Add a publication that is already there	`200` with the same body, nothing changes and nothing is duplicated
Remove a publication that is in the list	`204`, the publication is removed
Remove a publication that is not there	`204`, nothing changes

Add a publication to a list

Adds the publication to one of the target user's lists.

Endpoint

POST /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

Headers

Header	Required	Description
`X-User-Token`	Yes	API token of a store administrator
`Content-Type`	Yes	`application/json`
`Accept`	No	`application/json`

Body parameters

Parameter	Type	Required	Default	Description
`user_external_id`	string	Conditional	-	Your identifier for the user. Required unless `user_email` is sent
`user_email`	string	Conditional	-	Email of the user. Required unless `user_external_id` is sent
`content_id`	string	Yes	-	The publication identifier, read according to `id_type`
`id_type`	string	No	`internal`	`internal` reads `content_id` as the publica.la id; `external` reads it as one of the publication identifiers (ISBN among them)

Exactly one of user_external_id and user_email must be sent.

Request example

{
  "user_external_id": "student-1042",
  "content_id": "9781234567890",
  "id_type": "external"
}

Response

Success (200):

The added publication, in the same shape the items endpoints return.

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

The response is 200 whether this call added the publication or found it already there. content_id in the response is always the publica.la id, even when you addressed the publication by ISBN. added_at is null when the publication was already in the list from before the platform started recording that timestamp.

Examples

Add to favorites by ISBN

curl -X POST "https://yourstore.publica.la/api/v3/lists/favorites/items" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"user_external_id": "student-1042", "content_id": "9781234567890", "id_type": "external"}'

Add to favorites by publica.la id

curl -X POST "https://yourstore.publica.la/api/v3/lists/favorites/items" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"user_external_id": "student-1042", "content_id": "468166"}'

Identify the user by email

curl -X POST "https://yourstore.publica.la/api/v3/lists/favorites/items" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"user_email": "[email protected]", "content_id": "468166"}'

Add to any other list, by id

curl -X POST "https://yourstore.publica.la/api/v3/lists/9f2d4b1e-6c3a-4f58-9b77-1d0a2e5c8b34/items" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"user_external_id": "student-1042", "content_id": "468166"}'

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`	`The specified publication does not exist in this store.`	No publication matches `content_id` under the given `id_type`
`404`	`Not found`	`{list}` is not a list of the target user, an unknown slug, or a reserved storefront collection
`422`	First validation error	Neither or both user identifiers, missing `content_id`, or an unknown `id_type`
`429`	`Too Many Requests`	Rate limit exceeded

An unknown id_type returns:

{
  "message": "The selected id type is invalid.",
  "errors": {
    "id_type": ["The selected id type is invalid."]
  }
}

Remove a publication from a list

Removes the publication from one of the target user's lists.

Endpoint

DELETE /api/v3/lists/{list}/items/{content_id}

Path parameters

Parameter	Type	Description
`list`	string	The `favorites` slug, or the `id` of one of the user's lists. See Addressing a list
`content_id`	string	The publication identifier, read according to `id_type`

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
`id_type`	string	`internal`	`internal` reads `content_id` as the publica.la id; `external` reads it as one of the publication identifiers (ISBN among them)

Exactly one of user_external_id and user_email must be sent.

Response

Success (204):

No body. The response is 204 whether the publication was in the list or not.

Examples

Remove from favorites by ISBN

curl -X DELETE "https://yourstore.publica.la/api/v3/lists/favorites/items/9781234567890?user_external_id=student-1042&id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"

Remove from favorites by publica.la id

curl -X DELETE "https://yourstore.publica.la/api/v3/lists/favorites/items/468166?user_external_id=student-1042" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"

Identify the user by email

curl -X DELETE "https://yourstore.publica.la/api/v3/lists/favorites/items/468166?user_email=student%40example.com" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"

Remove from any other list, by id

curl -X DELETE "https://yourstore.publica.la/api/v3/lists/9f2d4b1e-6c3a-4f58-9b77-1d0a2e5c8b34/items/468166?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`	`The specified publication does not exist in this store.`	No publication matches `content_id` under the given `id_type`
`404`	`Not found`	`{list}` is not a list of the target user, an unknown slug, or a reserved storefront collection
`422`	First validation error	Neither or both user identifiers, or an unknown `id_type`
`429`	`Too Many Requests`	Rate limit exceeded

Working with favorites

Favorites is the list most integrations write to, and the only one with a slug: address it as favorites instead of its id, so no lookup is needed.

POST   /api/v3/lists/favorites/items
DELETE /api/v3/lists/favorites/items/{content_id}

A user who has never favorited anything has no favorites list yet. The endpoints hide that:

Add creates the favorites list on first use, so there is no separate create step. It is not created when the user or the publication does not exist.
Remove returns 204 when the user has no favorites list, the same as removing a publication that is not there.

Custom lists have no slug and are never created by the API. Read their id from List Lists first.

Manage List Items

Both operations are idempotent

Add a publication to a list

Endpoint

Path parameters

Headers

Body parameters

Request example

Response

Examples

Add to favorites by ISBN

Add to favorites by publica.la id

Identify the user by email

Add to any other list, by id

Errors

Remove a publication from a list

Endpoint

Path parameters

Query parameters

Response

Examples

Remove from favorites by ISBN

Remove from favorites by publica.la id

Identify the user by email

Remove from any other list, by id

Errors

Working with favorites

See also

Graph View

Both operations are idempotent​

Add a publication to a list​

Endpoint​

Path parameters​

Headers​

Body parameters​

Request example​

Response​

Examples​

Add to favorites by ISBN​

Add to favorites by publica.la id​

Identify the user by email​

Add to any other list, by id​

Errors​

Remove a publication from a list​

Endpoint​

Path parameters​

Query parameters​

Response​

Examples​

Remove from favorites by ISBN​

Remove from favorites by publica.la id​

Identify the user by email​

Remove from any other list, by id​

Errors​

Working with favorites​

See also​

Graph View

Both operations are idempotent

Add a publication to a list

Endpoint

Path parameters

Headers

Body parameters

Request example

Response

Examples

Add to favorites by ISBN

Add to favorites by publica.la id

Identify the user by email

Add to any other list, by id

Errors

Remove a publication from a list

Endpoint

Path parameters

Query parameters

Response

Examples

Remove from favorites by ISBN

Remove from favorites by publica.la id

Identify the user by email

Remove from any other list, by id

Errors

Working with favorites

See also