---
title: "API versioning and deprecation policy"
description: "How the Amnesia plugin API versions change over time, and what happens to deprecated surfaces."
canonical: https://amnesia-docs.pages.dev/api/deprecation/
source: "src/content/docs/api/deprecation.md"
---

# API versioning and deprecation policy

The Amnesia plugin API is versioned so automations built against today's contracts keep working
across releases. This page is the authoritative deprecation policy referenced by the published
[OpenAPI specification](/openapi.json).

## Current stable version

Version **1.x** (`v1`) is the current stable surface. All documented commands, events, and
capability requirements in this reference describe `v1` behavior.

## What counts as a breaking change

- Removing or renaming a command, event name, or capability.
- Changing the shape of a payload field from one type to another (for example, string to enum).
- Tightening a capability requirement so an existing call begins raising `PermissionError`.
- Removing support for an event handler that currently fires.

Additive changes — new optional fields, new command methods, new event names that do not alter
existing handlers — do not bump the major version.

## Deprecation process

When a `v1` surface is scheduled for removal:

1. The surface is marked `deprecated` in the OpenAPI specification and its reference page notes
   the deprecation.
2. A replacement surface, if any, is documented alongside the deprecated one.
3. The deprecated surface continues to function for at least one full minor release cycle after
   the announcement release.
4. Removal happens only in a major version bump (`v2`), which ships behind a new version prefix
   while `v1` remains callable during an overlap window.

## Sunset communication

Breaking-change announcements accompany each plugin release. Agents and automations should read
the [API overview](/api/overview/) and [release notes](/getting-started/installation/) as their
change-detection source, and prefer capability-scoped handles acquired through `connect()` so
permission changes surface as explicit `PermissionError` failures rather than silent behavior
shifts.

## Rate limit conventions

The plugin API is an in-process surface and is not subject to network throttling. Where Amnesia
surfaces are exposed through HTTP-style tooling (agents, proxies, or future hosted endpoints),
responses follow RFC 9331 and RFC 8594 conventions:

- `RateLimit-Policy` declares the quota (`600;w=60` in the published OpenAPI contract).
- `RateLimit` reports live consumption (`limit`, `remaining`, `reset`).
- Exhausted quotas return `429` with a `Retry-After` header and an RFC 9457 problem-details body.
- Deprecated operations emit `Deprecation`, and later `Sunset`, per the timeline above.

Agents should read these headers and self-throttle rather than polling on failure.

## Questions

If a planned change would break your automation, raise it through the channels listed on the
[contact page](/contact/) before the next minor release.