> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mediamonster.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> v1 only grows. A change that could break your code waits for v2, and v2 is announced at least six months before anything in v1 stops.

The API's version is in its path: `/api/v1/…`.

## v1 only grows

These arrive in v1 at any time, without notice, and your code should expect them:

* A new endpoint.
* A new field in a response. Read the fields you need and ignore the rest.
* A new optional field in a request.
* A new value in a list of choices — a new skill, a new option, a new format.
* A new error `code`. Treat a code you don't know by its HTTP status.
* A new response header.

These never happen in v1:

* A field removed or renamed, or its type changed.
* A required field added to a request.
* An error `code` renamed, or a status code changed for the same failure.
* An endpoint removed, or its path or method changed.

New changes are listed in the [Changelog](https://docs.mediamonster.app/api/changelog.md).

## Breaking changes wait for v2

A change that could break working code ships under `/api/v2`. v1 keeps working beside it.

When v2 replaces something in v1, we announce it in the [Changelog](https://docs.mediamonster.app/api/changelog.md) at least **six months** before the v1 version stops answering. From the day it is announced, every response from the old endpoint carries two standard headers:

| Header | What it says |
| - | - |
| `Deprecation` | When it was deprecated, as `@` and a unix time ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) |
| `Sunset` | The date it stops answering, as an HTTP date ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) |
| `Link` | This page, or the one that says what to move to, with `rel="deprecation"` |

```http theme={"theme":{"light":"github-dark","dark":"github-dark"}}
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://docs.mediamonster.app/api/versioning>; rel="deprecation"
```

Log a warning when you see `Deprecation` and you will have months to move. Nothing in v1 is deprecated today.

## MCP

The [MCP server](https://docs.mediamonster.app/mcp.md) follows the same rules: tools and fields are added, never removed or renamed in place. It negotiates the MCP protocol revision with your client on `initialize`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.