/api/v1/….
v1 only grows
These arrive in v1 at any time, without notice, and your code should expect them:- A new endpoint.
- A new field in a response. Read the fields you need and ignore the rest.
- A new optional field in a request.
- A new value in a list of choices — a new skill, a new option, a new format.
- A new error
code. Treat a code you don’t know by its HTTP status. - A new response header.
- A field removed or renamed, or its type changed.
- A required field added to a request.
- An error
coderenamed, or a status code changed for the same failure. - An endpoint removed, or its path or method changed.
Breaking changes wait for v2
A change that could break working code ships under/api/v2. v1 keeps working beside it.
When v2 replaces something in v1, we announce it in the Changelog at least six months before the v1 version stops answering. From the day it is announced, every response from the old endpoint carries two standard headers:
Deprecation and you will have months to move. Nothing in v1 is deprecated today.
MCP
The MCP server follows the same rules: tools and fields are added, never removed or renamed in place. It negotiates the MCP protocol revision with your client oninitialize.
