Fr, 20. Nov 🇩🇪 DE 🌐 EN EN Pricing
presseecho API
Developers

API documentation

Use the versioned REST API of the publisher hub to create press releases programmatically, add images and submit them for review.


Basics

API v1 is a RESTful web service with JSON responses. Base URL: https://pressekonto.com/api/v1. A release created via the API is always a draft. It is only published once you submit it via the submit route and it passes the subsequent content review. It then appears on both portals like any other release.

Authentication

All requests require a personal API token as a bearer header: Authorization: Bearer <token>. Each token carries permissions (e.g. press-releases:write) that control access to the respective endpoints. You create and revoke tokens yourself in your publisher account under “API tokens”. This requires an active booking (plan or single press release). All endpoints are located under /api/v1/….

Endpoints

Press releases

GET
/press-releases

List your releases (paginated, filterable via ?status=, ?reference= and ?per_page=, max. 100). · Permission: press-releases:read

POST
/press-releases

Create a new release, always as a draft (status draft). A reference that is already taken returns 409 with the existing release. · Permission: press-releases:write

GET
/press-releases/{id}

Fetch a release incl. company, category and images. · Permission: press-releases:read

PATCH
/press-releases/{id}

Update a release (only in status draft or rejected). · Permission: press-releases:write

POST
/press-releases/{id}/submit

Submit for content review. This is the only path to publication. · Permission: press-releases:write

DELETE
/press-releases/{id}

Delete a release. Published releases are excluded. · Permission: press-releases:write

Images

GET
/press-releases/{id}/images

List the images of a release. · Permission: press-releases:read

POST
/press-releases/{id}/images

Upload an image (multipart/form-data), only for draft/rejected. · Permission: press-release-images:write

DELETE
/press-release-images/{imageId}

Remove an image, only for draft/rejected. · Permission: press-release-images:write

Master data

GET
/companies

List your company profiles (newsrooms). · Permission: companies:read

GET
/companies/{id}

Fetch a company profile. · Permission: companies:read

GET
/categories

Active categories incl. translations, with the category_id for new releases. · Permission: press-releases:read

Account

GET
/quota

Status of your release quota: balance, releases in review, submittable, daily limit. · Permission: press-releases:read

GET
/legal/acceptances

Required and already accepted versions of the terms and the publication guidelines.

POST
/legal/acceptances

Accept the current versions ({"documents": [{"type": "agb", "version": "…"}]}). Only then can you submit and upload images. · Permission: press-releases:write

Fields of a press release

Field Type Required Description
reference string — Your own reference, e.g. your order number, max. 100 characters. Unique per account and fixed after creation; repeating the request does not create a second release.
portal string — Target portal (presseecho or businessportal24). If omitted, the requested domain decides, otherwise the company profile's portal; an explicit value takes precedence.
company_id integer yes ID of one of your company profiles. It determines the newsroom in which the release appears.
category_id integer yes Category (see GET /categories).
language string yes Language code, two characters: de or en.
title string yes Headline, max. 255 characters.
text string yes Content. Allowed HTML: p, br, h2, h3, strong, em, ul, ol, li, blockquote, a. Everything else is stripped.
backlink_url string — Link to source/website, http:// or https:// only, max. 255 characters.
keywords string — Keywords, comma-separated, max. 255 characters.
teaser_begin / teaser_end integer — Character offsets for the teaser excerpt.
no_export boolean — Exclude the release from feeds/exports.

Fields of an image upload

Field Type Required Description
image file yes JPG, PNG or WebP, max. 16 MB, at most 8,000 pixels per side. One title image per release.
ai_declaration string yes AI label of the image: original (no generative AI), ai_generated, ai_edited. If the file carries verified provenance data, that label applies and cannot be weakened.
copyright string yes Image credit as shown below the image (“Photo: …”), max. 255 characters.
rights_confirmed boolean yes Must be true: confirmation that you are entitled to publish the image and that your details are correct (wording see note below).
confirm_text_version string yes Identifier of the confirmed wording, currently img-confirm-v4. An outdated identifier is answered with 422 and the current one.
title string — Image title, max. 120 characters.
description string — Description, max. 500 characters.
license_url string — Link to the licence if a licence governs the use (e.g. Creative Commons, agency).
source_url string — Link to the source page (not a licence).
focus_x / focus_y integer — Focus point for cropping in percent (0–100), default centre.
no_crop boolean — true: do not crop, full image with neutral padding.
is_preview boolean — Set as preview image (replaces an existing one).

Quick start

The typical flow: create a draft, upload an image, submit for review.

# 1. Create a draft
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. Upload an image (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-v4" \
  -F "is_preview=1"

# 3. Submit for content review
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" }'

Required since July 2026: the submit call is a binding declaration of the AI grade of the text (ai_text_declaration: none, assisted, mostly_ai, fully_ai; transparency obligation under Art. 50 EU AI Act) and includes acknowledgement of permanent archiving (Terms § 13). Each image carries its own label (ai_declaration: original, ai_generated, ai_edited).

Images are optional. If an image is submitted, copyright, ai_declaration, rights_confirmed and confirm_text_version are required. The portal reads provenance data from the file (IPTC, XMP; later Content Credentials) and keeps the original file as evidence. With rights_confirmed you confirm the rights declaration in version img-confirm-v4 for each image; its wording is part of the API terms of use. Images without the required fields are rejected with 422; the release itself is unaffected.

Machine-readable reference: OpenAPI specification (YAML).

Revising after a rejection

Change a rejected release (status rejected, reason in rejection_reason) with PATCH /press-releases/{id} and submit it again with POST /press-releases/{id}/submit. Release and reference stay the same. The review field shows the state of the automatic check (automatic_checks_used of automatic_checks_max); after that a member of our editorial team reviews it (manual_review true).

Checking your quota

GET /quota returns the status of your release quota. With a quota agreement (model agreement) a release is deducted only when it is published; submittable (available) is the balance minus the releases in review. The same applies to plans and single purchases (model plan): remaining is the number of publications not yet used, in_review the releases in review that will use one of them when published (releases scheduled after the current calendar month only count from that month on), available what can still be submitted. Responses to submit then also carry the X-Quota-Remaining header (submittable) and, with a daily limit, X-Daily-Remaining.

Error codes

Error responses contain message (plain text) and, where the client can react, a stable code. Evaluate code, not the text.

HTTP code Meaning
402 booking_required No active booking.
409 not_editable Only drafts and rejected releases can be changed.
409 not_submittable Only drafts and rejected releases can be submitted.
409 not_deletable Published releases cannot be deleted via the API.
409 duplicate_reference Reference already taken; data contains the existing release, nothing is created.
422 quota_exhausted Quota used up: remaining publications or balance minus the releases in review, each of which already reserves one.
422 ai_declaration_missing AI declaration for the text (ai_text_declaration) is missing.
422 ai_declaration_mismatch The AI declaration contradicts the one agreed for your account; required_ai_text_declaration names it.
422 blacklisted Prohibited term in the text.
428 terms_required Current terms/guidelines not yet accepted; required_documents lists the versions (POST /legal/acceptances).
429 daily_limit_reached Daily limit of the quota agreement reached; Retry-After until midnight (German time). Revisions of rejected releases do not count.

HTTP status codes

Code Meaning
200 / 201 / 204 Success: fetch, resource created or deleted.
401 Missing or invalid API token.
402 Submitting requires an active booking (plan or single release).
403 Token permission missing or the resource does not belong to your account.
409 Status conflict, e.g. when editing an already published release or when a reference is already taken.
422 Validation error or quota/guideline violation (details in the body).
428 The current terms and guidelines must be accepted before submitting and uploading images (code terms_required).
429 Rate limit reached (60 requests per minute per token, X-RateLimit-* headers) or daily limit of a quota agreement reached (code daily_limit_reached).

Create an API token

You manage tokens yourself in the publisher account. For integration questions, support is happy to help: info@pressekonto.com