Skip to content
RoxyAPI
Quick StartPlaygroundSDKMCP SetupFree TemplatesAGENTS.md
  1. Docs
  3. Getting Started
  5. Versioning and Deprecation

Astrology API versioning and deprecation policy

Every RoxyAPI endpoint lives under a version prefix, currently /api/v2, and that prefix is a promise: code written against it keeps working. The rules below are a summary. The binding text is Terms of Service section 4.1, which sets the notice period, and it is the page to quote in a vendor assessment.

What can change inside a version

Only additions. A version can gain new endpoints, new optional request parameters, new response fields and new enum values. Nothing inside a version is removed or renamed, and no field changes its type, so a client that ignores fields it does not know keeps working through every release.

Two habits keep an integration safe against additions:

  • Read the fields you use and ignore the rest, rather than validating the whole response against a closed schema.
  • Handle an enum value you have not seen before, for example by falling back to a default branch, rather than assuming the list you coded against is complete.

What a breaking change looks like

A change that could break a working client ships under a new version prefix, never inside the current one. The previous version keeps answering while you move, for the notice period set in the Terms.

How an endpoint or a version is retired

Retirement is announced on the changelog and by email to active subscribers before it takes effect, and the endpoint keeps working for the whole notice period. The same terms apply on every plan. The changelog is also served as an RSS feed, so a build pipeline or a team channel can follow it.

Where the contract lives