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
/press-releases
List your releases (paginated, filterable via ?status=, ?reference= and ?per_page=, max. 100).
· Permission: press-releases:read
/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
/press-releases/{id}
Fetch a release incl. company, category and images.
· Permission: press-releases:read
/press-releases/{id}
Update a release (only in status draft or rejected).
· Permission: press-releases:write
/press-releases/{id}/submit
Submit for content review. This is the only path to publication.
· Permission: press-releases:write
/press-releases/{id}
Delete a release. Published releases are excluded.
· Permission: press-releases:write
Images
/press-releases/{id}/images
List the images of a release.
· Permission: press-releases:read
/press-releases/{id}/images
Upload an image (multipart/form-data), only for draft/rejected.
· Permission: press-release-images:write
/press-release-images/{imageId}
Remove an image, only for draft/rejected.
· Permission: press-release-images:write
Master data
/companies
List your company profiles (newsrooms).
· Permission: companies:read
/companies/{id}
Fetch a company profile.
· Permission: companies:read
/categories
Active categories incl. translations, with the category_id for new releases.
· Permission: press-releases:read
Account
/quota
Status of your release quota: balance, releases in review, submittable, daily limit.
· Permission: press-releases:read
/legal/acceptances
Required and already accepted versions of the terms and the publication guidelines.
/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