# Yappy API versioning and deprecation policy

An API that can change under you without warning is not one an agent should
integrate against. This page is the promise.

## Versioning

The major version lives in the URL path: **`https://yappy.biz/api/v1`**.

Every response also carries a dated **`API-Version`** header — for example
`API-Version: 2026-08-25` — naming the build of `v1` that answered. Quote it
when you report a problem; it is how we know which behaviour you saw.

## What ships without notice

Additive changes land inside `v1` at any time:

- New endpoints.
- New optional request parameters.
- New fields on an existing response object.
- New members of an enum in a response.
- New error `code` values (the shape stays the same).

**Parse leniently.** Ignore fields you do not recognise rather than failing on
them, and treat an unknown `code` as its HTTP status class.

## What counts as breaking

Anything below gets a new major version instead:

- Removing or renaming a field, endpoint, or enum member.
- Changing a field's type, or making an optional parameter required.
- Changing the meaning of an existing error `code`.
- Tightening a validation rule so a previously valid request is refused.

## The signals

When a version is scheduled for removal, **every response from it** carries:

```
Deprecation: Sat, 01 Feb 2026 00:00:00 GMT
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Link: <https://yappy.biz/developers/deprecation>; rel="deprecation"
Link: <https://yappy.biz/api/v2>; rel="successor-version"
```

`Deprecation` is when we started saying so. `Sunset` (RFC 8594) is when the
endpoint stops answering. **There will be at least 180 days between them.**

The same information is machine-readable at
[`GET /api/v1`](https://yappy.biz/api/v1) under `versioning`, and in the
OpenAPI spec under `x-deprecation-policy`.

## After the sunset

A retired version answers **`410 Gone`** — not `404`, which would suggest you
had the URL wrong — with a problem document naming its successor. You can see
this today, because v0 has already been through it:

```bash
curl -i https://yappy.biz/api/v0/releases
```

```
HTTP/2 410
Deprecation: Sat, 01 Feb 2026 00:00:00 GMT
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Link: <https://yappy.biz/developers/rest-api>; rel="deprecation",
      <https://yappy.biz/api/v1>; rel="successor-version"
```

## Current status

| Version | Status | Deprecated | Sunset |
|---|---|---|---|
| `v1` | **Current** | — | — |
| `v0` | Retired | 2026-02-01 | 2026-08-01 |

`v1` carries no `Deprecation` header, and no successor is planned. If that
changes, you will read it here and in the headers 180 days before it matters.

## MCP and the well-known documents

The MCP servers negotiate their protocol version in the `initialize` handshake
and accept `2024-11-05`, `2025-03-26`, and `2025-06-18`, answering with
whichever you asked for. The `.well-known` discovery documents are versioned by
their own specs, not by ours.

## Being told

There is no mailing list to join. The signals travel with the responses you are
already making, which is the only mechanism an autonomous agent can act on. If
you would like a human heads-up as well, mail **support@yappy.biz** and say
which endpoints you depend on.

---

Canonical: https://yappy.biz/developers/deprecation/ · Last updated: 2026-08-25