# Roomly API versioning and deprecation policy

> How the Roomly API and MCP servers change, and how long an old version keeps working.

## Versions

The API version is part of the path: `/api/v1`. The MCP servers carry their version in the server card.

## What can change in a version

Only backward-compatible changes: new endpoints, new optional parameters, new fields in a response, new error codes for new situations, and better descriptions. Clients must ignore response fields they do not know.

## Breaking changes

Versioning: the version is in the path (/api/v1). v1 only gets backward-compatible changes (new optional parameters, new response fields). A breaking change ships as /api/v2; v1 then keeps working for at least 6 months, and its responses carry Deprecation and Sunset headers (RFC 9745, RFC 8594) with a Link to the migration notes.

## Deprecation and sunset

- A deprecated version answers with a `Deprecation` header (RFC 9745) giving the date it was deprecated.
- It also answers with a `Sunset` header (RFC 8594) giving the date it stops working, at least 6 months later.
- A `Link` header with `rel="deprecation"` points to the migration notes.
- The change is announced in https://room-ly.org/llms.txt and on this page.

## Current status

- `/api/v1`: current, not deprecated.
- MCP servers https://room-ly.org/mcp and https://room-ly.org/mcp/docs: current, not deprecated.
