NAV

REST API v2

This API can be used to programatically list your account's groups, as well as to list and create publications based on existing PDF documents.

Getting Started

Get an API key

To use the rest API you need to an API key. You can create one in your account directly through the following steps:

curl https://api.publitas.com/v2/groups \
  -H "Authorization: ApiKey <api_key>"

API keys are passed via the Authorization header as demonstrated in the code snippet to the right.

Understanding Pagination

Many endpoints in the API support pagination to help manage large result sets. When using pagination, the following query parameters are available:

Parameter Type Description
page Integer Page number to retrieve (default: returns all results)
per_page Integer Number of items per page (default: 1000, max: 1000)

When pagination is used, the following headers are included in the response:

Header Description
X-Page Current page number
X-Per-Page Number of items per page
X-Next-Page Next page number (if available)
X-Prev-Page Previous page number (if available)

If no pagination parameters are provided, the API will return all results in a single response, up to a maximum of 1000 items, and include the following header in the response:

Header Description
X-Result-Truncated Set to true if there are more items than the maximum allowed

API Path structure

The base path of an API request is: https://api.publitas.com/v2/

A example of a complete path is:

https://api.publitas.com/v2/groups/

Groups

# This will retrieve all the groups accessible by the user
curl https://api.publitas.com/v2/groups \
  -H "Authorization: ApiKey <api_key>"

The above command returns a JSON document structured like this:

{
  "groups": [
    {
      "id": 1,
      "title": "Example group",
      "slug": "example-group",
      "url": "https://api.publitas.com/v2/groups/1",
      "publications_url": "https://api.publitas.com/v2/groups/1/publications",
      "publication_count": 2,
      "public_url": "https://view.publitas.com/example-group"
    }
  ]
}

The attributes are as follows:

Field Type Description
id Integer Group ID
title String Group title
slug String Group slug
url String Group details URL
publications_url String Publication list URL for the group. Custom domain will be applied if there is one.
publication_count Integer Amount of publications contained within the group
public_url String Group public URL (redirects to latest online publication)

Publications

List all publications of a group

# This will retrieve all publications for a group
curl https://api.publitas.com/v2/groups/1/publications \
  -H "Authorization: ApiKey <api_key>"

The above command returns JSON structured like this:

{
  "publications": [
    {
      "id": 1,
      "title": "Spring 2014",
      "browser_title": "Browser Spring 2014",
      "description": "Spring 2014 description",
      "slug": "spring-2014",
      "url": "https://api.publitas.com/v2/groups/1/publications/1",
      "cover_url": "https://view.publitas.com/1/1/pages/fb7be8c8211c15f3b5aa6e7527fe6fe2efb4f60c-at800.jpg",
      "page_count": 52,
      "pdf_download_url": "https://view.publitas.com/1/1/pdfs/ba113516-f927-4f81-a814-68d050d8fb85.pdf?response-content-disposition=attachment%3B+filename%2A%3DUTF-8%27%27Browser%2520Spring%25202014.pdf",
      "state": "offline",
      "online_at": null,
      "offline_at": null,
      "schedule_online_at": null,
      "schedule_offline_at": null,
      "public_url": "https://view.publitas.com/example-group/spring-2014",
      "metatag_ids": [1, 2],
      "valid_from": null,
      "collection_id": null,
      "disable_seo": true,
      "language": "en",
      "secured": false,
      "show_related_publications": false,
      "auto_related_publications": false,
      "test": false,
      "custom_header": null,
      "force_single_page_on_mobile": false,
      "mobile_vertical_scroll": false,
      "override_mobile_layout": false,
      "content_goal": null,
      "content_goal_other": null,
      "format_type": null
    },
    {
      "id": 2,
      "title": "Autumn 2014",
      "browser_title": "Browser Autumn 2014",
      "description": "Autumn 2014 description",
      "slug": "autumn-2014",
      "url": "https://api.publitas.com/v2/groups/1/publications/2",
      "cover_url": "https://view.publitas.com/1/2/pages/fb7be8c8211c15f3b5aa6e7527fe6fe2efb4f60c-at800.jpg",
      "page_count": 52,
      "pdf_download_url": "https://view.publitas.com/1/2/pdfs/ba113516-f927-4f81-a814-68d050d8fb85.pdf?response-content-disposition=attachment%3B+filename%2A%3DUTF-8%27%27Browser%2520Autumn%25202014.pdf",
      "state": "offline",
      "online_at": null,
      "offline_at": null,
      "schedule_online_at": "2014-09-25T15:17:20.000+02:00",
      "schedule_offline_at": null,
      "public_url": "https://view.publitas.com/example-group/autumn-2014",
      "metatag_ids": [2, 3],
      "valid_from": "2014-09-26",
      "collection_id": null,
      "disable_seo": true,
      "language": "en",
      "secured": false,
      "show_related_publications": false,
      "auto_related_publications": false,
      "test": false,
      "custom_header": null,
      "force_single_page_on_mobile": false,
      "mobile_vertical_scroll": false,
      "override_mobile_layout": false,
      "content_goal": null,
      "content_goal_other": null,
      "format_type": null
    }
  ]
}

HTTP Request

GET https://api.publitas.com/v2/groups/<Group ID>/publications

URL Parameters

Parameter Description
Group ID The ID of a specific group

Query Parameters

See the Pagination section for pagination parameters.

The JSON response returns a list of publications with the following attributes:

Field Type Description
id Integer Publication ID
title String Publication Title
browser_title String SEO title
description String SEO description
slug String Publication Slug
url String Publication details URL
cover_url String URL for the cover image (@800 resolution)
page_count Integer Number of pages in the publication
pdf_download_url String Source PDF download URL
state String The publication state (see table below for a better description)
online_at DateTime Time at which the publication was last set online
offline_at DateTime Time at which the publication was last set offline
schedule_online_at DateTime Time at which the publication is scheduled to go online
schedule_offline_at DateTime Time at which the publication is scheduled to go offline
public_url String Publication public URL or null when the publication is still converting.
metatag_ids Array List of metatag IDs assigned to the publication
valid_from Date Validity date of the publication. This is a descriptive parameter and has no effect on the publication
collection_id Integer ID of the collection this publication belongs to, or null if not part of any collection
disable_seo Boolean Whether SEO is disabled for this publication (true = unlisted, false = public)
language String Language code of the publication (e.g. "en", "nl", "de"). See the language table below
secured Boolean Whether the publication is password-protected
show_related_publications Boolean Whether related publications are shown
auto_related_publications Boolean Whether related publications are automatically determined
test Boolean Whether this is a test publication
custom_header String Custom header HTML for the publication
force_single_page_on_mobile Boolean Whether to force single page layout on mobile devices
mobile_vertical_scroll Boolean Whether vertical scroll is enabled on mobile
override_mobile_layout Boolean Whether the mobile layout is overridden
content_goal String The content goal of the publication
content_goal_other String Custom content goal description (when content_goal is "other")
format_type String The format type of the publication

The state field can have one of the following values:

Value Description
offline Publication is not publicly visible.
online Publication is publicly visible.

Filtering results

You can filter the results list with the following query params:

# This will retrieve only publicly listed publications
curl "https://api.publitas.com/v2/groups/1/publications?state=public&collection_id=1" \
  -H "Authorization: ApiKey <api_key>"
Param Options Description
state public
unlisted
online
offline		 Return only publicly listed publications
Return only unlisted publications
Return public and unlisted publications
Return only offline publications
collection_id Integer Filter publications by collection ID. Returns only publications that belong to the specified collection

Get a specific publication

# This endpoint retrieves a specific publication.
curl "https://api.publitas.com/v2/groups/1/publications/222" \
  -H "Authorization: ApiKey <api_key>"

The above command returns JSON structured like this:

{
  "publication": [
    {
      "id": 222,
      "title": "Spring 2014",
      "browser_title": "Browser Spring 2014",
      "description": "Spring 2014 description",
      "slug": "spring-2014",
      "url": "https://api.publitas.com/v2/groups/1/publications/222",
      "cover_url": "https://view.publitas.com/1/222/pages/fb7be8c8211c15f3b5aa6e7527fe6fe2efb4f60c-at800.jpg",
      "page_count": 52,
      "pdf_download_url": "https://view.publitas.com/1/222/pdfs/ba113516-f927-4f81-a814-68d050d8fb85.pdf?response-content-disposition=attachment%3B+filename%2A%3DUTF-8%27%27Browser%2520Spring%25202014.pdf",
      "state": "offline",
      "online_at": null,
      "offline_at": null,
      "schedule_online_at": null,
      "schedule_offline_at": null,
      "public_url": "https://view.publitas.com/example-group/spring-2014",
      "metatag_ids": [2, 3],
      "valid_from": null,
      "collection_id": null,
      "disable_seo": true,
      "language": "en",
      "secured": false,
      "show_related_publications": false,
      "auto_related_publications": false,
      "test": false,
      "custom_header": null,
      "force_single_page_on_mobile": false,
      "mobile_vertical_scroll": false,
      "override_mobile_layout": false,
      "content_goal": null,
      "content_goal_other": null,
      "format_type": null
    }
  ]
}

HTTP Request

GET https://api.publitas.com/v2/groups/<Group ID>/publications/<Publication ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Publication ID The ID of a specific publication

Create a publication

# This will create a publication with the title Winter2014, browser title BrowserWinter2014, description Winter2014Description and source URL http://example.com/winter2014.pdf.
curl "https://api.publitas.com/v2/groups/1/publications" \
  -H "Authorization: ApiKey <api_key>" \
  --data "publication[title]=Winter2014&publication[source_url]=http://example.com/winter2014.pdf&publication[browser_title]=BrowserWinter2014&publication[description]=Winter2014Description"

The above command returns JSON structured like this:

{
  "publication": {
    "id": 3,
    "title": "Winter2014",
    "browser_title": "BrowserWinter2014",
    "description": "Winter2014Description",
    "slug": "winter2014",
    "url": "https://api.publitas.com/v2/groups/1/publications/3",
    "cover_url": null,
    "page_count": 0,
    "pdf_download_url": "https://view.publitas.com/1/3/pdfs/ba113516-f927-4f81-a814-68d050d8fb85.pdf?response-content-disposition=attachment%3B+filename%2A%3DUTF-8%27%27Browser%2520Winter%25202014.pdf",
    "state": "offline",
    "online_at": null,
    "offline_at": null,
    "schedule_online_at": null,
    "schedule_offline_at": null,
    "public_url": null,
    "metatag_ids": [],
    "valid_from": null,
    "disable_seo": true,
    "language": "en",
    "secured": false,
    "show_related_publications": false,
    "auto_related_publications": false,
    "test": false,
    "custom_header": null,
    "force_single_page_on_mobile": false,
    "mobile_vertical_scroll": false,
    "override_mobile_layout": false,
    "content_goal": null,
    "content_goal_other": null,
    "format_type": null
  }
}

HTTP Request

POST https://api.publitas.com/v2/groups/<Group ID>/publications

URL Parameters

Parameter Description
Group ID The ID of a specific group

Request body parameters

The following fields need to be sent within a publication scope (see the right panel for an example):

Name Type Required Description
source_url String Yes URL where the PDF file resides. HTTP and HTTPS are accepted, and it needs to be a public accessible file.
title String Yes The title for the publication
browser_title String No The SEO title for the publication
description String No The SEO description for the publication
language String No 2-digit language code. See the language table below for allowed values
schedule_online_at DateTime No Time at which the publication is scheduled to be online. If the current time is provided, the publication will be put online as soon as it is converted
schedule_offline_at DateTime No Time at which the publication is scheduled to be offline
metatag_ids Array No List of metatag IDs you want to assign to the publication
metatags_category String No Assigns all metatags in that category to the publication. This can be sent in combination with metatag_ids
valid_from Date No Validity date of the publication. This is a descriptive parameter and has no effect on the publication
collection_id Integer No Associate publication to a collection by ID
extraction_options Object No Define settings to extract hotspots from the PDF file. See extraction options for allowed fields
layout_type String No Sets the publication layout, possible values are: single, booklet. Changing the publication layout creates a new conversion

Hotspot Annotations

[
  /Subtype /Text
  /Rect [150 500 350 450]
  /Contents ({ "type": "product", "icon": true, "dynamic": true, "sku": "WP06-29-Black" })
  /ANN pdfmark

Tip – All rectangles are expressed in PDF user space units (1 unit = 1⁄72 inch) with the origin at the bottom‑left corner of the page.

Annotations present in the provided PDF can be automatically converted into hotspots. The annotation rectangle (/Rect) defines the hotspot’s clickable area.

Standard PDF Link annotations (/Subtype /Link) will be converted into link hotspots.

Standard Text annotations (/Subtype /Text) whose Contents string is a UTF-8 JSON object can be used for move advanced cases. An example using the PDFMark syntax is shown to the right

Field Reference

Field Type Required Description
type "product" Yes Hotspot type. Only product is currently recognized.
icon boolean No (default true) Whether the hotspot icon is rendered in the reader.
dynamic boolean No (default true) true ⇒ Publitas shows the full product card overlay; false ⇒ hotspot acts as a transparent link over designer-provided imagery.
sku string \ string[] Yes

Update a publication

# This will update a publication's title, schedule it to go online, and assign metatags with IDs 1 and 2.
curl "https://api.publitas.com/v2/groups/1/publications/3" \
  -H "Authorization: ApiKey <api_key>" \
  -H "Content-Type: application/json" \
  -X PUT \
  --data '{"publication": {"title": "Winter 2014 Updated", "browser_title": "UpdatedBrowserTitle", "description": "UpdatedDescription", "schedule_online_at": "2025-06-01T10:00:00+02:00", "metatag_ids": [1,2]}}'

The above command returns JSON structured like this:

{
  "publication": {
    "id": 3,
    "title": "Winter 2014 Updated",
    "browser_title": "UpdatedBrowserTitle",
    "description": "UpdatedDescription",
    "slug": "winter2014",
    "url": "https://api.publitas.com/v2/groups/1/publications/3",
    "cover_url": null,
    "page_count": 0,
    "pdf_download_url": "https://view.publitas.com/1/3/pdfs/ba113516-f927-4f81-a814-68d050d8fb85.pdf?response-content-disposition=attachment%3B+filename%2A%3DUTF-8%27%27Browser%2520Winter%25202014.pdf",
    "state": "offline",
    "online_at": null,
    "offline_at": null,
    "schedule_online_at": "2025-06-01T10:00:00.000+02:00",
    "schedule_offline_at": null,
    "public_url": null,
    "metatag_ids": [1, 2],
    "valid_from": null,
    "disable_seo": true,
    "language": "en",
    "secured": false,
    "show_related_publications": false,
    "auto_related_publications": false,
    "test": false,
    "custom_header": null,
    "force_single_page_on_mobile": false,
    "mobile_vertical_scroll": false,
    "override_mobile_layout": false,
    "content_goal": null,
    "content_goal_other": null,
    "format_type": null
  }
}

HTTP Request

PUT https://api.publitas.com/v2/groups/<Group ID>/publications/<Publication ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Publication ID The ID of a specific publication

Request body parameters

The following fields need to be sent within a publication scope (see the right panel for an example):

Name Type Required Description
title String No The title of the publication
slug String No The URL slug. Only lowercase letters, numbers, hyphens, and underscores allowed. Must be unique within the group
language String No Language code (e.g. "en", "nl", "de"). See the language table for allowed values
browser_title String No The SEO title for the publication
description String No The SEO description for the publication
metatag_ids Array No List of metatag IDs you want to assign to the publication. This replaces current assignments (sending an empty array will clear assignments).
metatags_category String No Assigns all metatags in that category to the publication. This can be sent in combination with metatag_ids
valid_from Date No Validity date of the publication. This is a descriptive parameter and has no effect on the publication
layout_type String No Sets the publication layout, possible values are: single, booklet. Changing the publication layout creates a new conversion
schedule_online_at DateTime No ISO 8601 date-time to schedule publication to go online. Requires the scheduling feature to be enabled on the account
schedule_offline_at DateTime No ISO 8601 date-time to schedule publication to go offline. Requires the scheduling feature to be enabled on the account
disable_seo Boolean No Whether to disable SEO for this publication. Requires the disable SEO feature to be enabled on the account
secured Boolean No Whether the publication is password-protected. Requires the secure publications feature to be enabled on the account
password String No Password for the publication (required when secured is true). Never returned in responses
show_related_publications Boolean No Whether to show related publications
auto_related_publications Boolean No Whether related publications are automatically determined
test Boolean No Whether this is a test publication
custom_header String No Custom header HTML for the publication. Requires the custom header feature to be enabled on the account
force_single_page_on_mobile Boolean No Whether to force single page layout on mobile devices. Requires the force single page on mobile feature to be enabled on the account
mobile_vertical_scroll Boolean No Whether vertical scroll is enabled on mobile. Requires the mobile vertical scroll feature to be enabled on the account
override_mobile_layout Boolean No Whether to override the mobile layout. Requires the force single page on mobile or mobile vertical scroll feature to be enabled on the account
content_goal String No The content goal of the publication. Requires the content metadata feature to be enabled on the account
content_goal_other String No Custom content goal description (when content_goal is "other"). Requires the content metadata feature to be enabled on the account
format_type String No The format type of the publication. Requires the content metadata feature to be enabled on the account

Mark a publication as online

# This endpoint marks a publication as being online.
curl "https://api.publitas.com/v2/groups/1/publications/222/online" \
  -H "Authorization: ApiKey <api_key>" \
  -X POST

When the response code is 200 the command returns JSON structured like this:

{
  "publication": [
    {
      "id": 222,
      "title": "Spring 2014",
      "browser_title": "Browser Spring 2014",
      "description": "Spring 2014 description",
      "slug": "spring-2014",
      "url": "https://api.publitas.com/v2/groups/1/publications/222",
      "cover_url": "https://view.publitas.com/1/222/pages/fb7be8c8211c15f3b5aa6e7527fe6fe2efb4f60c-at800.jpg",
      "page_count": 52,
      "pdf_download_url": "https://view.publitas.com/1/222/pdfs/ba113516-f927-4f81-a814-68d050d8fb85.pdf?response-content-disposition=attachment%3B+filename%2A%3DUTF-8%27%27Browser%2520Spring%25202014.pdf",
      "state": "online",
      "online_at": "2015-01-28T16:05:28.309+01:00",
      "offline_at": null,
      "schedule_online_at": null,
      "schedule_offline_at": null,
      "public_url": "https://view.publitas.com/example-group/spring-2014",
      "valid_from": null,
      "disable_seo": false,
      "language": "en",
      "secured": false,
      "show_related_publications": false,
      "auto_related_publications": false,
      "test": false,
      "custom_header": null,
      "force_single_page_on_mobile": false,
      "mobile_vertical_scroll": false,
      "override_mobile_layout": false,
      "content_goal": null,
      "content_goal_other": null,
      "format_type": null
    }
  ]
}

HTTP Request

POST https://api.publitas.com/v2/groups/<Group ID>/publications/<Publication ID>/online

Response codes

This endpoint returns one of the following HTTP codes:

Code Description
200 Publication is online
402 You have reached your publishing limit.

Mark a publication as offline

# This endpoint marks a publication as being offline.
curl "https://api.publitas.com/v2/groups/1/publications/222/offline" \
  -H "Authorization: ApiKey <api_key>" \
  -X POST

The above command returns JSON structured like this:

{
  "publication": [
    {
      "id": 222,
      "title": "Spring 2014",
      "browser_title": "Browser Spring 2014",
      "description": "Spring 2014 description",
      "slug": "spring-2014",
      "url": "https://api.publitas.com/v2/groups/1/publications/222",
      "cover_url": "https://view.publitas.com/1/222/pages/fb7be8c8211c15f3b5aa6e7527fe6fe2efb4f60c-at800.jpg",
      "page_count": 52,
      "pdf_download_url": "https://view.publitas.com/1/222/pdfs/ba113516-f927-4f81-a814-68d050d8fb85.pdf?response-content-disposition=attachment%3B+filename%2A%3DUTF-8%27%27Browser%2520Spring%25202014.pdf",
      "state": "offline",
      "online_at": "2015-01-28T16:05:28.309+01:00",
      "offline_at": "2015-01-28T17:05:28.309+01:00",
      "schedule_online_at": null,
      "schedule_offline_at": null,
      "public_url": "https://view.publitas.com/example-group/spring-2014",
      "valid_from": null,
      "disable_seo": true,
      "language": "en",
      "secured": false,
      "show_related_publications": false,
      "auto_related_publications": false,
      "test": false,
      "custom_header": null,
      "force_single_page_on_mobile": false,
      "mobile_vertical_scroll": false,
      "override_mobile_layout": false,
      "content_goal": null,
      "content_goal_other": null,
      "format_type": null
    }
  ]
}

HTTP Request

POST https://api.publitas.com/v2/groups/<Group ID>/publications/<Publication ID>/offline

Response codes

This endpoint returns the 200 response code.

Mark a publication as unlisted

# This endpoint marks a publication as being online but unlisted (SEO disabled).
curl "https://api.publitas.com/v2/groups/1/publications/222/unlisted" \
  -H "Authorization: ApiKey <api_key>" \
  -X POST

When the response code is 200 the command returns JSON structured like this:

{
  "publication": [
    {
      "id": 222,
      "title": "Spring 2014",
      "browser_title": "Browser Spring 2014",
      "description": "Spring 2014 description",
      "slug": "spring-2014",
      "url": "https://api.publitas.com/v2/groups/1/publications/222",
      "cover_url": "https://view.publitas.com/1/222/pages/fb7be8c8211c15f3b5aa6e7527fe6fe2efb4f60c-at800.jpg",
      "page_count": 52,
      "pdf_download_url": "https://view.publitas.com/1/222/pdfs/ba113516-f927-4f81-a814-68d050d8fb85.pdf?response-content-disposition=attachment%3B+filename%2A%3DUTF-8%27%27Browser%2520Spring%25202014.pdf",
      "state": "online",
      "online_at": "2015-01-28T16:05:28.309+01:00",
      "offline_at": null,
      "schedule_online_at": null,
      "schedule_offline_at": null,
      "public_url": "https://view.publitas.com/example-group/spring-2014",
      "valid_from": null,
      "disable_seo": true,
      "language": "en",
      "secured": false,
      "show_related_publications": false,
      "auto_related_publications": false,
      "test": false,
      "custom_header": null,
      "force_single_page_on_mobile": false,
      "mobile_vertical_scroll": false,
      "override_mobile_layout": false,
      "content_goal": null,
      "content_goal_other": null,
      "format_type": null
    }
  ]
}

HTTP Request

POST https://api.publitas.com/v2/groups/<Group ID>/publications/<Publication ID>/unlisted

Response codes

This endpoint returns one of the following HTTP codes:

Code Description
200 Publication is online and unlisted
402 You have reached your publishing limit.

Archive Publication

# This endpoint archives a publication
curl "https://api.publitas.com/v2/groups/1/publications/222" \
  -H "Authorization: ApiKey <api_key>" \
  -X DELETE

The above command returns a 204 with no content

HTTP Request

DELETE https://api.publitas.com/v2/groups/<Group ID>/publications/<Publication ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Publication ID The ID of a specific publication

Metatags

List all metatags of a group

# This will retrieve all metatags for a group
curl  "https://api.publitas.com/v2/groups/1/metatags" \
  -H "Authorization: ApiKey <api_key>"

The above command returns JSON structured like this:

{
  "metatags": [
    {
      "id": 1,
      "group_id": 1,
      "category": "category_1",
      "value": "value_1"
    },
    {
      "id": 2,
      "group_id": 1,
      "category": "category_1",
      "value": "value_2"
    }
  ]
}

HTTP Request

GET https://api.publitas.com/v2/groups/<Group ID>/metatags

URL Parameters

Parameter Description
Group ID The ID of a specific group

Query Parameters

See the Pagination section for pagination parameters.

The JSON response returns a list of metatags with the following attributes:

Field Type Description
id Integer Publication ID
group_id Integer Group ID
category String Metatag category
value String Metatag value

Get a specific metatag

# This endpoint retrieves a specific metatag.
curl "https://api.publitas.com/v2/groups/1/metatags/222" \
  -H "Authorization: ApiKey <api_key>"

The above command returns JSON structured like this:

{
  "metatag": [
    {
      "id": 222,
      "group_id": 1,
      "category": "category_1",
      "value": "value_1"
    }
  ]
}

HTTP Request

GET https://api.publitas.com/v2/groups/<Group ID>/metatags/<Metatag ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Metatag ID The ID of a specific metatag

Create a metatag

# This will create a metatag with the categordy category_3 and value value_3.
curl "https://api.publitas.com/v2/groups/1/metatags" \
  -H "Authorization: ApiKey <api_key>" \
  --data "metatag[category]=category_3&metatag[value]=value_3"

The above command returns JSON structured like this:

{
  "metatag": {
    "id": 3,
    "group_id": 1,
    "category": "category_3",
    "value": "value_3"
  }
}

HTTP Request

POST https://api.publitas.com/v2/groups/<Group ID>/metatags

URL Parameters

Parameter Description
Group ID The ID of a specific group

Request body parameters

The following fields need to be sent within a metatag scope (see the right panel for an example):

Name Type Required Description
category String Yes Category of the metatag
value String Yes Value of the metatag

Update a metatag

# This will update a metatag with the category new_category and value value_4.
curl "https://api.publitas.com/v2/groups/1/metatags/3" \
  -H "Authorization: ApiKey <api_key>" \
  -X PUT \
  --data "metatag[category]=new_category&metatag[value]=value_4"

The above command returns JSON structured like this:

{
  "metatag": {
    "id": 3,
    "group_id": 1,
    "category": "new_category",
    "value": "value_4"
  }
}

HTTP Request

PUT https://api.publitas.com/v2/groups/<Group ID>/metatags/<Metatag ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Metatag ID The ID of a specific metatag

Request body parameters

The following fields need to be sent within a metatag scope (see the right panel for an example):

Name Type Required Description
category String No Category of the metatag
value String No Value of the metatag

Delete a metatag

# This will try to delete a metatag with id 4.
curl "https://api.publitas.com/v2/groups/1/metatags/4" \
  -H "Authorization: ApiKey <api_key>" \
  -X DELETE

The above command returns a 409 error and the following JSON if metatag is assigned to a publication:

{
  "error": "Metatag is currently in use, send \"force_delete=true\" to delete anyway"
}

# This will delete the metatag with id 4 even if it's assigned to a publication.
curl "https://api.publitas.com/v2/groups/1/metatags/4?force_delete=true" \
  -H "Authorization: ApiKey <api_key>" \
  -X DELETE

The above command returns a 204 with no content

HTTP Request

DELETE https://api.publitas.com/v2/groups/<Group ID>/metatags/<Metatag ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Metatag ID The ID of a specific metatag
force_delete Send "true" to override "Metatag is currently in use" error

Collections

List all collections of a group

# This will retrieve all collections for a group
curl "https://api.publitas.com/v2/groups/1/collections" \
  -H "Authorization: ApiKey <api_key>"

The above command returns JSON structured like this:

{
  "collections": [
    {
      "id": 1,
      "title": "Collection 1",
      "group_id": 1,
      "current_product_library_id": null
    },
    {
      "id": 2,
      "title": "Collection 2",
      "group_id": 1,
      "current_product_library_id": 5
    }
  ]
}

HTTP Request

GET https://api.publitas.com/v2/groups/<Group ID>/collections

URL Parameters

Parameter Description
Group ID The ID of a specific group

Query Parameters

See the Pagination section for pagination parameters.

The JSON response returns a list of collections with the following attributes:

Field Type Description
id Integer Collection ID
title String Collection Title
group_id Integer ID of the group this collection belongs to
current_product_library_id Integer ID of the associated product library, or null if unset

Get a specific collection

# This endpoint retrieves a specific collection.
curl "https://api.publitas.com/v2/groups/1/collections/42" \
  -H "Authorization: ApiKey <api_key>"

The above command returns JSON structured like this:

{
  "collection": {
    "id": 42,
    "title": "Collection 1",
    "group_id": 1,
    "current_product_library_id": null
  }
}

HTTP Request

GET https://api.publitas.com/v2/groups/<Group ID>/collections/<Collection ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Collection ID The ID of a specific collection

Create a collection

HTTP Request

POST https://api.publitas.com/v2/groups/<Group ID>/collections

URL Parameters

Parameter Description
Group ID The ID of a specific group 
curl -H "Authorization: ApiKey <api_key>" --data "{
  "collection": {
    "title": "New Collection"
  }
}"

The above command returns JSON structured like this:

{
  "collection": {
    "id": 42,
    "title": "New Collection",
    "group_id": 1,
    "current_product_library_id": null
  }
}

Request body parameters

The following fields need to be sent within a collection scope (see the right panel for an example):

Name Type Required Description
title String Yes Collection Title

Update a collection

# This will update a collection's title.
curl "https://api.publitas.com/v2/groups/1/collections/42" \
  -H "Authorization: ApiKey <api_key>" \
  -X PUT \
  --data "collection[title]=Updated Title"

The above command returns JSON structured like this:

{
  "collection": {
    "id": 42,
    "title": "Updated Title",
    "group_id": 1,
    "current_product_library_id": null
  }
}

HTTP Request

PUT https://api.publitas.com/v2/groups/<Group ID>/collections/<Collection ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Collection ID The ID of the collection to update

Request body parameters

The following fields need to be sent within a collection scope (see the right panel for an example):

Name Type Required Description
title String No Collection Title
current_product_library_id Integer No ID of the product library to associate, or null to clear

Delete a collection

HTTP Request

DELETE https://api.publitas.com/v2/groups/<Group ID>/collections/<Collection ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Collection ID The ID of the collection to delete 
curl -X DELETE "https://api.publitas.com/v2/groups/1/collections/42" \
  -H "Authorization: ApiKey <api_key>"

Response codes

Code Description
204 No Content - Collection successfully deleted
403 Forbidden - Invalid API key or insufficient permissions
404 Not Found - Collection does not exist
409 Conflict - Collection cannot be deleted because it contains publications

Error responses

When a collection cannot be deleted because it contains publications, the API returns a 409 Conflict status with the following error message:

{
  "error": "You can't delete this collection. It must be empty."
}

Product Libraries

List all product libraries of a group

# This will retrieve all product libraries for a group
curl "https://api.publitas.com/v2/groups/1/product_libraries" \
  -H "Authorization: ApiKey <api_key>"

The above command returns JSON structured like this:

{
  "product_libraries": [
    {
      "id": 1,
      "group_id": 1,
      "account_id": 10,
      "title": "Main Library",
      "url": "https://some/feed/file.xml",
      "sync_enabled": true,
      "sync_hour": 3,
      "sync_time_zone": "Europe/Amsterdam",
      "hourly_sync_enabled": false,
      "integration_instance_id": null,
      "external_id": null,
      "created_at": "2026-04-01T10:00:00Z",
      "updated_at": "2026-04-10T12:00:00Z",
      "last_import": {
        "id": 42,
        "state": "success",
        "success_count": 1891,
        "failed_count": 0,
        "created_at": "2026-04-10T12:00:00Z"
      }
    }
  ]
}

HTTP Request

GET https://api.publitas.com/v2/groups/<Group ID>/product_libraries

URL Parameters

Parameter Description
Group ID The ID of a specific group

Query Parameters

See the Pagination section for pagination parameters.

The JSON response returns a list of product libraries with the following attributes:

Field Type Description
id Integer Product Library ID
group_id Integer ID of the group this product library belongs to
account_id Integer ID of the account this product library belongs to
title String Product Library title
url String URL of the product feed file backing this library
sync_enabled Boolean Whether scheduled sync is enabled
sync_hour Integer Hour of the day (0-23) at which the daily sync runs
sync_time_zone String Time zone in which sync_hour is interpreted (IANA identifier, e.g. Europe/Amsterdam)
hourly_sync_enabled Boolean Whether the library is synced every hour
integration_instance_id Integer ID of the integration instance backing this library, or null if none
external_id Integer External identifier for libraries that are synced from an external system
created_at String ISO 8601 timestamp of creation
updated_at String ISO 8601 timestamp of last update
last_import Object Summary of the most recent import, or null if the library has never been imported

The last_import object has the following attributes:

Field Type Description
id Integer Import ID
state String Import state (processing, success, failed)
success_count Integer Number of products successfully imported
failed_count Integer Number of products that failed to import
created_at String ISO 8601 timestamp at which the import was created

Get a specific product library

# This endpoint retrieves a specific product library.
curl "https://api.publitas.com/v2/groups/1/product_libraries/1" \
  -H "Authorization: ApiKey <api_key>"

The above command returns JSON structured like this:

{
  "product_library": {
    "id": 1,
    "group_id": 1,
    "account_id": 10,
    "title": "Main Library",
    "url": "https://some/feed/file.xml",
    "sync_enabled": true,
    "sync_hour": 3,
    "sync_time_zone": "Europe/Amsterdam",
    "hourly_sync_enabled": false,
    "integration_instance_id": null,
    "external_id": null,
    "created_at": "2026-04-01T10:00:00Z",
    "updated_at": "2026-04-10T12:00:00Z",
    "last_import": {
      "id": 42,
      "state": "success",
      "success_count": 1891,
      "failed_count": 0,
      "created_at": "2026-04-10T12:00:00Z"
    }
  }
}

HTTP Request

GET https://api.publitas.com/v2/groups/<Group ID>/product_libraries/<Product Library ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Product Library ID The ID of a specific product library

Create a product library

HTTP Request

POST https://api.publitas.com/v2/groups/<Group ID>/product_libraries

URL Parameters

Parameter Description
Group ID The ID of a specific group 
curl "https://api.publitas.com/v2/groups/1/product_libraries" \
  -H "Authorization: ApiKey <api_key>" \
  -H "Content-Type: application/json" \
  --data '{
    "product_library": {
      "title": "Main Library",
      "url": "https://some/feed/file.xml",
      "sync_enabled": true,
      "sync_hour": 3,
      "sync_time_zone": "Europe/Amsterdam"
    }
  }'

The above command returns JSON structured like this:

{
  "product_library": {
    "id": 1,
    "group_id": 1,
    "account_id": 10,
    "title": "Main Library",
    "url": "https://some/feed/file.xml",
    "sync_enabled": true,
    "sync_hour": 3,
    "sync_time_zone": "Europe/Amsterdam",
    "hourly_sync_enabled": false,
    "integration_instance_id": null,
    "external_id": null,
    "created_at": "2026-04-13T16:12:08Z",
    "updated_at": "2026-04-13T16:12:08Z",
    "last_import": null
  }
}

Creating a product library schedules an initial import of its product feed.

Request body parameters

The following fields need to be sent within a product_library scope (see the right panel for an example):

Name Type Required Description
title String Yes Product Library title
url String No URL of the product feed file. HTTP, HTTPS, FTP and SFTP are accepted
sync_enabled Boolean No Whether scheduled sync is enabled
sync_hour Integer No Hour of the day (0-23) at which the daily sync runs
sync_time_zone String No Time zone in which sync_hour is interpreted (IANA identifier)
hourly_sync_enabled Boolean No Whether the library is synced every hour
integration_instance_id Integer No ID of the integration instance to back this library, instead of a url

Response codes

This endpoint returns the 201 response code on success.

Update a product library

# This will update a product library's title and URL.
curl "https://api.publitas.com/v2/groups/1/product_libraries/1" \
  -H "Authorization: ApiKey <api_key>" \
  -H "Content-Type: application/json" \
  -X PUT \
  --data '{
    "product_library": {
      "title": "Updated Title",
      "url": "https://some/new/feed.xml"
    }
  }'

The above command returns JSON structured like this:

{
  "product_library": {
    "id": 1,
    "group_id": 1,
    "account_id": 10,
    "title": "Updated Title",
    "url": "https://some/new/feed.xml",
    "sync_enabled": true,
    "sync_hour": 3,
    "sync_time_zone": "Europe/Amsterdam",
    "hourly_sync_enabled": false,
    "integration_instance_id": null,
    "external_id": null,
    "created_at": "2026-04-13T16:12:08Z",
    "updated_at": "2026-04-14T09:30:00Z",
    "last_import": {
      "id": 42,
      "state": "success",
      "success_count": 1891,
      "failed_count": 0,
      "created_at": "2026-04-10T12:00:00Z"
    }
  }
}

HTTP Request

PUT https://api.publitas.com/v2/groups/<Group ID>/product_libraries/<Product Library ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Product Library ID The ID of the product library to update

Request body parameters

The following fields need to be sent within a product_library scope (see the right panel for an example):

Name Type Required Description
title String No Product Library title
url String No URL of the product feed file. HTTP, HTTPS, FTP and SFTP are accepted
sync_enabled Boolean No Whether scheduled sync is enabled
sync_hour Integer No Hour of the day (0-23) at which the daily sync runs
sync_time_zone String No Time zone in which sync_hour is interpreted (IANA identifier)
hourly_sync_enabled Boolean No Whether the library is synced every hour
integration_instance_id Integer No ID of the integration instance to back this library, instead of a url

Updating url or integration_instance_id schedules a new import of the library.

Delete a product library

HTTP Request

DELETE https://api.publitas.com/v2/groups/<Group ID>/product_libraries/<Product Library ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Product Library ID The ID of the product library to delete 
curl -X DELETE "https://api.publitas.com/v2/groups/1/product_libraries/1" \
  -H "Authorization: ApiKey <api_key>"

Response codes

Code Description
204 No Content - Product library successfully deleted
403 Forbidden - Invalid API key or insufficient permissions
404 Not Found - Product library does not exist

Sync a product library

Triggers an on-demand import of a product library's feed. The import runs asynchronously; poll the library's last_import to track progress.

HTTP Request

POST https://api.publitas.com/v2/groups/<Group ID>/product_libraries/<Product Library ID>/sync

URL Parameters

Parameter Description
Group ID The ID of a specific group
Product Library ID The ID of the product library to sync 
curl -X POST "https://api.publitas.com/v2/groups/1/product_libraries/1/sync" \
  -H "Authorization: ApiKey <api_key>"

Response codes

Code Description
202 Accepted - Import scheduled
403 Forbidden - Invalid API key or insufficient permissions
404 Not Found - Product library does not exist

Pages

Add pages to publication

Add pages to a publication from a PDF file

HTTP Request

POST https://api.publitas.com/v2/groups/<Group ID>/publications/<Publication ID>/pages

URL Parameters

Parameter Description
Group ID ID of a group containing the publication
Publication ID The ID of a publication to add pages to 
curl 'https://api.publitas.com/v2/groups/<Group ID>/publications/<Publication ID>/pages' \
  -H 'Authorization: ApiKey <api_key>' \
  -H 'Content-Type: application/json' \
  --data '{
    "source_url": "https://some/file.pdf"
  }'

Request body parameters

Name Type Required Description
source_url String Yes URL of the PDF file to upload. HTTP and HTTPS are accepted, and it needs to be a publicly accessible file
source_page_numbers Array No List of page numbers in the pdf file to be added into the publication
position Integer No Page number where new pages should be inserted (by default add pages at the end)
extraction_options Object No Hotspot extraction (auto-tagging) settings, see extraction options for details

Response codes

This endpoint returns the 200 response code.

Replace a publication page

Replace a page in a publication

HTTP Request

PUT https://api.publitas.com/v2/groups/<Group ID>/publications/<Publication ID>/pages/<Page Number>

URL Parameters

Parameter Description
Group ID ID of a group containing the publication
Publication ID The ID of a publication to replace a page in
Page Number The number of the page to be replaced in the publication 
curl 'https://api.publitas.com/v2/groups/<Group ID>/publications/<Publication ID>/pages/<Page Number>' \
  -H 'Authorization: ApiKey <api_key>' \
  -H 'Content-Type: application/json' \
  -X PUT
  --data '{
    "page": {
      "source_url": "https://some/file.pdf"
    }
  }'

Request body parameters

The following fields need to be sent within a page scope (see the right panel for an example):

Name Type Required Description
source_url String Yes URL where the PDF file resides. HTTP and HTTPS are accepted, and it needs to be a public accessible file
source_page_number Integer No PDF page number to be used on replace (by default page number 1 is used)
extraction_options Object No Hotspot extraction (auto-tagging) settings, see extraction options for details
remove_hotspots Boolean No Remove existing hotspots on the specified page (based on page number parameter)

Response codes

This endpoint returns the 200 response code.

Remove a publication page

HTTP Request

DELETE https://api.publitas.com/v2/groups/<Group ID>/publications/<Publication ID>/pages/<Page Number>

curl "https://api.publitas.com/v2/groups/1/publications/222/pages/1" \
  -H "Authorization: ApiKey <api_key>" \
  -X DELETE

URL Parameters

Parameter Description
Group ID ID of a group containing the publication
Publication ID The ID of a publication to remove a page from
Page Number The number of the page to be removed in the publication

Response codes

This endpoint returns the 200 response code.

Product Feeds

List recent product feeds

Lists last 5 product feed imports

curl --location "http://api.publitas.com/v2/groups/1/product_feeds" --header "Authorization: ApiKey <api_key>"

The above command returns a JSON document structured like this:

{
  "product_feeds": [
    {
      "id": 28,
      "group_id": 1,
      "url": "http://some/feed/file.xml",
      "state": "processing",
      "success_count": 0,
      "failed_count": 0
    },
    {
      "id": 27,
      "group_id": 1,
      "url": "http://some/feed/file.xml",
      "state": "success",
      "success_count": 1891,
      "failed_count": 0
    },
    {
      "id": 26,
      "group_id": 1,
      "url": "http://some/feed/file.xml",
      "state": "failed",
      "success_count": 1,
      "failed_count": 1890
    },
    {
      "id": 25,
      "group_id": 1,
      "url": "http://some/feed/file.xml",
      "state": "success",
      "success_count": 1891,
      "failed_count": 0
    },
    {
      "id": 24,
      "group_id": 1,
      "url": "http://some/feed/file.xml",
      "state": "success",
      "success_count": 1891,
      "failed_count": 0
    }
  ]
}

HTTP Request

GET https://api.publitas.com/v2/groups/<Group ID>/product_feeds

URL Parameters

Parameter Description
Group ID The ID of a specific group

Create a product feed

HTTP Request

POST https://api.publitas.com/v2/groups/<Group ID>/product_feeds

curl 'http://api.publitas.com/v2/groups/1/product_feeds' \
  -H 'Authorization: ApiKey <api_key>' \
  -H 'Content-Type: application/json' \
  --data '{
      "product_feed": {
          "url": "http://some/feed/file.xml"
      }
  }'

The above command returns a JSON document structured like this:

{
  "product_feed": {
    "id": 42,
    "group_id": 1,
    "url": "http://some/feed/file.xml",
    "state": "processing",
    "success_count": 0,
    "failed_count": 0
  }
}

URL Parameters

Parameter Description
Group ID The ID of a specific group

Request body parameters

The following fields need to be sent within a product feed scope (see the right panel for an example):

Name Type Required Description
url String Yes URL of the feed file to upload. HTTP, HTTPS, FTP and SFTP are accepted, and it needs to be a publicly accessible file

Response codes

Code Description
201 Created - Product feed import scheduled
409 Conflict - A product feed import is already in progress
412 Precondition Failed - url is missing or empty

Retrieve a product feed

Returns a single product feed import record belonging to the given group.

curl "https://api.publitas.com/v2/groups/1/product_feeds/28" \
  -H "Authorization: ApiKey <api_key>"

The above command returns a JSON document structured like this:

{
  "product_feed": {
    "id": 28,
    "group_id": 1,
    "url": "http://some/feed/file.xml",
    "state": "success",
    "success_count": 1891,
    "failed_count": 0
  }
}

HTTP Request

GET https://api.publitas.com/v2/groups/<Group ID>/product_feeds/<Product Feed ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Product Feed ID The ID of the product feed import to retrieve

Response codes

Code Description
200 OK - Product feed returned
403 Forbidden - Invalid API key or insufficient permissions
404 Not Found - Product feed does not exist in the given group

Update a product feed

Changes the group's product feed URL and schedules a new import. A successful update creates a new import record with a new ID.

HTTP Request

PATCH https://api.publitas.com/v2/groups/<Group ID>/product_feeds/<Product Feed ID>

curl "https://api.publitas.com/v2/groups/1/product_feeds/28" \
  -H "Authorization: ApiKey <api_key>" \
  -H "Content-Type: application/json" \
  -X PATCH \
  --data '{
      "product_feed": {
          "url": "http://some/new/feed/file.xml"
      }
  }'

The above command returns a JSON document structured like this:

{
  "product_feed": {
    "id": 43,
    "group_id": 1,
    "url": "http://some/new/feed/file.xml",
    "state": "scheduled",
    "success_count": null,
    "failed_count": null
  }
}

URL Parameters

Parameter Description
Group ID The ID of a specific group
Product Feed ID The ID of an existing product feed import

Request body parameters

The following fields need to be sent within a product feed scope (see the right panel for an example):

Name Type Required Description
url String Yes URL of the feed file to upload. HTTP, HTTPS, FTP and SFTP are accepted, and it needs to be a publicly accessible file

Response codes

Code Description
200 OK - Product feed updated and a new import scheduled
403 Forbidden - Invalid API key or insufficient permissions
404 Not Found - Product feed does not exist in the given group
409 Conflict - A product feed import is already in progress
412 Precondition Failed - url is missing or empty

Delete a product feed

Clears the group's product feed configuration, removes all import records, and enqueues a cleanup of the group's products.

HTTP Request

DELETE https://api.publitas.com/v2/groups/<Group ID>/product_feeds/<Product Feed ID>

curl "https://api.publitas.com/v2/groups/1/product_feeds/28" \
  -H "Authorization: ApiKey <api_key>" \
  -X DELETE

URL Parameters

Parameter Description
Group ID The ID of a specific group
Product Feed ID The ID of an existing product feed import

Response codes

Code Description
204 No Content - Product feed successfully removed
403 Forbidden - Invalid API key or insufficient permissions
404 Not Found - Product feed does not exist in the given group

Conversions

List last conversions

List last 5 conversions of a publication

curl "https://api.publitas.com/v2/groups/1/publications/222/conversions/" \
  -H "Authorization: ApiKey <api_key>"

The above command returns a JSON document structured like this:

{
  "conversions": [
    {
      "id": 1404,
      "group_id": 1,
      "publication_id": 222,
      "state": "finished",
      "state_details": null,
      "source_type": "api_add_pages",
      "total_pages": 110,
      "converted_pages": 110,
      "extraction_options": null
    },
    {
      "id": 1403,
      "group_id": 1,
      "publication_id": 222,
      "state": "failed",
      "state_details": {
        "error": "Fail to download given source file: https://some/pdf/file.pdf"
      },
      "source_type": "api_add_pages",
      "total_pages": null,
      "converted_pages": 0,
      "extraction_options": null
    },
    {
      "id": 1402,
      "group_id": 1,
      "publication_id": 222,
      "state": "finished",
      "state_details": null,
      "source_type": "api_replace_page",
      "total_pages": 100,
      "converted_pages": 1,
      "extraction_options": null
    },
    {
      "id": 1401,
      "group_id": 1,
      "publication_id": 222,
      "state": "finished",
      "state_details": null,
      "source_type": "page_manager",
      "total_pages": 100,
      "converted_pages": 2,
      "extraction_options": null
    },
    {
      "id": 1400,
      "group_id": 1,
      "publication_id": 222,
      "state": "finished",
      "state_details": null,
      "source_type": "new_publication",
      "total_pages": 100,
      "converted_pages": 100,
      "extraction_options": null
    }
  ]
}

URL Parameters

Parameter Description
Group ID The ID of a specific group
Publication ID The ID of a specific publication

The JSON response returns a list of publications with the following attributes:

Field Type Description
id Integer Conversion ID
group_id Integer Group ID
publication_id Integer Publication ID
state String The conversion state (see table below for a better description)
state_details Object Additional info about conversion state (see object structure on section bellow)
source_type String Action which has create the conversion
total_pages Integer Total of pages to be processed in the conversion
converted_pages Integer Count of pages already processed in the conversion
extraction_options Object Conversion hotspots extraction settings. See extraction options

The state field can have one of the following values:

Value Description
new Conversion waiting to be processed
preparing PDF source file is being download
converting PDF pages being converted to publication page
finished Conversion process finished
canceled Conversion process canceled
failed Conversion process failed

The state_details is object with the following attributes:

Value Type Description
error String Error message describing conversion failed state

Get a specific conversion

# This endpoint retrieves a specific publication conversion.
curl -H "Authorization: ApiKey <api_key>" "https://api.publitas.com/v2/groups/1/publications/222/conversion/1404"

The above command returns JSON structured like this:

{
  "conversion": {
    "id": 1404,
    "group_id": 1,
    "publication_id": 222,
    "state": "finished",
    "state_details": null,
    "source_type": "api_add_pages",
    "total_pages": 110,
    "converted_pages": 110,
    "extraction_options": null
  }
}

HTTP Request

GET https://api.publitas.com/v2/groups/<Group ID>/publications/<Publication ID>

URL Parameters

Parameter Description
Group ID The ID of a specific group
Publication ID The ID of a specific publication
Conversion ID The ID of a specific conversion

Languages

Name Code
Basque eu
Bulgarian bg
Chinese zh
Croatian hr
Czech cs
Danish da
Dutch nl
English en
French fr
Finnish fi
German de
Hungarian hu
Italian it
Lithuanian lt
Norwegian no
Polish pl
Portuguese pt
Romanian ro
Russian ru
Serbian sr
Slovak sk
Spanish es
Swedish sv
Turkish tr
Ukranian uk

Extraction Options

The following fields define options to extract hotspots from a PDF

Extraction options field JSON object structured like this:

{
  "extraction_options": {
    "links": { "icons": true },
    "products": { "icons": false }
  }
}
Name Type Required Description
links Object No Extracts link hotspots for any URL, document link, and email address found in PDF file (see object definition table below)
products Object No Extracts product hotspots for any SKU found in PDF file, matching product feed or product library set (see object definition table below)

Both 'links' and 'products' allow the fields below:

Name Type Required Description
icons Boolean No Show or hide hotspot icons for extracted hotspot. This setting is not applicable to hotspots extracted from PDF annotations (those are defined in the annotation itself)

Hotspot Endpoints

Hotspots are interactive areas placed on spread pages. Each hotspot has a type that determines its behavior and the additional fields returned in the response. All coordinates and dimensions are expressed as a fraction of the spread size (values between 0 and 1).

List all hotspots of a spread

curl "https://api.publitas.com/v2/spreads/42/hotspots" \
  -H "Authorization: ApiKey <api_key>"

The above command returns JSON structured like this:

{
  "hotspots": [
    {
      "id": 1,
      "type": "external_link",
      "top": 0.1,
      "left": 0.2,
      "width": 0.15,
      "height": 0.08,
      "icon_left": 0.5,
      "icon_top": 0.5,
      "show_indication": true,
      "tab_index": null,
      "z_index": 0,
      "embedded_content": false,
      "dynamic": false,
      "product_theme_id": null,
      "rotation": 0.0,
      "url": "https://example.com",
      "popup_max_width": null,
      "popup_max_height": null
    }
  ]
}

HTTP Request

GET https://api.publitas.com/v2/spreads/<Spread ID>/hotspots

URL Parameters

Parameter Description
Spread ID The ID of a specific spread

This endpoint supports pagination. Results are ordered by page number.

Response fields

The response returns an array of hotspot objects. All hotspot types share the following base fields:

Field Type Description
id Integer Hotspot ID
type String Hotspot type (see below)
top Float Top offset as a fraction of spread height (0–1)
left Float Left offset as a fraction of spread width (0–1)
width Float Width as a fraction of spread width (0–1)
height Float Height as a fraction of spread height (0–1)
icon_left Float Horizontal center of the hotspot icon (0–1)
icon_top Float Vertical center of the hotspot icon (0–1)
show_indication Boolean Whether the hotspot indication icon is visible
tab_index Integer/null Accessibility tab order
z_index Integer Stacking order relative to other hotspots on the spread
embedded_content Boolean Whether the hotspot renders its content inline
dynamic Boolean true shows a full product card overlay; false acts as a transparent link
product_theme_id Integer/null Product theme ID for product-type hotspots
rotation Float Rotation in degrees

Additional fields are included depending on type:

external_link

Field Type Description
url String Target URL
popup_max_width Integer/null Maximum popup width in pixels
popup_max_height Integer/null Maximum popup height in pixels

page_reference

Field Type Description
page_number Integer Publication page number to link to

video

Field Type Description
video_id String/null Video ID (for hosted providers)
video_provider String/null Video provider (e.g. youtube, vimeo)
video_url String/null Direct video URL or file path
video_type String/null Video type
video_autoplay Boolean Whether the video autoplays on open
video_show_preview Boolean/null Whether a preview thumbnail is shown
video_loop Boolean Whether the video loops
video_start_time Integer/null Start time in seconds
video_overlay_content Boolean Whether the video overlays other content
video_show_accessibility_controls Boolean Whether accessibility controls are shown
accessibility_text String/null Accessible label for the video

image

Field Type Description
url String Image URL
image_alt_text String/null Alt text for the image
content_fit_mode String/null How the image is fitted (cover, contain, etc.)
image_show_lightbox Boolean Whether clicking opens the image in a lightbox
show_tooltip Boolean Whether to show a tooltip
corner_radius Integer/null Corner radius in pixels
opacity Float/null Opacity (0–1)
image_crop_state Object/null Crop state metadata
style_json Object/null Custom style overrides
background_color String/null Background color (hex); null when disabled

slideshow

Field Type Description
slides Array Array of slide objects (see below)

Each slide object contains:

Field Type Description
id Integer Slide ID
hotspot_id Integer Parent hotspot ID
position Integer Display order
url String/null External image URL
file_path String/null Hosted file path
file_hosted Boolean Whether the file is hosted
file_url String/null Absolute URL to the hosted file
original_filename String/null Original upload filename
alt_text String/null Accessible alt text for the slide

product

Field Type Description
products Array Array of product objects serialized via the V2 Product schema

Get a specific hotspot

curl "https://api.publitas.com/v2/spreads/42/hotspots/1" \
  -H "Authorization: ApiKey <api_key>"

The above command returns JSON structured like this:

{
  "hotspot": {
    "id": 1,
    "type": "external_link",
    "top": 0.1,
    "left": 0.2,
    "width": 0.15,
    "height": 0.08,
    "icon_left": 0.5,
    "icon_top": 0.5,
    "show_indication": true,
    "tab_index": null,
    "z_index": 0,
    "embedded_content": false,
    "dynamic": false,
    "product_theme_id": null,
    "rotation": 0.0,
    "url": "https://example.com",
    "popup_max_width": null,
    "popup_max_height": null
  }
}

HTTP Request

GET https://api.publitas.com/v2/spreads/<Spread ID>/hotspots/<Hotspot ID>

URL Parameters

Parameter Description
Spread ID The ID of a specific spread
Hotspot ID The ID of a specific hotspot

Returns 404 if the hotspot does not exist on the requested spread or belongs to a different spread.

Create a hotspot

curl "https://api.publitas.com/v2/spreads/42/hotspots" \
  -H "Authorization: ApiKey <api_key>" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "external_link",
    "top": 0.1,
    "left": 0.2,
    "width": 0.15,
    "height": 0.08,
    "url": "https://example.com"
  }'

The above command returns JSON structured like this:

{
  "hotspot": {
    "id": 99,
    "type": "external_link",
    "top": 0.1,
    "left": 0.2,
    "width": 0.15,
    "height": 0.08,
    "icon_left": 0.5,
    "icon_top": 0.5,
    "show_indication": true,
    "tab_index": null,
    "z_index": 0,
    "embedded_content": false,
    "dynamic": false,
    "product_theme_id": null,
    "rotation": 0.0,
    "url": "https://example.com",
    "popup_max_width": null,
    "popup_max_height": null
  }
}

HTTP Request

POST https://api.publitas.com/v2/spreads/<Spread ID>/hotspots

URL Parameters

Parameter Description
Spread ID The ID of a specific spread

Request body parameters

Core fields (all types)

Field Type Required Description
type String Yes Hotspot type: external_link, page_reference, video, image, slideshow, or product
top Float Yes Top offset as a fraction of spread height (0–1)
left Float Yes Left offset as a fraction of spread width (0–1)
width Float Yes Width as a fraction of spread width (0–1)
height Float Yes Height as a fraction of spread height (0–1)
show_indication Boolean No Whether the hotspot indication icon is visible
tab_index Integer No Accessibility tab order
embedded_content Boolean No Whether the hotspot renders its content inline

external_link fields

Field Type Required Description
url String Yes Target URL
popup_max_width Integer No Maximum popup width in pixels
popup_max_height Integer No Maximum popup height in pixels

page_reference fields

Field Type Required Description
page_number Integer Yes Publication page number to link to

video fields

Field Type Required Description
video_url String Yes Video URL or file path
video_type String No Video type
video_provider String No Video provider (e.g. youtube, vimeo)
video_autoplay Boolean No Whether the video autoplays on open
video_loop Boolean No Whether the video loops
video_show_preview Boolean No Whether a preview thumbnail is shown
video_start_time Integer No Start time in seconds
video_overlay_content Boolean No Whether the video overlays other content
video_show_accessibility_controls Boolean No Whether accessibility controls are shown
accessibility_text String No Accessible label for the video

image fields

Field Type Required Description
url String Yes Image URL
image_alt_text String No Alt text for the image
image_add_alt_text Boolean No Whether to include alt text in the response
content_fit_mode String No How the image is fitted (cover, contain, etc.)
image_show_lightbox Boolean No Whether clicking opens the image in a lightbox
show_tooltip Boolean No Whether to show a tooltip
corner_radius Integer No Corner radius in pixels
opacity Float No Opacity (0–1)

Response codes

Code Description
201 Hotspot created successfully
422 Validation errors in request body

Errors

When there is an error the command returns JSON structured like this:

{
  "errors": {
    "state": ["You have reached your publication limit"]
  }
}

The Publitas API uses the following error codes:

Error Code Meaning
402 Payment Required -- You have reached your publishing limit
403 Forbidden -- You requested access to a resource which you don't have permission
404 Not Found -- The path or document could not be found
405 Method Not Allowed -- You tried to access the API with an invalid method
406 Not Acceptable -- You requested a format that isn't json
418 I'm a teapot
422 Unprocessable Entity -- We found validation errors on one or more fields, a detailed error message can be found in the response body
500 Internal Server Error -- We had a problem with our server. Try again later
503 Service Unavailable -- We're temporarially offline for maintenance. Please try again later