# 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-enum` in [openapi.json](https://api.ratesspot.com/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](https://api.ratesspot.com/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: true` in openapi.json, and the [API reference](https://api.ratesspot.com/docs) says what to use instead;
- every response from it carries a `Deprecation` header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) with the date it was deprecated, and a `Link` header (`rel="deprecation"`) pointing to its [changelog](https://www.ratesspot.com/docs/changelog.md) entry;
- it's announced in the [changelog](https://www.ratesspot.com/docs/changelog.md).

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:

1. It's announced in the changelog, with what changes and how to move.
2. 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.
3. Responses from affected /v1 operations carry a `Sunset` header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) 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.
4. 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.
