Skip to main content

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.

info

Make sure you generated the api_token on your store. More info in the API Authentication guide

Field Requirements

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.

Physical Books

To sell physical books through the API, please contact [email protected] to verify if this feature is enabled for your store.

Endpoint Reference​

EndpointMethodDescription
/integration-api/v1/dashboard/issuesPOSTUpload new content
/integration-api/v1/dashboard/issuesGETList or query content
/integration-api/v1/dashboard/issues/(id)GETRetrieve specific content
/integration-api/v1/dashboard/issues/(id)PUTUpdate existing content
/integration-api/v1/dashboard/issues/(id)DELETEDelete content
Deprecated – Content API v1

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 Request Fields​

FieldTypeDescriptionRequired
publication_datestringDate of publication (YYYY-MM-DD)Yes
namestringTitle of the publicationYes
descriptionstringDescription of the publicationNo
extensionstringFile extension: 'mpga', 'mp3', 'pdf', or 'epub'Yes
file_urlstringURL of the content (public or signed URL)Yes
external_idstringYour unique reference code (must be unique)Yes
freebooleanWhether content is freely accessibleNo
bisacarrayBisac Codes used as genresNo
collectionarrayCollection(s) the resource belongs toNo
authorarrayAuthor name(s)No
countryarrayAvailable countriesNo
categoryarrayCategory/categoriesNo
publisherarrayPublisher name(s)No
keywordarraySearch keywordsNo
pricesobjectContent prices by currencyNo
langstringLanguage (ISO 639-1 code)No
table_of_contentsjsonPublication's table of contentsNo
coverstringURL 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"
}

Response Fields​

FieldDescriptionType
CODEResponse status codestring
data.issueContent resource detailsobject
data.messageResponse messagestring

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​

CodeDescription
201Content created successfully
422Validation error (details in response)
401Unauthorized (invalid API token)
403Forbidden (feature not enabled or insufficient permissions)
info

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 ValueDescription
convertingFilter by conversion state
deferredFilter 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​

CodeDescription
200Success
404Content not found
401Unauthorized (invalid API token)

Update Content​

Update an existing content resource.

Endpoint: PUT /integration-api/v1/dashboard/issues/{issue_id}

warning

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​

CodeDescription
204Content updated successfully
422Validation error (details in response)
401Unauthorized (invalid API token)
403Forbidden (insufficient permissions)
404Content not found

Delete Content​

Delete a content resource.

Endpoint: DELETE /integration-api/v1/dashboard/issues/{issue_id}

warning

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​

CodeDescription
200Success
404Content not found
401Unauthorized (invalid API token)
403Forbidden (insufficient permissions)
X

Graph View