# Versioning and breaking changes

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](https://sailfork.com/changelog) with a Breaking label and what to change, and in the [changelog feed](https://sailfork.com/changelog/rss.xml). 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](https://sailfork.com/docs/api#api-versions) 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.

---

Every docs page: https://sailfork.com/llms.txt
