RTC API versioning
The /v1 promise
Section titled “The /v1 promise”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.
Pin response shapes with RTC-Version
Section titled “Pin response shapes with RTC-Version”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| Version | Changes |
|---|---|
| none | Original shapes. Errors are { "error": "<message>", "code"? }. |
2026-11-01 | Errors 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.
Pin webhook payloads with apiVersion
Section titled “Pin webhook payloads with apiVersion”Each webhook endpoint has an apiVersion that fixes the
envelope it receives, independent of request headers:
apiVersion | Envelope |
|---|---|
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.
Contract version for SDKs
Section titled “Contract version for SDKs”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.
OpenAPI description
Section titled “OpenAPI description”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.