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.

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.

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.

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.

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.

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.