API stability and deprecation policy

This policy covers HTTP paths and methods, request and response schemas, documented headers, error codes, webhook payloads, SDK public APIs and CLI flags. Template document compatibility is governed by formatVersion. The MIT plugin API has its own semver contract; see plugin authoring.

Removing or renaming a path, field or header; tightening validation; changing a type or default; changing authentication scope requirements; or repurposing an error code is breaking. New endpoints, optional request fields, response fields, headers, response enum values and error codes are additive. Clients must tolerate unknown fields and enum values, and fall back to the HTTP status class when an error code is unknown. Strictly generated clients may need updating for new enums.

Before 1.0, patches never break the contract. A breaking change can ship in a minor only after at least two minor releases and 90 days of deprecation with runtime signals. From 1.0, strict semver applies: removal happens only in a major, after at least six months. URLs remain unversioned until 1.0; a future breaking major will mount /v2 beside the unprefixed v1.

After a removal, a hidden tombstone route returns HTTP 410 with code: "gone" and a successor Link for one further minor release. Beta surfaces (currently operations explicitly marked x-stability: beta in OpenAPI) are exempt from the stable compatibility window. The latest supported server policy still applies to fixes.

Runtime signals

Deprecation (RFC 9745) is a structured date, @<Unix seconds>. Sunset (RFC 8594) is an IMF-fixdate. Link carries successor-version and deprecation relations. These headers appear on success and error responses and are exposed through CORS. They do not change the response body or the operation’s current behaviour.

The TypeScript SDK calls onDeprecation(notice) when supplied; otherwise it warns once per method/path per process. Python issues PulpEngineDeprecationWarning once per path. Operators can query pulp_engine_deprecated_requests_total{method,route,feature,scope}. Sampled logs include tenant and actor without putting them into Prometheus labels.

Deprecation register

Surface	Since	Runtime signal	Planned sunset	Removal review	Successor
POST /render	0.79.0, 2026-05-30	Wave 8 release	2027-03-06	0.89.0	POST /render/pdf
Legacy API_KEY environment variable	Legacy scoped-key migration	Startup warning	Unscheduled	Unscheduled	API_KEY_ADMIN, API_KEY_RENDER, API_KEY_PREVIEW, API_KEY_EDITOR

The render-alias dates are planned, not an immediate removal. At release, ensure its first runtime signal ships at least 90 days before sunset and two minors before removal; extend both if necessary. CI rejects a version at or beyond a registered removeIn until removal or an explicit extension is reviewed. Future async-batch aliases must enter this register and use deprecateRoute.

PPTX rendering is stable from Wave 68; its OpenAPI operations carry x-stability: stable.