Breaking changes

The API reference describes the reviewed public contract under /api/v1. Changelog entries report user-visible changes; this page defines how Documentation V1 communicates compatibility without promising an unsupported lifetime or release schedule.

What counts as breaking#

A change is breaking when an existing valid integration must change to continue working. Examples include removing or renaming an operation, parameter, response field, or error contract; making an optional request field required; narrowing accepted values; or changing authentication so an existing caller is rejected.

Adding an optional field or a new operation is normally additive. Callers should ignore response fields they do not understand. Clarifying prose without changing runtime behavior is documentation maintenance, not an API break.

Publication rule#

A breaking API change receives a clear Breaking label in the public changelog and a migration note. The note states the affected operation or field, the old and new behavior, the customer action, and the effective product release context that is actually known at publication.

The API operation pages and reviewed examples must change with the runtime contract. The generated public OpenAPI snapshot and operation metadata are checked together so undocumented active operations or stale examples fail review.

No implied lifecycle promise#

v1 is the current base path, but this documentation does not promise a fixed support duration, deprecation window, future version, delivery date, or release schedule. Any compatibility period that Operade formally adopts must be published as a concrete user-facing policy before integrations rely on it.

Integration guidance#

Pin client behavior to method, path, documented request fields, status, and error code. Do not parse message text or depend on undocumented fields. Validate changes in a non-production caller before updating production traffic, and keep mutation retries consistent with Idempotency and concurrency.

Read the Documentation V1 changelog, API introduction, and exact operation page for current behavior.