API versioning

rrweb Cloud uses date-based API versions for backwards incompatible API changes. A version is named by its release date, for example 2026-04-26.

API versions do not change the URL path. The same endpoint paths remain available, and the version is selected per request.

Planned behavior

API version negotiation is not active yet. Until it ships, requests use the legacy compatibility behavior even if they include the version header or query parameter.

Choose a version

When you use an official SDK, the SDK selects the API version it was built and tested against. Updating the SDK may also update the API version used by SDK requests.

When you make direct API calls, choose exactly one of these methods:

RRWeb-API-Version: 2026-04-26

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

After API version negotiation ships, do not send both the header and query parameter. Requests that specify both, or specify an unsupported version, will be rejected with 400 Bad Request.

Breaking changes

We create a new API version when an API change requires existing integrations to change. Breaking changes include:

• removing or renaming a request or response field
• changing a request or response field type
• removing an endpoint or parameter
• changing endpoint behavior in a way older clients cannot support
• removing a deprecated compatibility alias

Non-breaking changes can ship without a new version. Examples include adding an optional response field, adding a new endpoint, improving validation messages, or fixing behavior that was not part of the documented contract.

Current versions

Latest

latest in the API reference means the current documented API behavior. It is useful for reading docs, but it is not an API version value. For production direct API calls, send a dated version.

2026-04-26

Initial documented API version for the RESTful recording, replay, metadata, and statistics APIs.

Compatible SDKs:

SDK	Version
Browser Client	Not yet published

Unversioned requests

Requests without RRWeb-API-Version or rrweb-api-version continue to use the legacy compatibility behavior. This keeps existing integrations working, but new integrations should pin a dated version after version negotiation ships.

Support policy

The active API version receives new features and fixes. Older versions continue to work, but new product capabilities may only be available on the active version.

When a version is deprecated, we will publish migration guidance before removing support.