API versioning and deprecation

Speko's stable REST operations use a major version in the URL, beginning with /v1. Backward-compatible fields, enum values, and endpoints may be added within v1. A change that removes a field, changes its meaning, or makes a previously valid request invalid requires a new major path. The OpenAPI 3.1 contract is the language-neutral source for current request and response shapes.

No v1 operation is currently deprecated. Before Speko removes a stable operation, the response will carry the RFC 9745 Deprecation header and a Link with the deprecation relation to its migration instructions. A dated Sunset header will be announced at least 90 days before shutdown. The same change appears in the dated public changelog, JSON Feed, and RSS feed with an effective date, sunset date, and concrete migration action.

• Compatible change. Continue using v1; tolerate unknown response fields and enum values where the contract allows them.
• Deprecated operation. Follow the linked migration and move before the advertised Sunset date.
• Model identifiers. A renamed model keeps an input alias; catalog and response headers publish the canonical identifier.

Router errors use a JSON error object with stable code, message, hint, and retryable fields. Every public Router response advertises the default edge quota as RateLimit-Policy: "relay-ip";q=2000;w=300: 2,000 requests per five-minute window for each public source IP. Organization and provider concurrency controls can impose a lower effective limit. An application-generated 429 also includes Retry-After; agents must wait at least that long and then continue with exponential backoff rather than retrying in a tight loop.