Saaskly

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 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 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.

Contact

Questions, or a use case this policy would break: help@saaskly.com.