API Changelog

This changelog records customer-facing API contract changes published in this documentation repository. Dates refer to documentation publication dates and do not necessarily represent backend deployment dates.

2026-08-12

Article Categories API

• Added writable parent_id support to article category create and update requests. null moves a category to the root level; invalid or cross-publication parents return 422 Unprocessable Entity.
• Added writable position support for ordering categories within the same parent. Positions are 1-indexed positive JSON integers; invalid values return 422 and are not normalized.
• Added position to category responses and clarified that parent_ids is the read-only ancestor path from the root to the immediate parent.
• Defined combined parent and position behavior: assigning or changing a parent appends the category to the new sibling list and ignores position in that request. Reordering after a parent change requires a second update. An unchanged parent_id can be sent together with position.
• Split create and update request schemas: create requires name; PUT and PATCH accept partial flat or nested updates.

2026-07-10

Article Import API

• Added article category endpoints to list, create, and update categories with GET, POST, PUT, and PATCH.
• Added article_category_ids to article responses and article update requests. An empty array removes all assignments.
• Restricted category assignment to existing category IDs from the current publication. Unknown IDs and non-integer elements return 422; a non-array value returns 400 Bad Request.
• Defined article creation and category assignment as two requests: categories cannot be assigned by POST /stories and must be assigned with a subsequent article update.
• Separated article create and update schemas and documented malformed request envelopes as 400 responses.

2026-06-19

Authentication API (OIDC)

• Added the customer-implemented OIDC authorization contract under /pmx-api/v2/{profile_token}.
• Added authorization endpoints for issues, downloads, chatbots, articles, and the optional accessible-issues list.
• Required Authorization: Bearer {ACCESS_TOKEN} for all OIDC endpoints and documented optional forwarding through OIDC-ID-Token.
• Defined invalid or expired tokens as 401 Unauthorized; valid tokens denied by business rules return 200 OK with granted: false.
• Clarified that end-user login happens upstream at the customer's Identity Provider and that PressMatrix does not send usernames or passwords to this API.
• Documented PX-User, Auth0, and Keycloak as supported OIDC providers.
• Clarified that both authentication API variants are implemented and operated by the customer, not by PressMatrix.

2026-06-17

Article Import API

• Published the Article Import API contract for listing, creating, retrieving, replacing, partially updating, deleting, and publishing articles under the technical stories resource.
• Added token authentication with Authorization: Token {TOKEN_GENERATED_BY_PMX} and the story request and response envelope.
• Added JSON and multipart article creation and updates. Image uploads support JPEG, PNG, and GIF with a maximum size of 5 MB.
• Added pagination, creation-date filters, external-ID filtering, and free-text search across article content and product identifiers.
• Documented article pricing, language, release, subscription, purchase, external, and product-identifier fields.
• Defined 401, 404, and 422 responses, deletion behavior, and publishing prerequisite failures.

2026-03-20

Import API 2.1

• Added paginated GET /emags, GET /emags/{emag_id}, and DELETE /emags/{emag_id} operations.
• Added read-only planned-emag listing and retrieval through GET /planned_emags and GET /planned_emags/{planned_emag_id}.
• Defined standard PDF, planned PDF, and EPUB import payloads. Planned PDF imports use import_attributes together with pe_id; EPUB imports use epub_import_attributes.
• Defined import-state responses: standard PDF imports use status; planned PDF and EPUB imports use ai_status. Supported states are pending, processing, finished, and failed.
• Added complete emag response envelopes, pagination metadata, and structured validation and business-error responses.
• Clarified update behavior: metadata can be updated independently, import attributes trigger a re-import, and switching between PDF and EPUB mode after creation is not allowed.
• Published a Postman collection for the Import API.

2025-11-14

Authentication API

• Clarified that POST /issues is optional and must be enabled by PressMatrix.
• Defined the response as a flat array of product IDs. Apple, Google, and external product IDs can be mixed; Amazon product IDs are deprecated.
• Clarified that at least one supported product ID must be returned for each visible issue and that an empty array grants access to no issues.
• Published an example customer implementation using AWS Lambda, DynamoDB, and API Gateway.

2025-09-30

Import API

• Added planned PDF imports to the documented import modes. They use import_attributes with import_images and a PressMatrix-provided pe_id.

2025-09-12

Import API

• Replaced the separate planned-emag creation and polling contract with planned PDF creation through POST /emags using pe_id.
• Replaced the generic import_config payload with import_attributes for PDF imports and epub_import_attributes for EPUB imports.
• Defined three mutually exclusive create modes: standard PDF without pe_id, planned PDF with pe_id, and EPUB.
• Documented 422 Unprocessable Entity for invalid planned-edition IDs, duplicate names, and invalid import-mode changes.

2025-09-10

Import API

• Introduced standalone planned-emag creation through POST /planned_emags and processing-status polling through GET /planned_emags/{planned_emag_id}. This contract was superseded on 2025-09-12 by planned imports through POST /emags.
• Documented that updating import attributes triggers a new import and removes the previous import result.
• Documented that the import mode cannot be switched between PDF and EPUB after creation.

2025-07-28

Import API 2.0

• Published the OpenAPI contract for creating periodicals with POST /emags and updating them with PUT /emags/{emag_id}.
• Added token authentication and request envelopes for PDF and EPUB imports.
• Added issue metadata for release dates, pricing, product identifiers, categories, language, text mode, subscription access, and single purchases.
• Defined validation, authentication, not-found, and internal-error responses.

2025-07-24

Import API

• Added the first documented PDF import flow for creating periodicals through POST /emags with remote PDF and optional XML widget-mapping URLs.

2025-07-01

Authentication API

• Promoted the download, chatbot, and article authorization endpoints from preview status to supported optional endpoints.

2025-06-30

Authentication API

• Published the OpenAPI contract for authentication, ticket authentication, issue authorization, optional download, chatbot and article authorization, and accessible-issues lookup.
• Defined HTTP Basic Authentication, request and response schemas, profile-token routing, and shared 400 and 401 error responses.

2025-06-18

Authentication API

• Added Accept: application/json to all documented requests.
• Marked download, chatbot, and article authorization as preview features at that time.
• Marked POST /issues as an optional feature requiring activation by PressMatrix.

2025-06-13

Authentication API

• Added authorization contracts for downloads, chatbots, and articles alongside issue authorization.
• Defined each authorization result as granted: true or granted: false.

2025-06-03

Authentication API

• Published the initial customer-implemented Authentication API contract under /pmx-api/v1/{profile_token}.
• Added username/password authentication, browser ticket authentication, issue authorization, and accessible-issues endpoints.
• Required HTTP Basic Authentication for all endpoints and 401 Unauthorized for missing or invalid credentials.