API versions and changes
What you can rely on when you build on the RatesSpot API, and how you'll hear about anything that changes.
One version that only grows
There is one version of the API: /v1. It only ever gains things:
- new endpoints, new optional request fields, new fields in responses;
- new values in lists that are documented as growing, such as webhook event types (marked
x-extensible-enumin openapi.json).
It never loses or changes them. Nothing is removed, renamed or made required, no field changes type, and no endpoint answers differently to a request that worked before. Every change to RatesSpot is checked against the previous openapi.json before it ships, and a change that would break a client isn't released.
There are no dated versions or version headers to pin. Write your client to:
- ignore fields it doesn't know, in responses and in webhook payloads;
- ignore event types and enum values it doesn't know, rather than failing on them;
- not depend on the order of fields or of keys in objects.
That's all it takes for your integration to keep working through every change to /v1.
Deprecation
Sometimes there's a better way to do something, and the old one is deprecated. A deprecated operation keeps working, unchanged, for as long as /v1 exists. You'll know because:
- it's marked
deprecated: truein openapi.json, and the API reference says what to use instead; - every response from it carries a
Deprecationheader (RFC 9745) with the date it was deprecated, and aLinkheader (rel="deprecation") pointing to its changelog entry; - it's announced in the changelog.
Look for the Deprecation header in your logs, or have your HTTP client warn you when it sees one.
Removal, and /v2
Deprecated operations are removed only in a new major version, /v2. There's no schedule for one: it happens when enough has been deprecated to be worth it, and never for a single change. When it does:
- It's announced in the changelog, with what changes and how to move.
- Everyone whose API keys or apps called something being removed in the last 30 days is emailed (the business's owners, and the developer of each app). RatesSpot records which keys and apps call deprecated operations for this.
- Responses from affected /v1 operations carry a
Sunsetheader (RFC 8594) with the date /v1 stops working. That date is at least 12 months after /v2 is released, and at least 6 months after the emails. - Until then /v1 keeps working and gets fixes, including security fixes, but no new features.
Security
If a security problem can only be fixed by changing how /v1 behaves, it's fixed, and the change is explained in the changelog the same day. This is the one exception, and it's handled by hand rather than by a version number.
Where else this applies
- Webhooks follow the same rules: new event types and new fields arrive without notice; existing ones don't change.
- The SDK (
@ratesspot/sdk) and the MCP server (@ratesspot/mcp) use semantic versioning. New API features come in minor versions; a major version only when /v2 does, or if their own interface has to change. - Not covered: the dashboard's own routes (staff sign-in, platform administration) are documented for completeness and follow the same rules, but they're for RatesSpot's dashboard, not for integrations.