API Versioning and Deprecation Policy
Effective August 24, 2026
Stable versions
Public REST endpoints carry their major version in the URL, such as/api/v1/reading. Within one major version, Runestone may add optional response fields, enum values where clients are expected to tolerate extension, new endpoints, and clarifying documentation. Existing required fields and documented semantics will not be removed or incompatibly changed without a new major version.
Deprecation notice
Runestone intends to announce a breaking retirement at least 90 days before shutdown when security, abuse, legal, or upstream platform constraints do not require faster action. A deprecated response will include the RFC 9745 Deprecation header, a Link with rel="deprecation" to migration guidance, and, once a removal date is chosen, the RFC 8594Sunset header. Current endpoints link this policy but do not send a Deprecation date because v1 is active.
Client expectations
Integrations should ignore unknown optional fields, parse errors by their machine-readable code, follow rate-limit guidance, and monitor response Link, Deprecation, and Sunset headers. OpenAPI, llms.txt, agent instructions, MCP metadata, and the npm package are updated alongside the production API. Questions about a migration can be sent to evan@runestonelabs.io.