Versioning

The distinction decides whether a change can ship silently or needs a new version, so it is worth being precise.

Not breaking — can appear at any time:

• A new field on a response.
• A new optional request parameter.
• A new endpoint.
• A new event type.
• A new value in a list you already have to handle unknown members of.

Breaking — needs a new dated version:

• Removing or renaming a response field.
• Removing an endpoint, or changing its path or method.
• Making an optional request field required.
• Narrowing what a field accepts.
• Changing the type of an existing field.

When an operation is on its way out it keeps working and starts announcing itself:

Sunset is the date it stops working. Between the two you have a window to migrate, and the endpoint behaves exactly as it always did.

Three values make a support conversation short instead of long:

• Agentency-Version — which contract shaped the response.
• request_id — on every response header and in every error body. This is the single most useful thing to quote when reporting a problem.
• error.code — the machine-readable failure, e.g. RATE_LIMITED.

The published OpenAPI document is generated from the running API, not written by hand, so it cannot describe an endpoint that does not exist or miss one that does.

Diff it between releases to see exactly what changed, or generate a typed client from it. Both SDKs are built this way.

• Changelog — what has actually changed.
• Errors — the error envelope, which is itself versioned.
• SDKs — clients generated from the spec.