Surp API versioning & deprecation policy

The current stable API version is v1, served under https://surp.ivc.lol/v1 (URL path versioning).

What counts as breaking

• Removing or renaming an endpoint, field, or error code
• Changing a field's type or making an optional field required
• Changing auth semantics or payment flow requirements

Additive changes are not breaking and may ship at any time: new optional request fields, new response fields, new routes, new models.

Deprecation & sunset process

1. Breaking changes are announced on this page and in llms.txt at least 90 days before taking effect.
2. From that moment, every affected response carries a Deprecation: true header (RFC 9745) and a Sunset: <HTTP-date> header (RFC 8594) with the removal date.
3. During the window the old behavior keeps working unchanged; after the Sunset date the endpoint may return 410 Gone with a Problem body pointing at the successor.

Clients should treat any Sunset header as authoritative and migrate before the date. The machine-readable form of this policy is x-deprecation-policy in the OpenAPI 3.1 specification.