# API Deprecation Policy: Versioning, Notice, Headers | FXMacroData

> How FXMacroData versions its API: what counts as a breaking change, how deprecations are signalled with the Deprecation and Link headers and the OpenAPI deprecated flag, the six-month minimum notice before removal, and the current deprecations.

Source: https://fxmacrodata.com/documentation/deprecation-policy
Documentation index: https://fxmacrodata.com/documentation/llms.txt
API base URL: https://api.fxmacrodata.com

# API deprecation policy

The API is versioned once, at `/v1`. Inside it, additions arrive without notice and removals never do: a path or field that is going away is marked in the schema, announced in the changelog, and keeps answering, with a `Deprecation` header pointing at its replacement, for at least six months before it is removed.

## One version, extended in place

Every production route lives under `https://api.fxmacrodata.com/v1/`. New capability is added as new endpoints, new optional parameters, new selector values and new response fields on the same version, never as a parallel copy of an existing route. The [production OpenAPI schema](https://api.fxmacrodata.com/openapi.json) is the contract; the [API reference](https://fxmacrodata.com/documentation/reference) is generated from it.

## Changes you should expect without notice

Clients must tolerate these. They appear in the [changelog](https://fxmacrodata.com/documentation/changelog) when they matter, but they are not deprecations.

- New fields on any response object, including inside `data[]` rows, `data_quality` and `provenance`. Parse by key, never by position or count.

- New endpoints and new optional query parameters.

- New values for open string fields such as `source`, `publication_time_basis` or `returned_reason`, and new entries in enumerated selector lists exposed through `supported_options`.

- New currencies, indicators, commodities and series variants in the data catalogue.

- Key order within JSON objects, whitespace, and the order of equal-ranked items.

- Fields that are omitted when they do not apply. A field documented as optional may be absent on a row and present on the next.

- Longer histories, revised values and corrected timestamps as publishers revise their data (see data corrections ).

## Changes that go through deprecation

Anything that would make a correct client stop working.

- Removing or renaming an endpoint, a query parameter, a response field or a selector value.

- Changing the type, unit or meaning of an existing field, or the shape of an existing object.

- Tightening validation so that a request that is valid today would be rejected.

- Changing how a route authenticates or which plans may call it.

- Changing a default, such as the default `limit` or the default `revisions` view.

## How a deprecation is signalled

Each deprecation is marked in four places at once, so a client can detect it in the schema, in the response, in the changelog and in the documentation.

| Where | Signal |
| --- | --- |
| OpenAPI schema | The operation or parameter carries `deprecated: true` and its description names the replacement. |
| Every response | A `Deprecation: true` header, plus a `Link` header: `rel="successor-version"` pointing at the replacement route, or `rel="deprecation"` pointing at the documentation that explains the change. |
| Changelog | A dated entry on the [changelog](https://fxmacrodata.com/documentation/changelog), also published in its [Atom feed](https://fxmacrodata.com/documentation/changelog.xml), stating what is deprecated, what replaces it and the earliest removal date. |
| Documentation | The affected page describes the replacement; this page lists the deprecation until it is removed. |

Log the `Deprecation` header in your client. A single alert on its first appearance gives you the whole notice period to migrate.

## Notice period

- A deprecated endpoint, parameter or field keeps working, with the same data, for **at least six months** from the date of its changelog entry.

- The removal date is published in the changelog in advance. The route is not removed earlier than that date.

- Deprecations of authentication transports are handled the same way. Where a transport stays accepted indefinitely, its entry below says so.

- Enterprise customers with a signed agreement may have a longer period written into it; this page states the minimum that applies to everyone.

## Current deprecations

Everything deprecated today, with its replacement. Neither has a removal date set.

| Deprecated | Use instead | Status |
| --- | --- | --- |
| GET /v1/fx/fixing-timeline/{base}/{quote} | GET /v1/fx/intraday-reference-rates/{base}/{quote} | Still served. Responses carry `Deprecation: true` and a `Link` with `rel="successor-version"`. No removal date set; at least six months' notice will be given in the changelog. |
| ?api_key= on REST routes | `X-API-Key` header or `Authorization: Bearer` | Still accepted. Responses to query-string authentication carry `Deprecation: true` and a `Link` to the [authentication documentation](https://fxmacrodata.com/documentation/rate-limits#authentication). No removal date set. The query parameter remains the documented transport for SSE, WebSocket and MCP, where a browser or host cannot set headers. |

## Data corrections are not deprecations

The contract is the shape of the response; the values inside it follow the publishers.

- Publisher revisions change `val` for a period and add an entry to `revisions[]`. Use `revisions=first` or `as_of` when your work depends on what was known at the time; see [point-in-time backtesting](https://fxmacrodata.com/documentation/point-in-time-backtesting).

- Corrections FXMacroData makes to its own timestamps or stored values are recorded on the [issue log](https://fxmacrodata.com/documentation/issue-log) with their date and scope.

- When a series is re-pointed at a different official source, the change is a changelog entry and the rows the old source wrote are replaced in the same release, so the slug keeps meaning one thing.

Questions about a specific change: [info@fxmacrodata.com](mailto:info@fxmacrodata.com).