Article Import API

Introduction

The PressMatrix Article Import API enables publishers to create, update, list, retrieve, delete, and publish article-based content for a publication. The technical endpoint resource is named stories, and request/response bodies use the story envelope.

The base URL is:

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

OpenAPI Specification

Download OpenAPI YAML

You can view the spec with Swagger Editor.

Authentication

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

Authorization Header

Authorization: Token {TOKEN_GENERATED_BY_PMX}

Overview

The API exposes these endpoints:

GET /organizations/{organization_id}/publications/{publication_id}/stories
POST /organizations/{organization_id}/publications/{publication_id}/stories
GET /organizations/{organization_id}/publications/{publication_id}/stories/{story_id}
PUT /organizations/{organization_id}/publications/{publication_id}/stories/{story_id}
PATCH /organizations/{organization_id}/publications/{publication_id}/stories/{story_id}
DELETE /organizations/{organization_id}/publications/{publication_id}/stories/{story_id}
POST /organizations/{organization_id}/publications/{publication_id}/stories/{story_id}/publish
GET /organizations/{organization_id}/publications/{publication_id}/article_categories
POST /organizations/{organization_id}/publications/{publication_id}/article_categories
PUT /organizations/{organization_id}/publications/{publication_id}/article_categories/{article_category_id}
PATCH /organizations/{organization_id}/publications/{publication_id}/article_categories/{article_category_id}

Name
organization_id
Type
integer
Description
PressMatrix organization ID.
Name
publication_id
Type
integer
Description
PressMatrix publication ID.
Name
story_id
Type
integer
Description
Article ID in the technical stories resource.
Name
article_category_id
Type
integer
Description
Article category ID for the publication.
Name
page
Type
integer
Description
Optional page number for paginated list endpoints.
Name
per
Type
integer
Description
Optional number of items per page.

Article fields

Name
name
Type
string
Description
Internal article name. Required when creating an article.
Name
title
Type
string
Description
Article title shown to readers.
Name
preview
Type
string
Description
Short article summary.
Name
content
Type
string
Description
Article body in Markdown.
Name
external_id
Type
string
Description
Customer-provided identifier. List filters use partial matching.
Name
released_at
Type
string
Description
ISO 8601 date and time from which the article is visible.
Name
language
Type
string
Description
Two-letter language code, for example de.
Name
cents
Type
integer
Description
Price in the smallest currency unit.
Name
currency
Type
string
Description
ISO 4217 currency code, for example EUR.
Name
article_category_ids
Type
integer[]
Description
Category IDs assigned to the article. The field is always returned by article lists, single-article responses, and successful updates.
Name
image
Type
file
Description
Optional image upload via multipart/form-data. Supported MIME types are JPEG, PNG, and GIF. Maximum file size is 5 MB.

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

Create article

Creates a new article. Use JSON for metadata-only articles, or multipart/form-data when uploading an image.

Article categories cannot be assigned when creating an article. Create the article with POST /stories first, then assign categories with PUT or PATCH /stories/{story_id}.

Malformed JSON or a missing story envelope returns 400.

JSON request

curl --location 'https://editor.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/stories' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "story": {
      "name": "Example Article",
      "title": "Example Article",
      "preview": "Short article summary.",
      "content": "# Example Article\n\nArticle body in Markdown.",
      "external_id": "article-001",
      "released_at": "2026-07-10T12:00:00Z",
      "cents": 199,
      "currency": "EUR",
      "language": "de",
      "subscription_required": false,
      "purchase_required": false
    }
  }'

Multipart request

curl --location 'https://editor.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/stories' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --form 'story[name]="Example Article"' \
  --form 'story[title]="Example Article"' \
  --form 'story[released_at]="2026-07-10T12:00:00Z"' \
  --form 'story[cents]="199"' \
  --form 'story[currency]="EUR"' \
  --form 'story[language]="de"' \
  --form 'story[image]=@article-image.png'

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

List articles

Returns a paginated list of articles for the publication.

Name
from
Type
string
Description
Return articles created on or after this ISO 8601 timestamp.
Name
to
Type
string
Description
Return articles created on or before this ISO 8601 timestamp.
Name
external_id
Type
string
Description
Filter by a single external ID value or a comma-separated list of values. Each value is matched partially.
Name
search
Type
string
Description
Search across title, content, and product identifiers.

Request

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

PATCH/organizations/{organization_id}/publications/{publication_id}/stories/{story_id}

Update article

Use PATCH to update selected article fields. Use PUT when replacing the full set of article attributes.

Creating an article and assigning categories requires two requests:

Create the article with POST /stories.
Assign categories with PUT or PATCH /stories/{story_id}.

Category IDs must belong to the current publication. An empty array removes all assignments. Unknown IDs and non-integer array elements return 422; a non-array value returns 400.

Patch request

curl --request PATCH 'https://editor.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/stories/{story_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "story": {
      "title": "Updated Example Article",
      "preview": "Updated article summary.",
      "purchase_required": true
    }
  }'

Assign categories

curl --request PATCH 'https://editor.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/stories/{story_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "story": {
      "article_category_ids": [{article_category_id}]
    }
  }'

Clear categories

curl --request PATCH 'https://editor.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/stories/{story_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "story": {
      "article_category_ids": []
    }
  }'

Article categories

Article categories belong to a publication. List responses use the article_categories envelope; successful create and update responses use article_category.

Name
id
Type
integer
Description
Article category ID.
Name
name
Type
string
Description
Non-empty, human-readable category name.
Name
parent_id
Type
integer | null
Description
Writable ID of the immediate parent category. null moves the category to the root level.
Name
position
Type
integer
Description
1-indexed position among categories with the same parent. Request values must be positive integers.
Name
parent_ids
Type
integer[]
Description
Read-only full ancestor chain from the root to the immediate parent. The array is empty for a root category.
Name
created_at
Type
string
Description
Creation timestamp in ISO 8601 format.
Name
updated_at
Type
string
Description
Last update timestamp in ISO 8601 format.

Malformed JSON returns 400. A missing name on create returns 400. A blank name, an invalid parent_id, or a position that is not a positive JSON integer returns 422. Invalid position values are not normalized. An unknown category ID on update returns 404.

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

List article categories

Returns all article categories for the publication.

Request

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

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

Create article category

Creates an article category. The example uses the simpler flat request. The nested form {"article_category":{"name":"Sports"}} is also supported. With parent_id, the category is appended to that parent's children. Without parent_id, a positive position can set its place among root categories. If both fields are sent on create, position is ignored.

Request

curl --request POST 'https://editor.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/article_categories' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "name": "Sports"
  }'

PATCH/organizations/{organization_id}/publications/{publication_id}/article_categories/{article_category_id}

Update article category

Updates an article category's name, parent, or position. Both PUT and PATCH accept partial updates in flat and nested request forms.

If parent_id equals the current parent, position can be applied in the same request. If the parent actually changes, a position sent in the same request is ignored and the category is appended to the new sibling list. Changing both the parent and target position therefore requires two requests.

Set parent

Sets the immediate parent. The category is appended to the new sibling list. Use null to move it to the root level.

Patch request

curl --request PATCH 'https://editor.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/article_categories/{article_category_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "article_category": {
      "parent_id": 456
    }
  }'

Set position

Moves the category to position 2 within its current sibling list. The position must be a positive integer.

Patch request

curl --request PATCH 'https://editor.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/article_categories/{article_category_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "article_category": {
      "position": 2
    }
  }'

Parent + position

Sets the parent and position in one request. Both values take effect only when parent_id already matches the current parent. If the parent changes, position is ignored. To actually change both, set the parent first and the position in a second request.

Patch request

curl --request PATCH 'https://editor.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/article_categories/{article_category_id}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}' \
  --data '{
    "article_category": {
      "parent_id": 456,
      "position": 2
    }
  }'

POST/organizations/{organization_id}/publications/{publication_id}/stories/{story_id}/publish

Publish article

Publishes an article after all required fields and publishing prerequisites are satisfied.

Request

curl --request POST 'https://editor.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/stories/{story_id}/publish' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}'

DELETE/organizations/{organization_id}/publications/{publication_id}/stories/{story_id}

Delete article

Deletes an article from normal API responses.

Request

curl --request DELETE 'https://editor.pressmatrix.com/api/v2/importer/organizations/{organization_id}/publications/{publication_id}/stories/{story_id}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Token {TOKEN_GENERATED_BY_PMX}'