This page is the stability contract for the Rho API. It states what may change at each release stage, what may not, and the notice you can expect before a change takes effect.
The Rho API is versioned per release; today that's the URL path /api/v1. The current version is v1. A resource's badge in the documentation identifies its release stage.
| Stage | Where it is published | Contract |
|---|---|---|
| Beta | v1, with a Beta badge | Additive changes are normal. Breaking changes are possible with notice while we incorporate customer feedback. |
| GA | v1, with no badge | Frozen to additive changes. Breaking changes require a new API version, and deprecations follow a published timeline. |
A new resource normally launches in v1 with a Beta badge. Untagged v1 resources are generally available (GA).
A Beta resource is live for any business whose API Access Token has the required scope, but its contract is still open to change. We may make additive changes or, with notice, make a breaking change without creating a new API version. Do not depend on Beta behavior remaining unchanged.
An untagged v1 resource is GA. A request that works today keeps working. Changes that would break existing code require a new API version; we do not ship them into that GA resource in /api/v1.
Any GA deprecation or sunset comes with at least 15 days' notice before the change takes effect.
The following are non-breaking and can ship into a GA resource 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 for a GA resource. 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_typecan return a value your code has not seen before. Give anyswitchon 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
idor 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 release stage of the corresponding REST resource. Beta tools may change with notice; GA tools are additive-only, with breaking changes requiring a new version.
For GA resources, tool names derive from frozen v1 operationIds, so tool names will never change. You can reference them explicitly in workflows, agent skills, and saved automations without them breaking. Beta tool names can change with notice.
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.