# Versioning and compatibility

This page is the stability contract for the Rho API. It states what may change in a released
version, what may not, and the notice you can expect before anything is deprecated.

## Versioning model

The Rho API is versioned per release; today that's the URL path `/api/v1`. The current version is `v1`.

**`v1` is stable and additive-only**. A request that works today keeps working. Changes that would
break existing code require a **new API version**; we do not ship them into `/api/v1`.

Any `v1` deprecation or sunset comes with **at least 15 days' notice** before the change takes effect.

## What can change without a new version

The following are **non-breaking** and can ship into `v1` at any time. Build your app so these
never break it:

- A new enum value.
- A new nullable response field.
- A new optional query parameter.


## What requires a new version

The following are **breaking**. They will not ship into `v1`; they require a new API version:

- Removing or renaming an enum value.
- Removing a response field.
- Changing a field's type.
- Making an optional field required.


## Client obligations

Because the additive changes above ship without a version bump, write your code to tolerate them:

- **Handle unknown enum values gracefully.** A value set grows as Rho adds new products and rails, so
a field such as `transaction_type` can return a value your code has not seen before. Give any
`switch` on it a default case so a new value shows up as unknown rather than an error.
- **Handle new response fields gracefully.** Ignore fields you do not recognize rather than failing to
parse the response, so a field added later never breaks deserialization.
- **Treat IDs as opaque strings.** Do not parse structure out of an `id` or assume a fixed format; use
it only as a whole value to look records up and reference them.
- **Store IDs as-is.** Persist the full string exactly as returned, without assuming a fixed length or
layout.


## MCP parity

The MCP server is 1:1 with the REST API, so the `/mcp/v1` tool schemas follow the same policy as the
REST contracts above: additive-only, with breaking changes requiring a new version. One policy covers
both surfaces.

Tool *names* derive from the frozen `v1` operationIds, so **tool names will never change**. You can
reference them explicitly in workflows, agent skills, and saved automations without them breaking.

Tool *descriptions* are not part of the contract - they may be improved at any time to help agents use
the tools well, and such changes are never treated as breaking.