API versioning (planned)

API version negotiation has not launched. Requests currently remain unversioned and use the existing compatibility behavior. Sending a version header or query parameter today does not select a dated contract, so do not treat either value as a production pin.

The API reference describes the current behavior. Backwards-incompatible version dates, supported-version lists, SDK mappings, deprecation windows, and migration guidance will be published when negotiation launches.

What will count as a breaking change?

A future dated API version may be needed for changes such as:

• removing or renaming a request or response field
• changing a field type
• removing an endpoint or parameter
• changing endpoint behavior in a way existing integrations cannot support
• removing a documented compatibility alias

Adding an optional response field or endpoint, improving validation messages, and fixing behavior outside the documented contract can remain non-breaking.

Select an API version after negotiation launches

Direct API clients will choose one documented dated version using either the RRWeb-API-Version request header or the rrweb-api-version query parameter.

The request header:

RRWeb-API-Version: 2026-04-26

or the query parameter:

?rrweb-api-version=2026-04-26

Do not send both methods. The launch documentation will define the accepted dates and error behavior for conflicting or unsupported values. Official SDK documentation will state which API version each SDK release selects.

When a version is deprecated, rrweb Cloud will publish support dates and migration guidance before removal. Do not infer a support window from the example date on this page.