API Versioning and Deprecation Policy
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.
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
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
| 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
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:
- It is marked
deprecated: truein/openapi.json. - Its responses carry a RFC 9745
Deprecationheader, naming the date the deprecation took effect. - Its responses carry a RFC 8594
Sunsetheader, 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 GMTNo 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
Every published endpoint answers with two RFC 8631
Link relations, so any response you are holding carries the way back to both
descriptions of the surface:
service-desc→/openapi.json, the machine-readable spec, whoseinfo.x-deprecation-policypoints back at this pageservice-doc→ the API reference
Questions
Write to 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.
Fume API Reference
Endpoints, parameters and response shapes of the public Fume API: the tokenized fund registry, the fund service provider catalog, and the site's submission endpoints.
Agent Access to Fume
How an AI agent reads fume.finance: markdown content negotiation, llms.txt, the sitemap, raw-markdown URLs, and what a 404 tells you.