Skip to content
Documentation

RTC API versioning

Everything under /v1 changes additively only. RTC may add:

  • new routes, optional request fields and query parameters;
  • new response fields, error codes, webhook event types and enum values;
  • new response headers.

Build clients that ignore unknown fields and treat an unknown error code like the generic code of its HTTP status. RTC does not remove or rename a field, change its type or meaning, make an optional input required, or reuse an error code under /v1.

A breaking change ships as a new major path, /v2. Both versions then run side by side for at least 12 months before /v1 is retired, with notice on this site.

Some improvements change the shape of an answer without changing what it means, such as the structured error envelope. They are opt-in per request with a dated version header:

RTC-Version: 2026-11-01
VersionChanges
noneOriginal shapes. Errors are { "error": "<message>", "code"? }.
2026-11-01Errors use the envelope { "error": { code, message, details?, requestId, retryable, docUrl } }.

RTC applies the newest version that is not later than the date you send, and echoes it in the RTC-Version response header. A date earlier than the first version keeps the original shapes. Pin the version your code was written against and change it deliberately when you upgrade.

Each webhook endpoint has an apiVersion that fixes the envelope it receives, independent of request headers:

apiVersionEnvelope
legacy{ id, type, createdAt, projectId, data }, the earlier single webhook migrated to an endpoint
2026-11-01{ id, type, apiVersion, createdAt, tenantId, projectId, roomId?, data }, the default for new endpoints

Event data grows additively like the API. To move a receiver to a newer payload version, add a second endpoint with the new version, switch your processing, then remove the old endpoint.

GET /v1/capabilities reports contractVersion, which changes whenever the customer contract gains something. SDKs can use it to enable newer features only where the API already supports them.

RTC’s customer routes are described in OpenAPI 3.1, generated from the schemas the API validates requests with and checked against the code on every change. The file is docs/openapi/v1.yaml in the RTC platform repository. Contact CHAMPREP to receive the current file for client generation; this reference and the API reference remain the public documentation.