--- title: "RateAPI Versioning & Deprecation Policy" description: "How RateAPI versions its REST API, what counts as a breaking change, and the Deprecation and Sunset headers that warn you at least 180 days before anything is removed." canonical: "https://rateapi.dev/deprecation-policy" last-updated: "2026-08-21" source: "https://rateapi.dev/llms.txt" --- # Versioning & Deprecation What can change under an integration built on RateAPI, and how much warning it gets. The short version: additive changes ship whenever, removals take at least 180 days and announce themselves in response headers first. ## How RateAPI is versioned The major version lives in the URL path. Every current endpoint is served under `https://api.rateapi.dev/v1/…`, and a pinned client that never changes its URLs never gets a breaking change delivered to it. There is no version header to set and no date-based pinning to keep track of — the path is the contract. A new major version would be published alongside `/v1`, not in place of it. `/v1` would then enter the sunset process below rather than being switched off when its successor shipped. ## What counts as a breaking change These are breaking, and only happen across a major version or through the sunset process: Removing an endpoint, a response field, or an accepted parameter. Changing the type or meaning of an existing response field, or narrowing what an existing parameter accepts. Making a previously optional request field required, or adding a new authentication requirement to an endpoint that had none. Changing the default sort order or the default filter set of a list endpoint, where a client reading the first element would start getting a different answer. These are **not** breaking and ship continuously: adding an endpoint, adding a response field, adding an optional parameter, adding a new enum member to a field already documented as extensible, relaxing a validation rule, and performance work. Write your client so an unrecognised field or enum member is ignored rather than fatal. Rate *values* change constantly — that is the product, not a version event. Every rate carries its own observed timestamp so freshness is verifiable per record. ## The sunset window Once something is marked deprecated, it keeps working for a minimum of **180 days** before removal. During that window nothing about its behaviour changes; the only difference is that its responses start carrying the headers below. Deprecated surfaces are also marked `"deprecated": true` in the [OpenAPI document](https://api.rateapi.dev/openapi.json), so a generated client can flag it at build time. If a change is forced on us from outside — a data source withdrawing permission, or a legal obligation — we may have to move faster than 180 days. In that case we will email every key holder using the affected surface rather than relying on headers alone. It has not happened yet. ## The headers Deprecation is signalled per response, following RFC 8594 and the HTTP `Deprecation` header draft, so a client discovers it without anyone reading a changelog: DeprecationAn HTTP date marking when the surface became deprecated. Present on every response from a deprecated endpoint. SunsetAn HTTP date, at least 180 days later, after which the surface may stop responding. Link; rel="deprecation"A link to this page, plus a `rel="successor-version"` link to whatever replaces it when there is a replacement. A deprecated endpoint therefore answers like this, and keeps answering normally until the sunset date passes: `Deprecation: Wed, 01 Oct 2026 00:00:00 GMT Sunset: Mon, 30 Mar 2027 00:00:00 GMT Link: ; rel="deprecation"` ## Currently deprecated Nothing. No RateAPI endpoint or field is currently under a sunset notice. When that changes, the affected surfaces will be listed here by name and sunset date, and the headers above will appear on their responses at the same time. One naming note that is not a deprecation: responses carry both the RFC `RateLimit-*` headers and the older `X-RateLimit-*` pair. The `X-` forms are legacy, and we intend to keep sending them indefinitely — they are not scheduled for removal. Prefer the unprefixed ones in new code. See the [developer portal](https://rateapi.dev/developers#rate-limits) for what each one means. ## Questions If you are about to build something and want to know whether a particular field is safe to depend on, ask before you build it: [support@rateapi.dev](mailto:support@rateapi.dev). Other routes are on the [contact page](https://rateapi.dev/contact). ⚡RateAPI Daily-verified lending rates from 3,700+ US credit unions, plus deposit APY benchmarks for savings, CDs, share certificates, and money markets. [Sign In →](https://app.rateapi.dev) ### Products - [Current Rates →](https://rateapi.dev/current-mortgage-rates) - [Current Auto Loan Rates](https://rateapi.dev/current-auto-loan-rates) - [Current CD Rates](https://rateapi.dev/current-cd-rates) - [Current HELOC Rates](https://rateapi.dev/current-heloc-rates) - [Current Personal Loan Rates](https://rateapi.dev/current-personal-loan-rates) - [Credit Union Rate Index](https://rateapi.dev/credit-union-rate-index) - [For Credit Unions](https://rateapi.dev/for-credit-unions) - [Mortgage Rates](https://rateapi.dev/mortgage-rates) - [Auto Loan Rates](https://rateapi.dev/auto-loan-rates) - [RV Loan Rates](https://rateapi.dev/rv-loan-rates) - [Boat & Marine Rates](https://rateapi.dev/boat-loan-rates) - [Motorcycle Rates](https://rateapi.dev/motorcycle-loan-rates) - [HELOC Rates](https://rateapi.dev/heloc-rates) - [Personal Loan Rates](https://rateapi.dev/personal-loan-rates) - [Credit Card Rates](https://rateapi.dev/credit-card-rates) - [Credit Union Directory →](https://rateapi.dev/credit-unions) ### Resources - [Should I Refinance?](https://rateapi.dev/should-i-refinance) - [When to Lock Your Rate](https://rateapi.dev/when-to-lock-your-rate) - [Auto vs Personal Loan](https://rateapi.dev/auto-loan-vs-personal-loan) - [Pricing →](https://rateapi.dev/pricing) - [Use Cases](https://rateapi.dev/use-cases) - [AI Integration](https://rateapi.dev/ai) - [AI Guides →](https://rateapi.dev/ai-guides) - [Mortgage Benchmark](https://rateapi.dev/mortgage-rate-benchmark) - [Auto Loan Benchmark](https://rateapi.dev/auto-loan-rate-benchmark) - [Data Methodology](https://rateapi.dev/methodology) - [Transparency](https://rateapi.dev/transparency) - [Datasets →](https://rateapi.dev/credit-union-rate-dataset) ### Company - [About](https://rateapi.dev/about) - [What is RateAPI?](https://rateapi.dev/what-is-rateapi) - [Mortgage Rate API Guide](https://rateapi.dev/what-is-mortgage-rate-api) - [Auto Loan Rate API Guide](https://rateapi.dev/what-is-auto-loan-rate-api) - [FAQ](https://rateapi.dev/faq) - [Independence](https://rateapi.dev/independence) - [Corrections](https://rateapi.dev/corrections) - [Contact](https://rateapi.dev/contact) - Are you a real estate agent or lender? ### Developers - [Developer Portal →](https://rateapi.dev/developers) - [API Reference](https://api.rateapi.dev/) - [OpenAPI Spec](https://api.rateapi.dev/openapi.json) - [Webhooks](https://api.rateapi.dev/webhooks) - [MCP Server](https://rateapi.dev/mcp) - [Embed Widgets](https://rateapi.dev/widget-docs) - [Versioning & Deprecation](https://rateapi.dev/deprecation-policy) - [GitHub](https://github.com/rate-api) © 2026 RateAPI | [llms.txt](https://rateapi.dev/llms.txt) --- Source: https://rateapi.dev/deprecation-policy Rate data API: https://api.rateapi.dev · OpenAPI: https://api.rateapi.dev/openapi.json · MCP: https://mcp.rateapi.dev/mcp