presseecho API

Entwickler

API-Dokumentation

Über die versionierte REST-API des Publisher-Hubs erstellen Sie Pressemitteilungen programmatisch, versehen sie mit Bildern und reichen sie zur Prüfung ein.

Grundlagen

Die API v1 ist ein RESTful Web Service mit JSON-Responses. Basis-URL: https://pressekonto.com/api/v1. Eine über die API angelegte Mitteilung ist immer ein Entwurf. Veröffentlicht wird sie erst, wenn Sie sie über die Submit-Route einreichen und sie die anschließende Inhaltsprüfung besteht. Dann erscheint sie wie jede andere Mitteilung auf beiden Portalen.

Authentifizierung

Alle Anfragen benötigen einen persönlichen API-Token als Bearer-Header: Authorization: Bearer <token>. Jeder Token trägt Berechtigungen (z. B. press-releases:write), die den Zugriff auf die jeweiligen Endpunkte steuern. Tokens erstellen und widerrufen Sie selbst in Ihrem Publisher-Konto unter „API-Tokens“. Voraussetzung ist eine aktive Buchung (Tarif oder Einzel-Pressemitteilung). Bestandskunden der Altportale: Ihre bisherigen API-Schlüssel wurden übernommen. Sie funktionieren weiter als Bearer-Token, in der alten Form (X-ApiKey-Header) und auf den dokumentierten /service/…-Pfaden. Für neue Integrationen empfehlen wir die aktuellen /api/v1/…-Endpunkte mit Bearer-Token.

Endpunkte

Pressemitteilungen

GET

/press-releases

Eigene Mitteilungen auflisten (paginiert, filterbar über ?status=, ?reference= und ?per_page=, max. 100). · Berechtigung: press-releases:read

POST

/press-releases

Neue Mitteilung anlegen, immer als Entwurf (Status draft). Eine bereits vergebene Referenz ergibt 409 mit der vorhandenen Mitteilung. · Berechtigung: press-releases:write

GET

/press-releases/{id}

Eine Mitteilung inkl. Firma, Rubrik und Bildern abrufen. · Berechtigung: press-releases:read

PATCH

/press-releases/{id}

Mitteilung ändern (nur im Status draft oder rejected). · Berechtigung: press-releases:write

POST

/press-releases/{id}/submit

Zur Inhaltsprüfung einreichen. Das ist der einzige Weg zur Veröffentlichung. · Berechtigung: press-releases:write

DELETE

/press-releases/{id}

Mitteilung löschen. Veröffentlichte Mitteilungen sind ausgenommen. · Berechtigung: press-releases:write

Bilder

GET

/press-releases/{id}/images

Bilder einer Mitteilung auflisten. · Berechtigung: press-releases:read

POST

/press-releases/{id}/images

Bild hochladen (multipart/form-data), nur bei draft/rejected. · Berechtigung: press-release-images:write

DELETE

/press-release-images/{imageId}

Bild entfernen, nur bei draft/rejected. · Berechtigung: press-release-images:write

Stammdaten

GET

/companies

Eigene Firmenprofile (Newsrooms) auflisten. · Berechtigung: companies:read

GET

/companies/{id}

Ein Firmenprofil abrufen. · Berechtigung: companies:read

GET

/categories

Aktive Rubriken inkl. Übersetzungen, mit der category_id für neue Mitteilungen. · Berechtigung: press-releases:read

Konto

GET

/quota

Stand des PM-Kontingents: Guthaben, Meldungen in Prüfung, einreichbar, Tageslimit. · Berechtigung: press-releases:read

GET

/legal/acceptances

Geforderte und bereits angenommene Fassungen von AGB und Veröffentlichungsrichtlinien.

POST

/legal/acceptances

Aktuelle Fassungen annehmen ({"documents": [{"type": "agb", "version": "…"}]}). Erst danach können Sie einreichen. · Berechtigung: press-releases:write

Felder einer Pressemitteilung

Feld	Typ	Pflicht	Beschreibung
reference	string	—	Eigene Referenz, z. B. Ihre Auftragsnummer, max. 100 Zeichen. Eindeutig je Konto und nach dem Anlegen fest; ein wiederholtes Anlegen legt keine zweite Mitteilung an.
portal	string	—	Ziel-Portal (presseecho oder businessportal24). Ohne Angabe entscheidet die aufgerufene Domain, sonst das Portal des Firmenprofils; ein gesetzter Wert hat Vorrang.
company_id	integer	ja	ID eines eigenen Firmenprofils. Sie legt fest, in welchem Newsroom die Mitteilung erscheint.
category_id	integer	ja	Rubrik (siehe GET /categories).
language	string	ja	Sprachcode, zwei Zeichen: de oder en.
title	string	ja	Überschrift, max. 255 Zeichen.
text	string	ja	Inhalt. Erlaubtes HTML: p, br, h2, h3, strong, em, ul, ol, li, blockquote, a. Alles andere wird entfernt.
backlink_url	string	—	Link zur Quelle/Website, nur http:// oder https://, max. 255 Zeichen.
keywords	string	—	Schlagworte, kommagetrennt, max. 255 Zeichen.
teaser_begin / teaser_end	integer	—	Zeichen-Offsets für den Teaser-Ausschnitt.
no_export	boolean	—	Mitteilung von Feeds/Exporten ausnehmen.

Felder eines Bild-Uploads

Feld	Typ	Pflicht	Beschreibung
image	file	ja	JPG, PNG oder WebP, max. 16 MB, höchstens 8.000 Pixel je Seite. Ein Titelbild je Mitteilung.
ai_declaration	string	ja	KI-Kennzeichnung des Bildes: original (ohne generative KI), ai_generated, ai_edited. Enthält die Datei geprüfte Herkunftsdaten, gilt deren Kennzeichnung; eine Abschwächung ist nicht möglich.
copyright	string	ja	Bildnachweis, wie er unter dem Bild erscheint („Foto: …“), max. 255 Zeichen.
rights_confirmed	boolean	ja	Muss true sein: Bestätigung, dass Sie zur Veröffentlichung berechtigt sind und die Angaben zutreffen (Wortlaut siehe Hinweis unten).
confirm_text_version	string	ja	Kennung des bestätigten Wortlauts, derzeit img-confirm-v2. Eine veraltete Kennung wird mit 422 und der aktuellen Kennung beantwortet.
title	string	—	Bildtitel, max. 120 Zeichen.
description	string	—	Bildunterschrift, max. 500 Zeichen.
license_url	string	—	Link zur Lizenz, wenn eine Lizenz die Nutzung regelt (z. B. Creative Commons, Agentur).
source_url	string	—	Link zur Fundstelle oder Ursprungsseite (keine Lizenz).
focus_x / focus_y	integer	—	Fokuspunkt für den Zuschnitt in Prozent (0–100), Standard Bildmitte.
no_crop	boolean	—	true: nicht beschneiden, ganzes Bild mit neutralem Rand.
is_preview	boolean	—	Als Vorschaubild setzen (ersetzt ein vorhandenes).

Schneller Einstieg

Der typische Ablauf: Entwurf anlegen, Bild hochladen, zur Prüfung einreichen.

# 1. Entwurf anlegen
curl -X POST https://pressekonto.com/api/v1/press-releases \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "A-2026-0815",
    "company_id": 1,
    "category_id": 2,
    "language": "de",
    "title": "Neue Produktankündigung",
    "text": "<p>Unser neues Produkt …</p>"
  }'

# 2. Bild hochladen (multipart)
curl -X POST https://pressekonto.com/api/v1/press-releases/123/images \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "image=@pressefoto.jpg" \
  -F "ai_declaration=original" \
  -F "copyright=Mustermann GmbH" \
  -F "rights_confirmed=1" \
  -F "confirm_text_version=img-confirm-v2" \
  -F "is_preview=1"

# 3. Zur Inhaltsprüfung einreichen
curl -X POST https://pressekonto.com/api/v1/press-releases/123/submit \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ai_text_declaration": "none" }'

Pflicht seit Juli 2026: Der Submit-Aufruf erklärt verbindlich den KI-Grad des Textes (ai_text_declaration: none, assisted, mostly_ai, fully_ai; Transparenzpflicht nach Art. 50 KI-VO) und schließt die Kenntnisnahme der dauerhaften Archivierung ein (AGB § 13). Jedes Bild trägt seine eigene Kennzeichnung (ai_declaration: original, ai_generated, ai_edited).

Bilder sind optional. Wird ein Bild übermittelt, sind copyright, ai_declaration, rights_confirmed und confirm_text_version Pflicht. Das Portal liest Herkunftsdaten der Datei (IPTC, XMP; später Content Credentials) aus und speichert die Originaldatei zur Beweissicherung. Mit rights_confirmed bestätigen Sie für jedes Bild die Rechteerklärung in der Fassung img-confirm-v2; ihr Wortlaut ist Bestandteil der API-Nutzungsbedingungen. Bilder ohne die Pflichtfelder werden mit 422 abgelehnt, die Mitteilung bleibt unverändert.

Maschinenlesbare Referenz: OpenAPI-Spezifikation (YAML).

Überarbeiten nach einer Ablehnung

Eine abgelehnte Mitteilung (status rejected, Begründung in rejection_reason) ändern Sie mit PATCH /press-releases/{id} und reichen sie mit POST /press-releases/{id}/submit erneut ein. Mitteilung und Referenz bleiben dieselben. Das Feld review zeigt den Stand der automatischen Prüfung (automatic_checks_used von automatic_checks_max); danach prüft ein Mensch aus der Redaktion (manual_review true).

Kontingent abfragen

GET /quota liefert den Stand Ihres PM-Kontingents. Bei einer Kontingentvereinbarung (model agreement) wird erst bei der Veröffentlichung abgezogen; einreichbar (available) ist das Guthaben minus die Mitteilungen in Prüfung. Antworten auf submit tragen dann zusätzlich die Kopfzeilen X-Quota-Remaining und X-Daily-Remaining.

Fehlercodes

Fehlerantworten enthalten message (Klartext) und, wo der Client reagieren kann, einen stabilen code. Werten Sie code aus, nicht den Text.

HTTP	code	Bedeutung
402	booking_required	Keine aktive Buchung.
409	not_editable	Nur Entwürfe und abgelehnte Mitteilungen sind änderbar.
409	not_submittable	Nur Entwürfe und abgelehnte Mitteilungen können eingereicht werden.
409	not_deletable	Veröffentlichte Mitteilungen können nicht per API gelöscht werden.
409	duplicate_reference	Referenz bereits vergeben; data enthält die vorhandene Mitteilung, es wird nichts angelegt.
422	quota_exhausted	Kontingent aufgebraucht (bei einer Kontingentvereinbarung: Guthaben abzüglich der Mitteilungen in Prüfung).
422	ai_declaration_missing	KI-Angabe zum Text (ai_text_declaration) fehlt.
422	ai_declaration_mismatch	KI-Angabe widerspricht der für Ihr Konto vereinbarten Vorgabe; required_ai_text_declaration nennt sie.
422	blacklisted	Unzulässiger Begriff im Text.
428	terms_required	Aktuelle AGB/Richtlinien noch nicht angenommen; required_documents nennt die Fassungen (POST /legal/acceptances).
429	daily_limit_reached	Tageslimit der Kontingentvereinbarung erreicht; Retry-After bis Mitternacht (deutsche Zeit). Überarbeitungen abgelehnter Mitteilungen zählen nicht.

HTTP-Statuscodes

Code	Bedeutung
200 / 201 / 204	Erfolg: Abruf, Ressource erstellt bzw. gelöscht.
401	Kein oder ungültiger API-Token.
402	Einreichen erfordert eine aktive Buchung (Tarif oder Einzel-PM).
403	Token-Berechtigung fehlt oder die Ressource gehört nicht zu Ihrem Konto.
409	Statuskonflikt, z. B. beim Bearbeiten einer bereits veröffentlichten Mitteilung oder bei einer bereits vergebenen Referenz.
422	Validierungsfehler oder Kontingent-/Richtlinienverstoß (Details im Body).
428	Vor dem Einreichen müssen die aktuellen AGB und Richtlinien angenommen sein (code terms_required).
429	Rate-Limit erreicht (60 Anfragen pro Minute je Token, Header X-RateLimit-*) oder Tageslimit einer Kontingentvereinbarung erreicht (code daily_limit_reached).

API-Token erstellen

Tokens verwalten Sie selbst im Publisher-Konto. Bei Fragen zur Anbindung hilft der Support: info@businessportal24.com

Zum Publisher-Konto Preise ansehen