4626.fun API versioning

This is the named 4626.fun versioning and deprecation policy. The public Agent API is versioned in the URL path as /api/v1/. Agents should pin to v1. A new major version, if shipped, will live at /api/v2/ and will not silently replace v1.

Compatibility

Additive fields on JSON objects are not a breaking change. Removing a field, renaming a path, or changing a status code for a success path is a breaking change and requires a new URL version or a documented deprecation window. OpenAPI info.version tracks the v1 document revision, not a second public surface.

Deprecation signals

DeprecationDeprecated operations send Deprecation: true (RFC 9745).

SunsetThe same responses send an HTTP-date Sunset header (RFC 8594) for the earliest removal instant.

LinkLink: </developers/versioning>; rel="deprecation" points here.

OpenAPIDeprecated operations set deprecated: true in /openapi.json.

Window

4626.fun keeps a deprecated v1 operation available for at least 90 days after the Sunset date is first advertised, unless the route is already gone (HTTP 410) because it was replaced by an automatic path. The XMTP AMOE check-in POST is an example of a retired route: it returns 410 with Deprecation and Sunset headers. Prefer the documented replacement in the OpenAPI description.