---
title: "API Versioning and Deprecation Policy"
description: "What Fume guarantees about the stability of its public API: what is versioned, what counts as a breaking change, how much notice a retirement gets, and the headers that announce one."
canonical: "https://www.fume.finance/docs/developers/versioning"
---

# API Versioning and Deprecation Policy (/docs/developers/versioning)



This is the stability contract for the public Fume API: **nothing under
`/api/v1/` breaks under you.** A breaking change gets a new prefix. A retirement
inside a version gets 90 days of notice, announced in three places a client can
read without a human.

## What is versioned [#what-is-versioned]

Every endpoint is served under `/api/v1/`. The major version is in the path, and
it is the only version number that exists — there is no minor version to pin, no
date header to send, and no `Accept` parameter to negotiate.

The unprefixed form (`/api/registry/funds`) is a permanent alias for the current
major version. It returns the same response, so an integration written against
it keeps working. New integrations should pin the versioned path anyway, so that
a future `/api/v2/` cannot change the meaning of a URL you already call.

Every response — including every error response — states the contract it was
served under in an `API-Version: 1` header. A client holding a response but not
the URL that produced it can still tell.

## What counts as a breaking change [#what-counts-as-a-breaking-change]

| Change                                        | Breaking? | What we do                    |
| --------------------------------------------- | --------- | ----------------------------- |
| Removing an endpoint, field, or response code | **Yes**   | New major version, new prefix |
| Renaming a field, or changing its type        | **Yes**   | New major version, new prefix |
| Narrowing an accepted parameter value         | **Yes**   | New major version, new prefix |
| Adding an endpoint                            | No        | Ships without a version bump  |
| Adding a field to a response                  | No        | Ships without a version bump  |
| Adding an **optional** parameter              | No        | Ships without a version bump  |
| Adding a new value to an existing enum        | No        | Ships without a version bump  |

Because additive changes ship without a bump, **parse responses tolerantly**:
ignore fields you do not recognise rather than rejecting the payload, and treat
an unknown enum value as a value you do not handle rather than as an error.

## When something is retired [#when-something-is-retired]

Introducing `/api/v2/` does not retire `/api/v1/`: a new major version arrives
beside the old one rather than replacing it. Retiring anything — a whole version,
or a single endpoint inside one — is announced **at least 90 days before it
stops answering**, in three machine-readable places:

1. It is marked `deprecated: true` in [`/openapi.json`](https://www.fume.finance/openapi.json).
2. Its responses carry a [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)
   `Deprecation` header, naming the date the deprecation took effect.
3. Its responses carry a [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)
   `Sunset` header, naming the date it will stop answering.

Both headers carry HTTP dates, so a client can compare them against the clock
and act without anyone reading this page:

```
Deprecation: Wed, 11 Feb 2026 00:00:00 GMT
Sunset: Tue, 12 May 2026 00:00:00 GMT
```

**No endpoint is deprecated today**, so no live response currently carries
either header. Their absence is the signal that nothing is scheduled for
removal, so a monitor should alert on the headers *appearing*.

## How to find this policy from a response [#how-to-find-this-policy-from-a-response]

Every published endpoint answers with two [RFC 8631](https://www.rfc-editor.org/rfc/rfc8631)
`Link` relations, so any response you are holding carries the way back to both
descriptions of the surface:

* `service-desc` → [`/openapi.json`](https://www.fume.finance/openapi.json), the
  machine-readable spec, whose `info.x-deprecation-policy` points back at this page
* `service-doc` → the [API reference](/docs/developers/api-reference)

## Questions [#questions]

Write to [info@fume.finance](mailto:info@fume.finance). If you have an
integration against the public API and want to hear about a deprecation
directly rather than by polling headers, say so and we will mail you.