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

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

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

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)
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)

Delete Content​

Delete a content resource.

Endpoints:

  • DELETE /integration-api/v1/dashboard/issues/{issue_id}
  • DELETE /integration-api/v1/dashboard/issues/{external_id}

Example Requests​

  • DELETE https://your-store.com/integration-api/v1/dashboard/issues/468166
  • DELETE https://your-store.com/integration-api/v1/dashboard/issues/9781496822482

Response Codes​

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

Graph View