> ## Documentation index
> Fetch the complete documentation index at: https://developer.rhombus.com/llms.txt
> Use it to discover all available pages before exploring further.

# Versioning and Deprecation

> How the Rhombus REST API changes over time: new operation versions such as spliceV3, deprecated operations and their replacements, Deprecation and Sunset headers, changes made without a new version, and how to write clients that keep working.

The Rhombus REST API has a single version. There's no version header and no version in the URL: every operation lives at `/api/<service>/<operation>`.

## New versions of an operation

When an operation has to change in a way that would break existing clients, Rhombus adds a new operation with a version suffix and keeps the old one. For example, [`spliceV3`](https://developer.rhombus.com/api-reference/video-webservice/splice-v3) sits alongside `splice` and `spliceV2`, and [`getSavedClipsV2`](https://developer.rhombus.com/api-reference/event-webservice/get-list-of-saved-clips-in-organization) alongside `getSavedClips`. Use the highest version that exists unless the reference says otherwise.

## Deprecated operations

The old operation is then marked deprecated:

- The [API Reference](https://developer.rhombus.com/api-reference/overview) labels it **Deprecated** and, when there is one, links to the replacement. The sidebar hides deprecated operations unless you turn on **Show deprecated operations**.
- The [OpenAPI specification](https://api2.rhombussystems.com/api/openapi/public.json) marks it `deprecated: true`, so generated clients flag it too.

Deprecated operations keep working, but they get no new features. Move to the replacement when you next work on that part of your integration. If an operation is eventually retired, it answers with `"error": true` and an `errorMsg` saying so; see [Errors](https://developer.rhombus.com/errors).

## Deprecation and Sunset headers

When a way of calling the API is scheduled to stop working, responses to requests that still use it carry two headers:

```text Deprecated request
Deprecation: true
Sunset: Tue, 05 Jan 2027 00:00:00 GMT
```

- `Deprecation: true` means the request relied on something deprecated. The request itself still succeeds.
- `Sunset` is the date after which the same request fails with an error.

For example, a [partner credential](https://developer.rhombus.com/partner-api-calls) that calls an endpoint outside `/api/partner/` without the `x-auth-org` header gets these headers, with the date above; after that date, the same request is an error. On the event WebSocket, such a connection is refused with 403 `PERMISSION_REQUIRED`. Send `x-auth-org` with the UUID of the organization to act in ([Scoping a call to a client organization](https://developer.rhombus.com/partner-api-calls#scoping-a-call-to-a-client-organization)).

Log every response that carries `Deprecation`, with the operation and the `Sunset` date, so you find these calls before the date.

## Changes without a new version

These changes can appear in the existing API at any time; notable ones are announced in the [Changelog](https://developer.rhombus.com/changelog):

- New operations.
- New optional fields in requests.
- New fields in responses.
- New values in enums, such as a new alert or event type.

Write clients that tolerate them:

- **Ignore response fields you don't use**, and don't fail on ones you don't recognize. Most JSON libraries do this by default; strict deserializers (for example Jackson with `FAIL_ON_UNKNOWN_PROPERTIES`) need it turned off.
- **Handle enum values you don't know**, for example by logging them and skipping the item, rather than throwing.
- **Treat a missing field as null.** Fields with null values are left out of responses.
- **Don't depend on the order** of fields in a response or of items in a list, unless the operation documents an order.

## Staying informed

- The [Changelog](https://developer.rhombus.com/changelog) lists notable changes, with an [RSS feed](https://developer.rhombus.com/changelog/rss.xml).
- The OpenAPI specification's `info.version` doesn't change between releases. To see exactly what changed, keep a copy of the specification and compare it with the current one.