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:

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

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 [email protected] and say which endpoints you depend on.