Content API Reference
Overview
The Content API allows you to manage digital and physical resources on the Publica.la platform. This includes creating, modifying, deleting, and querying resources such as ebooks, audiobooks, and physical books.
Make sure you generated the api_token on your store. More info in the API Authentication guide
Fields marked as "No" in the "Required" column are optional and can be omitted from the request entirely. You do not need to send them with empty values.
To sell physical books through the API, please contact [email protected] to verify if this feature is enabled for your store.
Endpoint Reference
Endpoint | Method | Description |
---|---|---|
/integration-api/v1/dashboard/issues | POST | Upload new content |
/integration-api/v1/dashboard/issues | GET | List or query content |
/integration-api/v1/dashboard/issues/(id) | GET | Retrieve specific content |
/integration-api/v1/dashboard/issues/(id) | PUT | Update existing content |
/integration-api/v1/dashboard/issues/(id) | DELETE | Delete content |
The GET content endpoint will be deprecated on December 31, 2025. Refer to the new Content API v3.
Upload Content
Create and upload a new content resource.
Endpoint: POST /integration-api/v1/dashboard/issues
- Digital Content
- Physical Content
Digital Content Request Fields
Field | Type | Description | Required |
---|---|---|---|
publication_date | string | Date of publication (YYYY-MM-DD) | Yes |
name | string | Title of the publication | Yes |
description | string | Description of the publication | No |
extension | string | File extension: 'mpga', 'mp3', 'pdf', or 'epub' | Yes |
file_url | string | URL of the content (public or signed URL) | Yes |
external_id | string | Your unique reference code (must be unique) | Yes |
free | boolean | Whether content is freely accessible | No |
bisac | array | Bisac Codes used as genres | No |
collection | array | Collection(s) the resource belongs to | No |
author | array | Author name(s) | No |
country | array | Available countries | No |
category | array | Category/categories | No |
publisher | array | Publisher name(s) | No |
keyword | array | Search keywords | No |
prices | object | Content prices by currency | No |
lang | string | Language (ISO 639-1 code) | No |
table_of_contents | json | Publication's table of contents | No |
cover | string | URL or path to cover image (jpg/png only) | No |
PDF Example
{
"publication_date": "2020-06-01",
"name": "The Computing Machine",
"description": "The description of the publication...",
"free": 0,
"bisac": [{ "code": "ANT018000" }],
"extension": "pdf",
"file_url": "https://valid/url/for.pdf",
"external_id": "PDF-CM-001",
"collection": ["The classics"],
"author": ["Grace Hopper"],
"country": ["Finland"],
"category": ["Hardware meets software"],
"publisher": ["publica.la"],
"keyword": ["API", "book"],
"prices": {
"USD": 2.00,
"ARS": 0.02,
"EUR": 2.35,
"MXN": 0.10
}
}
EPUB Example
{
"description": "This book is an essential guide for understanding the mechanisms behind our actions.",
"external_id": "isbn112233441",
"lang": "en",
"name": "The Power of Habits",
"author": ["Grace Hopper"],
"publication_date": "2022-09-01",
"bisac": [{ "code": "SEL009000" }],
"extension": "epub",
"file_url": "https://valid/url/for.epub",
"publisher": ["publica.la"],
"keyword": ["API", "book"],
"prices": {
"USD": 2.00,
"ARS": 0.02,
"EUR": 2.35
}
}
Audio Example
{
"description": "A powerful audiobook exploring personal growth and transformation.",
"external_id": "696900",
"lang": "pt",
"name": "Test Audio API",
"publication_date": "2019-09-13",
"extension": "mp3",
"file_url": "https://filesamples.com/samples/audio/mp3/Symphony%20No.6%20(1st%20movement).mp3"
}
Physical Content Request Fields
Field | Type | Description | Required |
---|---|---|---|
publication_date | string | Date of publication (YYYY-MM-DD) | Yes |
name | string | Title of the publication | Yes |
description | string | Description of the publication | No |
external_id | string | Your unique reference code (must be unique) | Yes |
free | boolean | Whether content is freely accessible | No |
bisac | array | Bisac Codes used as genres | No |
collection | array | Collection(s) the resource belongs to | No |
author | array | Author name(s) | No |
country | array | Available countries | No |
category | array | Category/categories | No |
publisher | array | Publisher name(s) | No |
keyword | array | Search keywords | No |
prices | object | Content prices by currency | No |
lang | string | Language (ISO 639-1 code) | No |
type | string | Must be 'physical' | Yes |
table_of_contents | html | Publication's table of contents | No |
pages | integer | Quantity of pages | No |
height | integer | Vertical dimension (cm/inches) | No |
width | integer | Horizontal dimension (cm/inches) | No |
weight | integer | Weight (grams) | No |
thickness | integer | Thickness (cm) | No |
stock | boolean | Whether the product is in stock (true/false) | No |
binding_type | string | Type of binding | No |
editing_location | string | Location where the book was edited | No |
cover | string | URL or path to cover image (jpg/png only) | No |
Physical Book Example
{
"publication_date": "2024-09-13",
"name": "The Art of Software Architecture",
"description": "A comprehensive guide to designing scalable and maintainable software systems...",
"external_id": "PHYS-BOOK-001",
"type": "physical",
"lang": "en",
"free": false,
"bisac": [
{ "code": "COM051230" }
],
"collection": ["Technical Books", "Architecture Series"],
"author": ["Grace Hopper", "Alan Turing"],
"country": ["United States", "Canada"],
"category": ["Software Engineering"],
"publisher": ["Tech Publishing House"],
"keyword": ["architecture", "software", "design", "patterns"],
"prices": {
"USD": 45.00,
"EUR": 42.00,
"GBP": 38.00
},
"cover": "https://example.com/covers/software-architecture.jpg",
"binding_type": "Hardcover",
"editing_location": "New York",
"table_of_contents": "<h2>Contents</h2><ul><li>Chapter 1: Introduction</li><li>Chapter 2: Principles</li></ul>",
"pages": 356,
"height": 23,
"width": 15,
"thickness": 3,
"weight": 650,
"stock": true
}
Response Fields
Field | Description | Type |
---|---|---|
CODE | Response status code | string |
data.issue | Content resource details | object |
data.message | Response message | string |
Example Response
{
"CODE": "success",
"data": {
"issue": {
"lang": "pt",
"name": "test audio api",
"external_id": "696900",
"published_at": {
"timestamp": 1568343600,
"date": "2019-09-13 00:00:00",
"timezone": "America/Argentina/Buenos_Aires"
},
"slug": "test-audio-api-1712991786",
"id": 1000003,
"description": "O Trabalho com o Espelho, um dos ensinamentos centrais...",
"free": false,
"prices": [],
// ... other fields ...
},
"message": "The title will be processed and available in your library in a moment.."
}
}
Response Codes
Code | Description |
---|---|
201 | Content created successfully |
422 | Validation error (details in response) |
401 | Unauthorized (invalid API token) |
403 | Forbidden (feature not enabled or insufficient permissions) |
You can host your files in Google Drive and use a direct download URL. Use this Google tool to convert sharing links to direct download links.
Get Content
Retrieve one or more content resources.
Endpoints:
GET /integration-api/v1/dashboard/issues
(list all content, paginated)GET /integration-api/v1/dashboard/issues/{id || external_reference}
(get specific content)
Query Parameters
Use the query
parameter to filter results:
Parameter Value | Description |
---|---|
converting | Filter by conversion state |
deferred | Filter by deferred state |
{name} | Filter by content name |
(id) | Filter by numerical ID |
Example Requests
- Get content in converting state:
GET /integration-api/v1/dashboard/issues/?query=converting
- Get by name:
GET /integration-api/v1/dashboard/issues/?query=The%20Computing%20Machine
- Get by ID:
GET /integration-api/v1/dashboard/issues/468166
- Get all content:
GET /integration-api/v1/dashboard/issues/
Response
The response includes detailed content information and pagination metadata when listing multiple resources.
Example Response (List)
{
"CODE": "success",
"data": {
"paginator": {
"current_page": 1,
"data": [
{
"id": 468166,
"external_id": "9781496822482",
"version": 1,
"name": "Conversations with Donald Hall",
"slug": "conversations-with-donald-hall",
"conversion_status": "done",
"published_at": {
"timestamp": 1616122800,
"date": "2021-03-19 00:00:00",
"timezone": "America/Argentina/Buenos_Aires"
},
"cover_image_path": "https://your-store.com/publicala/issues/2021/03/ZotqenpMS797S5wS/41a3c9c7-5f9f-4db5-bb6c-714865d2fdbd_cover.jpg",
"free": false,
"prices": {
"USD": 25
},
// ... other fields ...
},
// ... more items ...
],
"first_page_url": "https://your-store.com/integration-api/v1/dashboard/issues?page=1",
"from": 1,
"last_page": 6,
// ... pagination fields ...
},
"reached_issues_limit": false,
"reached_free_issues_limit": false
}
}
Response Codes
Code | Description |
---|---|
200 | Success |
404 | Content not found |
401 | Unauthorized (invalid API token) |
Update Content
Update an existing content resource.
Endpoint: PUT /integration-api/v1/dashboard/issues/{issue_id}
The file and file type cannot be updated through the API. If this action is necessary, you can replace the file with another file of the same type from the store publication panel.
Request Fields
Same as the Upload Content fields, with the following differences:
- When updating a publication, make sure to send all the desired final taxonomies and terms
- If a publication already has a term in a specific taxonomy and you just want to add a second one, you still need to send both
Example Request
{
"publication_date": "2020-06-01",
"name": "The Computing Machine",
"description": "The description of the publication...",
"free": 0,
"bisac": [{ "code": "ANT018000" }],
"collection": ["The classics"],
"author": ["Grace Hopper", "Alan Turing"],
"country": ["Finland"],
"category": ["Hardware meets software"],
"publisher": ["publica.la"],
"keyword": ["API", "book"],
"prices": {
"USD": 2.00,
"ARS": 0.02,
"EUR": 2.35
}
}
Response Codes
Code | Description |
---|---|
204 | Content updated successfully |
422 | Validation error (details in response) |
401 | Unauthorized (invalid API token) |
403 | Forbidden (insufficient permissions) |
404 | Content not found |
Delete Content
Delete a content resource.
Endpoint: DELETE /integration-api/v1/dashboard/issues/{issue_id}
The DELETE endpoint only accepts the numeric issue ID (not external_id
). You can retrieve the issue ID by using the GET endpoint with your external_id
first.
Example Request
DELETE https://your-store.com/integration-api/v1/dashboard/issues/468166
Response Codes
Code | Description |
---|---|
200 | Success |
404 | Content not found |
401 | Unauthorized (invalid API token) |
403 | Forbidden (insufficient permissions) |