API reference

Versioning and deprecation

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

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 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.
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

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.

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.