What counts as a breaking change to the REST API, MCP tools, CLI and SDKs, how much notice you get, and how to pin a version.
An integration that works today keeps working for at least 90 days after we announce a change that would break it. This page says what counts as breaking, how we announce it, and how to pin the version you built against.
Notice periods
Surface
Notice before a breaking change
How you pin
REST API
90 days
Sailfork-Version: YYYY-MM-DD header
MCP tools
90 days
sailfork/toolSchemaVersion in initialize
TypeScript and Python SDKs
90 days, with the REST API they wrap
The SDK release you install
CLI commands, flags and output
30 days while the CLI is at 0.x
The CLI release you install; sailfork upgrade --rollback goes back one
During the notice period the old behavior and the new one both work. A security fix can shorten it when keeping the old behavior would leave accounts exposed. We say so in the announcement.
What counts as breaking
A change is breaking when a call, command or script that worked before can now fail, or succeed with a different meaning:
A route, tool, command or flag is removed or renamed.
A request field, tool argument or flag becomes required, or accepts fewer values than before.
A response field is removed, renamed, or changes type.
A default changes what happens when you leave a value out, such as a page size or whether a call waits.
An exit code or error code changes meaning.
A token needs a scope it did not need before.
These are not breaking, so they ship without notice:
New routes, tools, commands, flags and optional arguments.
New fields in a response, and new values in a response enum. Ignore fields you do not know, and treat an unknown enum value as "other".
New error codes for a case that failed before.
Wording of human-readable messages. Match on error.code, never on the message.
Faster answers, higher limits and bug fixes that make a call do what its docs already said.
How we announce it
Every breaking change appears in the changelog with a Breaking label and what to change, and in the changelog feed. We also email the owners of access tokens that used the affected route or tool in the last 30 days, at the start of the notice period.
REST API
Send Sailfork-Version with the date of the API version your client was written against. A breaking change ships as a new date. The previous date keeps its behavior for at least 90 days after the new one is announced, and the REST API overview lists the dates that work today. A request with no header gets the newest version, so pin it in anything that runs unattended.
MCP tools
The server's initialize result carries two values in _meta, and so does the server card at /.well-known/mcp/server-card.json:
Key
Meaning
sailfork/toolSchemaVersion
The date of the last breaking change to any tool's arguments. Compare it with the date you built against.
sailfork/toolSchemaDigest
Changes with every change to any tool's arguments, breaking or not. Use it to refresh a cached tool list.
When a tool is renamed, or an argument is renamed or narrowed, the old name and shape keep working for 90 days next to the new one. Tool results are text and JSON written for models to read. A change in their wording is not breaking, but a change in a JSON field follows the rules above.
CLI
The CLI is at 0.x. A command, flag, exit code or --json field that changes in a breaking way keeps its old form for 30 days. The server refuses a CLI older than the minimum release with 426 and the command to upgrade. We raise the minimum only for a security fix or after the same 30 days of notice.