Article Import API

Einführung

Die PressMatrix Article Import API ermöglicht Publishern, artikelbasierte Inhalte für eine Publikation zu erstellen, zu aktualisieren, aufzulisten, abzurufen, zu löschen und zu veröffentlichen. Die technische Endpoint-Ressource heißt stories, und Requests sowie Responses verwenden den story-Envelope.

Die Basis-URL lautet:

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

OpenAPI-Spezifikation

OpenAPI YAML herunterladen

Die Spezifikation kann im Swagger Editor geöffnet werden.

Authentifizierung

Alle Endpunkte benötigen tokenbasierte Authentifizierung über den Authorization-Header.

Authorization-Header

Authorization: Token {TOKEN_GENERATED_BY_PMX}

Übersicht

Die API stellt diese Endpunkte bereit:

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
Artikel-ID in der technischen stories-Ressource.
Name
article_category_id
Type
integer
Description
Artikelkategorie-ID der Publikation.
Name
page
Type
integer
Description
Optionale Seitennummer für paginierte Listen-Endpunkte.
Name
per
Type
integer
Description
Optionale Anzahl von Einträgen pro Seite.

Artikelfelder

Name
name
Type
string
Description
Interner Artikelname. Beim Erstellen erforderlich.
Name
title
Type
string
Description
Artikeltitel, der Lesern angezeigt wird.
Name
preview
Type
string
Description
Kurze Artikelzusammenfassung.
Name
content
Type
string
Description
Artikelinhalt in Markdown.
Name
external_id
Type
string
Description
Kundenseitiger Identifier. Listenfilter verwenden Teiltreffer.
Name
released_at
Type
string
Description
Datum und Uhrzeit nach ISO 8601, ab denen der Artikel sichtbar ist.
Name
language
Type
string
Description
Zweistelliger Sprachcode, zum Beispiel de.
Name
cents
Type
integer
Description
Preis in der kleinsten Währungseinheit.
Name
currency
Type
string
Description
Währungscode nach ISO 4217, zum Beispiel EUR.
Name
article_category_ids
Type
integer[]
Description
Dem Artikel zugewiesene Kategorie-IDs. Das Feld wird in Artikellisten, Einzelartikel-Responses und erfolgreichen Update-Responses immer zurückgegeben.
Name
image
Type
file
Description
Optionaler Bild-Upload über multipart/form-data. Unterstützte MIME-Typen sind JPEG, PNG und GIF. Die maximale Dateigröße beträgt 5 MB.

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

Artikel erstellen

Erstellt einen neuen Artikel. JSON eignet sich für reine Metadaten-Artikel, multipart/form-data für Requests mit Bild-Upload.

Artikelkategorien können beim Erstellen nicht zugewiesen werden. Erstelle den Artikel zuerst mit POST /stories und weise Kategorien anschließend mit PUT oder PATCH /stories/{story_id} zu.

Fehlerhaftes JSON oder ein fehlender story-Envelope führt zu 400.

JSON-Anfrage

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

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

Artikel auflisten

Gibt eine paginierte Liste der Artikel einer Publikation zurück.

Name
from
Type
string
Description
Gibt Artikel zurück, die ab diesem ISO-8601-Zeitpunkt erstellt wurden.
Name
to
Type
string
Description
Gibt Artikel zurück, die bis zu diesem ISO-8601-Zeitpunkt erstellt wurden.
Name
external_id
Type
string
Description
Filtert nach einem einzelnen External-ID-Wert oder einer kommagetrennten Liste von Werten. Jeder Wert wird als Teiltreffer gesucht.
Name
search
Type
string
Description
Sucht in Titel, Inhalt und Product-Identifiern.

Anfrage

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}

Artikel aktualisieren

Verwende PATCH, um einzelne Artikelfelder zu aktualisieren. Verwende PUT, wenn der vollständige Satz von Artikelattributen ersetzt werden soll.

Das Erstellen eines Artikels und das Zuweisen von Kategorien erfordert zwei Requests:

Erstelle den Artikel mit POST /stories.
Weise Kategorien mit PUT oder PATCH /stories/{story_id} zu.

Kategorie-IDs müssen zur aktuellen Publikation gehören. Ein leeres Array entfernt alle Zuordnungen. Unbekannte IDs und nicht ganzzahlige Array-Einträge führen zu 422; ein Wert, der kein Array ist, führt zu 400.

Patch-Anfrage

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
    }
  }'

Kategorien zuweisen

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}]
    }
  }'

Kategorien entfernen

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": []
    }
  }'

Artikelkategorien

Artikelkategorien gehören zu einer Publikation. Listen-Responses verwenden den article_categories-Envelope; erfolgreiche Create- und Update-Responses verwenden article_category.

Name
id
Type
integer
Description
Artikelkategorie-ID.
Name
name
Type
string
Description
Nicht leerer, menschenlesbarer Kategoriename.
Name
parent_id
Type
integer | null
Description
Beschreibbare ID der direkt übergeordneten Kategorie. null verschiebt die Kategorie auf die oberste Ebene.
Name
position
Type
integer
Description
1-basierte Position unter den Kategorien mit demselben Parent. Request-Werte müssen positive Ganzzahlen sein.
Name
parent_ids
Type
integer[]
Description
Schreibgeschützte vollständige Ahnenkette von der obersten bis zur direkt übergeordneten Kategorie. Bei Kategorien auf der obersten Ebene ist das Array leer.
Name
created_at
Type
string
Description
Erstellungszeitpunkt im ISO-8601-Format.
Name
updated_at
Type
string
Description
Zeitpunkt der letzten Aktualisierung im ISO-8601-Format.

Fehlerhaftes JSON führt zu 400. Ein fehlender Name beim Erstellen führt zu 400. Ein leerer Name, eine ungültige parent_id oder eine position, die keine positive JSON-Ganzzahl ist, führt zu 422. Ungültige Positionswerte werden nicht normalisiert. Eine unbekannte Kategorie-ID beim Aktualisieren führt zu 404.

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

Artikelkategorien auflisten

Gibt alle Artikelkategorien der Publikation zurück.

Anfrage

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

Artikelkategorie erstellen

Erstellt eine Artikelkategorie. Das Beispiel verwendet den einfacheren flachen Request. Die verschachtelte Form {"article_category":{"name":"Sports"}} wird ebenfalls unterstützt. Mit parent_id wird die Kategorie am Ende der untergeordneten Kategorien dieses Parents angelegt. Ohne parent_id kann eine positive position die Position auf der obersten Ebene festlegen. Werden beim Erstellen beide Felder gesendet, wird position ignoriert.

Anfrage

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}

Artikelkategorie aktualisieren

Aktualisiert Name, Parent oder Position einer Artikelkategorie. Sowohl PUT als auch PATCH akzeptieren partielle Änderungen in der flachen und der verschachtelten Request-Form.

Wenn parent_id dem aktuellen Parent entspricht, kann position im selben Request angewendet werden. Ändert sich der Parent tatsächlich, wird eine gleichzeitig gesendete position ignoriert und die Kategorie am Ende der neuen Geschwisterliste eingefügt. Um Parent und Zielposition zu ändern, sind deshalb zwei Requests erforderlich.

Parent setzen

Setzt den direkt übergeordneten Parent. Die Kategorie wird am Ende der neuen Geschwisterliste eingefügt. Mit null wird sie auf die oberste Ebene verschoben.

Patch-Anfrage

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 setzen

Verschiebt die Kategorie an Position 2 innerhalb der aktuellen Geschwisterliste. Die Position muss eine positive Ganzzahl sein.

Patch-Anfrage

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

Setzt Parent und Position in einem Request. Das funktioniert nur vollständig, wenn parent_id bereits dem aktuellen Parent entspricht. Ändert sich der Parent, wird position ignoriert. Um beides tatsächlich zu ändern, müssen zuerst der Parent und danach die Position gesetzt werden.

Patch-Anfrage

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

Artikel veröffentlichen

Veröffentlicht einen Artikel, nachdem alle Pflichtfelder und Publishing-Voraussetzungen erfüllt sind.

Anfrage

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}

Artikel löschen

Löscht einen Artikel aus den normalen API-Responses.

Anfrage

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}'