# Versioning and deprecation

> How Kanorio versions its APIs, what counts as a breaking change, and how deprecations are announced before anything is removed.

> Markdown version of https://kanorio.com/en/developers/basics/versioning. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp

All three APIs are versioned in the URL as `/api/v1`. Compatible changes ship continuously without a new version. Breaking changes follow the process on this page. The APIs are currently in **beta**: shapes can still change, and every change is announced in the [changelog](https://kanorio.com/en/developers/changelog) first.

## Compatible changes

These ship at any time, so write clients that tolerate them:

- New endpoints, operations, MCP tools and webhook events.
- New optional request fields and query parameters.
- New response fields. Ignore fields you do not know.
- New error codes. Handle unknown codes by their HTTP status, as described in [Errors](https://kanorio.com/en/developers/basics/errors).
- New permissions, and looser validation that accepts more values.

## Breaking changes

These never ship silently:

- Removing or renaming an endpoint, operation, tool or field.
- Changing a field's type or meaning, or making an optional field required.
- Changing an error code or its HTTP status.
- Tightening validation, or changing the permission an operation needs.

On a stable operation, a breaking change goes through deprecation, and a new URL version keeps the old one available for at least six months. During the current phase, breaking changes are listed in the changelog the day they ship.

## How a deprecation reaches you

When an operation is deprecated, every channel tells you at once:

| Where | What you see |
|---|---|
| Response headers | `Deprecation` with the date it was deprecated, `Sunset` with the removal date, and `Link` headers to this policy and to the replacement |
| OpenAPI | `deprecated: true`, `x-kanorio-sunset` and `x-kanorio-replaced-by` on the operation |
| MCP | The tool description starts with `[Deprecated, removed after …; use …]` |
| API reference | A deprecated badge with the removal date and the replacement |
| CLI | A warning on stderr |
| Email | Token owners who called the operation in the last 30 days get a reminder before removal |

```http
Deprecation: @1788134400
Sunset: Sat, 01 May 2027 00:00:00 GMT
Link: <https://kanorio.com/en/developers/basics/versioning>; rel="deprecation"
```

An operation is removed only after its sunset date has passed.

## Release phases

Each operation and each product has a release phase. See [Release phases](https://kanorio.com/en/developers/basics/release-phases).

## SDK, Elements and MCP versions

- `@kanorio/sdk` and `@kanorio/elements` follow semantic versioning. Rules that change often, such as bot protection, crawler block lists and redirects, are served by the API, so deployed front ends pick them up without upgrading.
- The MCP server publishes a semantic version in `serverInfo` and in its registry entry. A major version means existing calls may behave differently. The changelog names the version each time it changes.