Skip to content

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

SurfaceNotice before a breaking changeHow you pin
REST API90 daysSailfork-Version: YYYY-MM-DD header
MCP tools90 dayssailfork/toolSchemaVersion in initialize
TypeScript and Python SDKs90 days, with the REST API they wrapThe SDK release you install
CLI commands, flags and output30 days while the CLI is at 0.xThe 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:

KeyMeaning
sailfork/toolSchemaVersionThe date of the last breaking change to any tool's arguments. Compare it with the date you built against.
sailfork/toolSchemaDigestChanges 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.

Loading Sailfork