Astrology API Versioning: How to Verify a Stable Contract

Every astrology app sits on a contract it did not write. The natal chart your onboarding renders, the daily horoscope your push job sends, the compatibility score your matching screen sorts on: each is a field some vendor promised to keep returning in the same shape. When that promise is vague, the first sign of a breaking change is a crash report.

Astrology API versioning is how a provider makes that promise checkable. This guide gives you six checks that work against any provider, what a good answer looks like for each, and the exact commands to verify it yourself rather than trusting a sales page. Each check ends with what the RoxyAPI Astrology API does, stated as fact, so you have one worked example to compare the rest against. Almost none of it needs an account: the documents you check are public.

What makes an astrology API contract stable?

A stable API contract is one where the code you ship today keeps working without changes until you choose to move. Five things make that true: a version on every request, a written rule that the version only grows, a notice period before anything is retired, a public machine-readable spec, and error codes that keep their meaning. A sixth, a changelog feed, tells you when any of it moves.

The table is the whole checklist. The sections below show how to run each check.

Ready to build on a contract you have checked? The RoxyAPI Astrology API runs every domain on one key under this versioning policy. See pricing.

How do you check the version and the change rule?

Check the version by reading the server URL in the spec, and check the change rule by finding where it is written and whether it binds the vendor. A path version such as /v2 shows in every request and every log line. A header version works as well when the provider pins a default to your account and says so; the red flag is no version at all. The rule matters more than the number: a version protects you only if the provider says what may change inside it.

Two commands answer the first half for any provider that publishes an OpenAPI document:

curl -s https://roxyapi.com/api/v2/openapi.json -o spec.json
jq -r '.servers[].url' spec.json
# https://roxyapi.com/api/v2

For the second half, look for three things in writing: which changes a version allows, where a breaking change goes, and how long you get before a retirement.

RoxyAPI: the Terms of Service, section 4.1 states that within a version the API only adds endpoints, optional parameters, response fields and enum values, and never removes or renames a field, changes its type, or removes an endpoint. A breaking change ships under a new version prefix. A retirement is announced on the public changelog and by email to active subscribers at least 90 days ahead, the endpoint keeps working throughout, and this holds on every plan, with an exception only where a security or legal requirement leaves no room for the full period. The plain-language summary is on the versioning and deprecation page. The other terms worth reading before you sign, from data ownership to benchmarking rights, are in the astrology API contract terms guide.

How do you diff two OpenAPI snapshots yourself?

You diff two OpenAPI snapshots by saving the provider spec on two dates and running an OpenAPI diff tool that classifies each change as breaking or additive. This is the only check that does not rely on the vendor telling the truth, because it compares what they published, not what they promised. It takes three steps, and the third runs in CI.

1. Save a baseline today. Store the file in your repo with the date in its name, so the contract you built against is part of your own history.
2. Compare the live document against it. The open source tool oasdiff reads two OpenAPI files and prints every change that could break an existing caller.
3. Fail your build when a break appears. --fail-on ERR exits non zero, so a scheduled job turns a silent vendor change into a red check. The default rules count a new response enum value as an error, so a one-line severity file lowers that rule to info when the contract allows new values. Pin the tool version so the rules do not move under you.

curl -s https://roxyapi.com/api/v2/openapi.json -o contract-2026-09-25.json
echo "response-property-enum-value-added info" > oasdiff-levels.txt

go run github.com/oasdiff/oasdiff@v1.32.1 breaking \
  contract-2026-09-25.json https://roxyapi.com/api/v2/openapi.json \
  --fail-on ERR --severity-levels oasdiff-levels.txt
# No changes detected

A lighter check needs only jq: list every operationId in each snapshot and ask which ones disappeared. An empty result means no operation was removed or renamed, and every operationId is a method name in a generated SDK.

jq -r '[.paths[][] | objects | .operationId] | sort[]' old.json > old-ops.txt
jq -r '[.paths[][] | objects | .operationId] | sort[]' new.json > new-ops.txt
comm -23 old-ops.txt new-ops.txt

RoxyAPI: the combined document at /api/v2/openapi.json is public, needs no key, and covers every endpoint in one file, so one baseline covers all 18+ domains. Every RoxyAPI release is diffed against the last committed contract with breaking-change rules of the same kind before it ships, so a removed field or a renamed operation cannot go out unnoticed.

How do you read a breaking-change report without false alarms?

Read each finding as a question about your own code: does the request you send, or a field you read, change? A diff tool reports every change that could break some caller, and it knows nothing about the provider rule or your client. Two classes of finding need a second look before you open a support ticket.

A new enum value in a response. oasdiff reports an added response enum value as an error under its default rules, because a client with an exhaustive switch fails on a value it has never seen. A contract that allows new enum values is telling you to code for them: keep a default branch and never assume the list is complete. On an astrology API that means, for example, a new aspect type in a chart response.

A request type that became stricter on paper. A spec can tighten a parameter from number to integer, or publish a minimum and maximum, to describe validation the server already applied. The tool flags it either way. Settle it with one call: send the exact request your code sends, and if it still returns 200, the finding does not touch you.

RoxyAPI: the versioning page states the same two client habits in writing: read the fields you use and ignore the rest, and handle an enum value you have not seen before by falling back to a default branch.

Are the error codes stable enough to branch on?

Error codes are stable enough to branch on when the provider separates a machine code from the human message and promises the code keeps its meaning. Branching on an HTTP status alone is too coarse: a 401 can mean no key, a revoked key or a lapsed subscription, and each needs a different fix. Branching on the message text breaks the day someone improves a sentence.

This is a live 404 from the tarot card lookup, captured on 25 September 2026:

curl -s https://roxyapi.com/api/v2/tarot/cards/the-fool-of-cups \
  -H "X-API-Key: $ROXY_API_KEY"

{
  "error": "Card not found: the-fool-of-cups",
  "code": "not_found",
  "doc_url": "https://roxyapi.com/docs/errors#not_found"
}

A 400 adds an issues array listing every field that failed at once. Sending count: 2.5 to POST /tarot/draw returns validation_error with one issue on path: "count", so a client can fix the whole request in a single retry.

To check any provider, look for a published list of codes and ask whether it is machine-readable. RoxyAPI publishes every code, with its status and meaning, on the info object of the spec:

jq -r '.info["x-error-codes"][] | "\(.status // "any") \(.code)"' spec.json
# 400 validation_error
# ...
# any error

The last line is the fallback code error, which has no fixed status of its own.

RoxyAPI: every error body carries error (readable, wording may change), code (stable, the one to switch on) and doc_url (an absolute link to the fix for that exact code). The full list with the fix for each is on the error codes reference.

Where do you hear about a change before it lands?

You hear about a change through a feed your tooling reads and an email your team receives, and a buyer should ask for both. A changelog page nobody visits is not notice. A feed lets a build pipeline, a Slack channel or a feed reader pick up an announcement the day it ships, and email reaches the account owner who may never open either.

Check three things with any provider:

1. Is there a machine-readable feed? RSS or Atom, at a stable URL, with dated entries.
2. Does retirement notice go to email as well? A feed alone misses the person who pays the invoice.
3. Is the notice period the same on every plan? A period reserved for a higher tier leaves every other plan without one.

curl -s https://roxyapi.com/changelog/rss.xml | grep -c '<item>'

RoxyAPI: the changelog lists shipped capabilities newest first, and the same entries are served as an RSS feed at /changelog/rss.xml. A retirement is announced there and by email to active subscribers, at least 90 days ahead, on every plan. Because the typed SDKs for TypeScript, Python, PHP, C# and Go and the Remote MCP tools are all generated from the same OpenAPI document, a change you see in the spec diff is the change your SDK and your agent receive. No separate hand-written layer drifts behind it.

FAQ

What is a breaking change in an API?

A breaking change is any change that can make a working client fail without the client changing its code: a removed or renamed field, a changed field type, a removed endpoint, or a new required request field. Additions such as new endpoints, optional parameters and new response fields are not breaking for a client that ignores fields it does not use. RoxyAPI allows only additions inside a version and ships any breaking change under a new version prefix.

How does RoxyAPI version its API?

RoxyAPI versions its API by path prefix, currently /api/v2. Inside a version the API only grows, and a breaking change ships under a new prefix. The rule is written into Terms of Service section 4.1, which also sets 90 days of notice, on the changelog and by email, before an endpoint or a version is retired.

How much notice does RoxyAPI give before retiring an endpoint?

RoxyAPI gives at least 90 days of notice before retiring an endpoint or a version, announced on the public changelog and by email to active subscribers, and the endpoint keeps working for that whole period. The same notice applies on every plan. The only exception is a security or legal requirement that leaves no room for the full period, where notice is as long as the requirement allows.

Can I get alerted when an astrology API changes?

Yes, if the provider publishes a feed. RoxyAPI serves its changelog as an RSS feed at /changelog/rss.xml, which a build pipeline, a team channel or any feed reader can follow. For a check that does not depend on the provider, save the RoxyAPI OpenAPI document and diff it on a schedule with an OpenAPI diff tool.

Where is the RoxyAPI OpenAPI spec?

The combined RoxyAPI OpenAPI 3.1 document is public at https://roxyapi.com/api/v2/openapi.json and covers every endpoint across 18+ domains in one file, with no key needed to download it. It is the source the typed SDKs and the Remote MCP tools are generated from, and it publishes every error code on its info object as x-error-codes.

Should my code switch on the error message or the error code?

Switch on the code field. On RoxyAPI the error message is written for people and its wording can change, while code is a stable identifier that keeps its meaning, and doc_url links to the fix for that exact code. The HTTP status alone is too coarse, because several different problems share a 401 or a 429.

Conclusion

A stable contract is not a feeling about a vendor. It is a version, a written rule, a notice period, a public spec, stable error codes and a feed, all of which you can check, plus one diff you can keep running. Run the six astrology API versioning checks against every provider on your shortlist. The RoxyAPI Astrology API publishes each one, and you can call any endpoint live in the API reference before you commit.