# Deprecation policy

The public HTTP API is versioned in the URL path. The current major version is /api/v0. A breaking change ships as a new major path, such as /api/v1, and does not silently replace /api/v0. Adding an endpoint or an optional field is not a break. Removing or renaming a field is.

When a version is scheduled for removal, responses on that version carry two headers. Deprecation, from RFC 9745, is an HTTP-date for the moment the version was deprecated. Sunset, from RFC 8594, is an HTTP-date for the moment it stops. The Sunset date is at least 90 days after Deprecation. A Link header with rel="deprecation" points at this page. Until those headers are present, that version has no removal date.

/api/v0 has no scheduled sunset. The contract can still gain endpoints. Removals and renames wait for a new major path plus the Deprecation and Sunset headers. The machine-readable contract stays at /api/v0/openapi.json. This policy is the timeline agents can rely on.

Rate limits are separate from deprecation. Each server instance allows 120 requests per client IP per 60 seconds. Responses send RateLimit-Policy and RateLimit, using the IETF structured fields. A 429 also sends Retry-After, which is the header to obey. The counter lives in that instance, not in one global bucket, because the host is serverless.