Import API

Introduction

The PressMatrix Import API enables publishers to create, update, fetch, list and delete digital issues for the PressMatrix Kiosk. It supports standard PDF imports, planned PDF imports and EPUB imports.

The base URL is:

https://pegasus.pressmatrix.com/api/v2/importer

OpenAPI Specification

Download OpenAPI YAML

You can view the spec with Swagger Editor.

Example Postman Collection

Download a postman collection to test the API.

Download the Postman collection.

Authentication

All endpoints require token-based authentication via the Authorization header.

Authorization Header

Authorization: Token {TOKEN_GENERATED_BY_PMX}

Overview

The API exposes these endpoint groups:

Emags
- GET /organizations/{organization_id}/publications/{publication_id}/emags
- POST /organizations/{organization_id}/publications/{publication_id}/emags
- GET /organizations/{organization_id}/publications/{publication_id}/emags/{emag_id}
- PUT /organizations/{organization_id}/publications/{publication_id}/emags/{emag_id}
- DELETE /organizations/{organization_id}/publications/{publication_id}/emags/{emag_id}
Planned Emags
- GET /organizations/{organization_id}/publications/{publication_id}/planned_emags
- GET /organizations/{organization_id}/publications/{publication_id}/planned_emags/{planned_emag_id}

Name
organization_id
Type
integer
Description
PressMatrix organization ID.
Name
publication_id
Type
integer
Description
PressMatrix publication ID.
Name
emag_id
Type
integer
Description
Emag ID.
Name
planned_emag_id
Type
integer
Description
Planned emag ID.
Name
page
Type
integer
Description
Optional page number for paginated list endpoints. Minimum is 1.
Name
per
Type
integer
Description
Optional number of items per page for paginated list endpoints. Minimum is 1.

Import modes and status fields

Only one of import_attributes or epub_import_attributes is allowed per request.

There are three relevant import variants:

Standard PDF import: use import_attributes without pe_id
Planned PDF import: use import_attributes together with pe_id
EPUB import: use epub_import_attributes

The response uses different import status fields depending on the import mode:

Name
import.status
Type
enum
Description
Used for standard PDF imports without pe_id.
Name
import.ai_status
Type
enum
Description
Used for planned PDF imports and EPUB imports.

Supported enum values for both fields are:

Import status enum

pending
processing
finished
failed

POST/organizations/{organization_id}/publications/{publication_id}/emags

Create emag

Creates a new emag.

The response now always returns the full emag object.

Name
name
Type
string
Description
Name of the issue. Must be unique within the publication.
Name
released_at
Type
string
Description
Date and time from which the issue is visible.
Name
pe_id
Type
string
Description
Planned edition identifier. Only relevant for planned imports.
Name
preview
Type
string
Description
Short description shown in the kiosk details screen.
Name
apple_product_identifier
Type
string
Description
Identifier for Apple App Store.
Name
google_product_id
Type
string
Description
Identifier for Google Play.
Name
external_id
Type
string
Description
External issue identifier.
Name
hide_preview_widgets
Type
boolean
Description
Hides preview widgets when set to true.
Name
single_purchase_required
Type
boolean
Description
Whether single purchase is required.
Name
for_subscribers_only
Type
boolean
Description
Whether the issue is available only to subscribers.
Name
cents
Type
integer
Description
Price in cents.
Name
currency
Type
string
Description
ISO 4217 currency code, for example EUR.
Name
text_mode_enabled
Type
boolean
Description
Enables text mode.
Name
language
Type
string
Description
Language code, for example de.
Name
category_ids
Type
array
Description
Array of category IDs.
Name
import_attributes
Type
object
Description
PDF import configuration.
- import_images (boolean)
- pdf_location (string, required)
- xml_location (string, optional)
Name
epub_import_attributes
Type
object
Description
EPUB import configuration.
- import_articles (boolean)
- import_images (boolean)
- pdf_location (string, required)
- epub_location (string, required)

Standard PDF import example

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/emags' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "name": "Generic PDF Issue",
      "released_at": "2026-07-10T12:00:00.000Z",
      "preview": "Generic short description for kiosk details.",
      "apple_product_identifier": "com.example.kiosk.issue_generic_pdf",
      "google_product_id": "com.example.kiosk.issue_generic_pdf",
      "external_id": "ISSUE-GENERIC-PDF",
      "hide_preview_widgets": false,
      "single_purchase_required": false,
      "for_subscribers_only": false,
      "cents": 199,
      "currency": "EUR",
      "text_mode_enabled": true,
      "language": "de",
      "category_ids": [],
      "import_attributes": {
        "import_images": true,
        "pdf_location": "https://cdn.example.com/issues/generic/issue.pdf",
        "xml_location": "https://cdn.example.com/issues/generic/issue.xml"
      }
    }
  }'

Planned PDF import example

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/emags' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "name": "Generic Planned Issue",
      "released_at": "2026-07-10T12:00:00.000Z",
      "pe_id": "PUBCODE_20260710",
      "preview": "Generic planned import preview.",
      "apple_product_identifier": "com.example.kiosk.issue_generic_planned",
      "google_product_id": "com.example.kiosk.issue_generic_planned",
      "external_id": "ISSUE-GENERIC-PLANNED",
      "hide_preview_widgets": false,
      "single_purchase_required": false,
      "for_subscribers_only": false,
      "cents": 199,
      "currency": "EUR",
      "text_mode_enabled": true,
      "language": "de",
      "category_ids": [],
      "import_attributes": {
        "import_images": true,
        "pdf_location": "https://cdn.example.com/issues/generic/issue.pdf"
      }
    }
  }'

EPUB import example

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/emags' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "name": "Generic EPUB Issue",
      "released_at": "2026-07-10T12:00:00.000Z",
      "preview": "Generic EPUB import preview.",
      "apple_product_identifier": "com.example.kiosk.issue_generic_epub",
      "google_product_id": "com.example.kiosk.issue_generic_epub",
      "external_id": "ISSUE-GENERIC-EPUB",
      "hide_preview_widgets": false,
      "single_purchase_required": false,
      "for_subscribers_only": false,
      "cents": 199,
      "currency": "EUR",
      "text_mode_enabled": true,
      "language": "de",
      "category_ids": [],
      "epub_import_attributes": {
        "import_articles": true,
        "import_images": true,
        "pdf_location": "https://cdn.example.com/issues/generic/issue.pdf",
        "epub_location": "https://cdn.example.com/issues/generic/issue.epub"
      }
    }
  }'

Success response example

{
  "emag": {
    "id": 1001,
    "created_at": "2026-01-22T12:41:00.000Z",
    "updated_at": "2026-03-20T12:49:42.000Z",
    "name": "Generic PDF Issue",
    "released_at": "2026-07-10T12:00:00.000Z",
    "preview": "Generic short description for kiosk details.",
    "apple_product_identifier": "com.example.kiosk.issue_generic_pdf",
    "google_product_id": "com.example.kiosk.issue_generic_pdf",
    "external_id": "ISSUE-GENERIC-PDF",
    "hide_preview_widgets": false,
    "single_purchase_required": false,
    "for_subscribers_only": false,
    "cents": 199,
    "currency": "EUR",
    "text_mode_enabled": true,
    "language": "de",
    "pe_id": null,
    "category_ids": [],
    "import": {
      "status": "finished"
    },
    "import_attributes": {
      "import_images": true,
      "pdf_location": "https://cdn.example.com/issues/generic/issue.pdf",
      "xml_location": "https://cdn.example.com/issues/generic/issue.xml"
    }
  }
}

Failure response example

{
  "name": [
    "has already been taken"
  ]
}

PUT/organizations/{organization_id}/publications/{publication_id}/emags/{emag_id}

Update emag

Updates an existing emag.

If new file URLs are provided, the existing import data is replaced and a new import starts.

You cannot switch an existing emag from PDF import to EPUB import or from EPUB import to PDF import via PUT.

The response now always returns the full emag object.

Minimal update example

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/emags/{emag_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "name": "Updated Generic Issue"
    }
  }'

Reimport PDF example

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/emags/{emag_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "import_attributes": {
        "import_images": false,
        "pdf_location": "https://cdn.example.com/issues/generic/issue-v2.pdf",
        "xml_location": "https://cdn.example.com/issues/generic/issue-v2.xml"
      }
    }
  }'

Update EPUB files example

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/emags/{emag_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "emag": {
      "epub_import_attributes": {
        "pdf_location": "https://cdn.example.com/issues/generic/issue-v2.pdf",
        "epub_location": "https://cdn.example.com/issues/generic/issue-v2.epub"
      }
    }
  }'

Success response example

{
  "emag": {
    "id": 1001,
    "created_at": "2026-01-22T12:41:00.000Z",
    "updated_at": "2026-03-20T12:49:42.000Z",
    "name": "Updated Generic Issue",
    "released_at": "2026-07-10T12:00:00.000Z",
    "preview": "Updated generic short description.",
    "apple_product_identifier": "com.example.kiosk.issue_generic_pdf",
    "google_product_id": "com.example.kiosk.issue_generic_pdf",
    "external_id": "ISSUE-GENERIC-PDF-UPDATED",
    "hide_preview_widgets": true,
    "single_purchase_required": false,
    "for_subscribers_only": false,
    "cents": 299,
    "currency": "EUR",
    "text_mode_enabled": false,
    "language": "de",
    "pe_id": null,
    "category_ids": [],
    "import": {
      "status": "finished"
    },
    "import_attributes": {
      "import_images": false,
      "pdf_location": "https://cdn.example.com/issues/generic/issue-v2.pdf",
      "xml_location": "https://cdn.example.com/issues/generic/issue-v2.xml"
    }
  }
}

Failure response example

{
  "name": [
    "has already been taken"
  ]
}

GET/organizations/{organization_id}/publications/{publication_id}/emags

List emags

Returns a paginated list of emags.

Name
page
Type
integer
Description
Optional page number.
Name
per
Type
integer
Description
Optional items per page.

List emags example

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/emags?page=1&per=2' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}'

Response example

{
  "emags": [
    {
      "id": 1001,
      "created_at": "2026-01-22T12:31:54.000Z",
      "updated_at": "2026-03-06T14:45:12.000Z",
      "name": "Generic PDF Issue",
      "released_at": "2026-01-21T00:00:00.000Z",
      "preview": "Generic preview text.",
      "apple_product_identifier": null,
      "google_product_id": null,
      "external_id": "ISSUE-001",
      "hide_preview_widgets": false,
      "single_purchase_required": false,
      "for_subscribers_only": false,
      "cents": 199,
      "currency": "EUR",
      "text_mode_enabled": false,
      "language": "de",
      "pe_id": "PUBCODE_20260121",
      "category_ids": [],
      "import": {
        "status": "finished"
      },
      "import_attributes": {
        "import_images": false,
        "pdf_location": "https://cdn.example.com/issues/generic/issue-001.pdf",
        "xml_location": null
      }
    },
    {
      "id": 1002,
      "created_at": "2025-11-06T09:24:34.000Z",
      "updated_at": "2026-01-21T08:23:31.000Z",
      "name": "Generic EPUB Issue",
      "released_at": "2025-11-30T23:00:00.000Z",
      "preview": "Generic EPUB preview text.",
      "apple_product_identifier": null,
      "google_product_id": null,
      "external_id": "ISSUE-002",
      "hide_preview_widgets": false,
      "single_purchase_required": false,
      "for_subscribers_only": null,
      "cents": 199,
      "currency": "EUR",
      "text_mode_enabled": true,
      "language": "de",
      "pe_id": null,
      "category_ids": [],
      "import": {
        "ai_status": "processing"
      },
      "epub_import_attributes": {
        "import_articles": true,
        "import_images": true,
        "pdf_location": "https://cdn.example.com/issues/generic/issue-002.pdf",
        "epub_location": "https://cdn.example.com/issues/generic/issue-002.epub"
      }
    }
  ],
  "current_page": 1,
  "total_pages": 12,
  "total_count": 24,
  "per_page": 2,
  "next_page": 2,
  "prev_page": null
}

GET/organizations/{organization_id}/publications/{publication_id}/emags/{emag_id}

Get single emag

Returns one emag by ID.

Get single emag example

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/emags/{emag_id}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}'

Response example

{
  "emag": {
    "id": 1001,
    "created_at": "2026-01-22T12:41:00.000Z",
    "updated_at": "2026-03-20T12:49:42.000Z",
    "name": "Generic PDF Issue",
    "released_at": "2026-07-10T12:00:00.000Z",
    "preview": "Generic short description for kiosk details.",
    "apple_product_identifier": "com.example.kiosk.issue_generic_pdf",
    "google_product_id": "com.example.kiosk.issue_generic_pdf",
    "external_id": "ISSUE-GENERIC-PDF",
    "hide_preview_widgets": false,
    "single_purchase_required": false,
    "for_subscribers_only": false,
    "cents": 199,
    "currency": "EUR",
    "text_mode_enabled": true,
    "language": "de",
    "pe_id": null,
    "category_ids": [],
    "import": {
      "status": "finished"
    },
    "import_attributes": {
      "import_images": true,
      "pdf_location": "https://cdn.example.com/issues/generic/issue.pdf",
      "xml_location": "https://cdn.example.com/issues/generic/issue.xml"
    }
  }
}

DELETE/organizations/{organization_id}/publications/{publication_id}/emags/{emag_id}

Delete emag

Deletes an emag.

On success the API returns 204 No Content.

If the emag does not exist, the API returns 404 Not Found.

Delete emag example

curl --location --request DELETE 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/emags/{emag_id}' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}'

Success response

HTTP/1.1 204 No Content

Not found response

HTTP/1.1 404 Not Found

GET/organizations/{organization_id}/publications/{publication_id}/planned_emags

List planned emags

Returns a paginated list of planned emags.

Name
page
Type
integer
Description
Optional page number.
Name
per
Type
integer
Description
Optional items per page.

List planned emags example

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/planned_emags?page=1&per=2' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}'

Response example

{
  "planned_emags": [
    {
      "id": 2001,
      "publication_id": 3001,
      "emag_id": null,
      "name": "Generic Planned Slot 1",
      "release_date": "2026-03-15T11:40:00.000Z",
      "pubcode": "PUBCODE",
      "status": "planned",
      "pe_id": "PUBCODE_20260315"
    },
    {
      "id": 2002,
      "publication_id": 3001,
      "emag_id": 1001,
      "name": "Generic Planned Slot 2",
      "release_date": "2026-03-01T07:40:00.000Z",
      "pubcode": "PUBCODE",
      "status": "transferred",
      "pe_id": "PUBCODE_20260301"
    }
  ],
  "current_page": 1,
  "total_pages": 5,
  "total_count": 10,
  "per_page": 2,
  "next_page": 2,
  "prev_page": null
}

GET/organizations/{organization_id}/publications/{publication_id}/planned_emags/{planned_emag_id}

Get single planned emag

Returns one planned emag by ID.

Get single planned emag example

curl --location 'https://pegasus.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/planned_emags/{planned_emag_id}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}'

Response example

{
  "planned_emag": {
    "id": 2001,
    "publication_id": 3001,
    "emag_id": null,
    "name": "Generic Planned Slot 1",
    "release_date": "2026-03-15T11:40:00.000Z",
    "pubcode": "PUBCODE",
    "status": "planned",
    "pe_id": "PUBCODE_20260315"
  }
}