--- title: "API versioning and deprecation policy" canonical: "https://saaskly.com/api-deprecation-policy" last-updated: "2026-09-09" --- # API versioning and deprecation policy *Last updated: 29 August 2026* This policy covers every machine-readable interface Saaskly publishes: the REST read API (`/api/v1/` and its legacy alias `/api/`), the MCP server at `/mcp`, the Markdown mirrors (`.md`), `/llms.txt` and the discovery manifests under `/.well-known/`. ## Versioning - The REST API is versioned in the URL path. The current version is **v1**: `https://saaskly.com/api/v1/`. - The un-prefixed `/api/` paths are a legacy alias of v1. They behave identically and will be retired under the same process as any other breaking change. - The MCP server, Markdown mirrors and manifests are unversioned; changes to them follow the same notice rules below. - The OpenAPI description at [/openapi.json](/openapi.json) is the contract. Its `info.version` changes on every breaking change. ## What counts as a breaking change Removing or renaming a field, endpoint, tool, resource or query parameter; changing a field's type or meaning; tightening validation so a previously valid request fails; changing the URL of a stable document; removing a category slug from the `CategorySlug` enum. **Not breaking, shipped without notice:** new fields, new endpoints, new MCP tools, new categories and category slugs, new optional parameters, more permissive validation, new headers, and changes to prose content, scores or rankings (which are editorial and change constantly). ## Notice period and signals - Breaking changes are announced **at least 90 days** before they take effect, in the changelog on [/developers](/developers) and in the OpenAPI description. - From the announcement, affected endpoints send a `Deprecation` header (RFC 9745) with the date the change was announced and a `Sunset` header (RFC 8594) with the date it takes effect, plus a `Link` header with `rel="deprecation"` pointing at the announcement. - A new major version, if one is ever needed, runs alongside the old one for the whole notice period. - Nothing is currently deprecated. ## Rate limits and retries 300 requests per 60 seconds per client IP, announced with `RateLimit-*` headers and enforced with `429` + `Retry-After`. POST endpoints honour `Idempotency-Key`. Details on [/developers](/developers). ## Contact Questions, or a use case this policy would break: [help@saaskly.com](mailto:help@saaskly.com). --- Researched and drafted with AI assistance; reviewed and approved by Tim Meredith. See https://saaskly.com/ai-transparency.md and https://saaskly.com/editorial-policy.md. Canonical HTML: https://saaskly.com/api-deprecation-policy ยท Markdown index: https://saaskly.com/llms.txt