API v1 compatibility policy

API v1 is identified by /api/v1. Stable operations follow these rules.

Additive optional fields, new endpoints, new optional request properties, and new problem codes are normally non-breaking. Clients must ignore unknown response properties. New enum values are additive only when the schema explicitly marks the enum extensible; otherwise they require advance deprecation guidance.

Removing or renaming an operation or field, changing a type or meaning, making optional input required, narrowing accepted values, or changing lifecycle effects is breaking and requires a new major API path. A stable operation is normally deprecated for at least 180 days. OpenAPI carries deprecated, replacement guidance, deprecation date, and sunset date; HTTP responses may also carry Deprecation, Sunset, and Link headers.

Emergency security changes may shorten the window when continued behaviour creates material risk. The changelog explains the risk without disclosing exploit details, the migration path, and the exceptional schedule.

Labels are stable, beta, experimental, and deprecated. Beta and experimental operations state their narrower guarantees in their OpenAPI description.