This policy explains how we change the Rally & Roam API and MCP server, and the notice you get before a change could break your integration.

Versions

The API version is in the path: /partner-api/v1. The API reference in the developer centre carries its own version number, which goes up with every published change.
The MCP server supports the protocol versions it lists in server/discover and in answer to initialize. When a new protocol version is published we add it, and keep older ones for as long as widely used clients need them.

Changes we may make at any time

Adding endpoints, MCP tools, optional parameters, response fields, headers, enum values and error codes.
Changing the wording of messages, descriptions and documentation.
Fixing behaviour that does not match the documentation, so that it does.

Build your client to ignore fields it does not know and to handle an unknown error code by its HTTP status.

Breaking changes

Removing or renaming an endpoint, tool, parameter or field, changing a field's type or meaning, or making something optional required, is a breaking change. Before one:

we give at least 90 days' notice by email to every developer account owner, and in the changelog in the developer centre;
we mark the old behaviour deprecated in the API reference during the notice period;
where the change is large, we publish it as a new version (/v2) and keep the old version working until its announced end date.

We may give less notice only where security, the law or a provider of open data leaves us no choice, and we will say why.

Before general availability

Until we announce general availability of version 1, we may make breaking changes with shorter notice. We record every one in the changelog. Version 1.2.0 of the description was such a change: it unified the item shape for every key and the shape of lists.

Where to follow changes

The changelog in the developer centre lists every change with its date. Notices go to the email address of each developer account owner.

API deprecation and versioning