API policy

Nothing switched off without notice.

Versioning and deprecation policy, 18 October 2026

Code that worked yesterday should work today. Nothing in the econfeed API is removed or changed in a way that breaks your code without at least 12 months' notice. Every change is announced in the changelog first.

This covers the REST API under /v1, the WebSocket and server-sent event stream, webhook payloads and signatures, the API specification, and our Python, JavaScript and R clients and MCP server. It applies from the day the API opens to customers, early-access keys included.

Versions

The major version is in the path: /v1. Inside /v1 we only make compatible changes.
An incompatible change arrives as a new endpoint or parameter next to the old one, or as /v2. The old one keeps working until its sunset date.
/v1 keeps running for at least 12 months after /v2 is generally available.

What counts as breaking

Breaking and compatible changes
Compatible: can happen any time	Breaking: needs 12 months' notice
New endpoints, optional parameters, response fields and headers	Removing or renaming an endpoint, parameter, field, event type or error code
New entries in lists that grow, such as release states or event types you opt in to. Your code should accept values it does not know yet	Changing a field's type, unit, meaning or format
New series and sources, agency revisions and corrections: these are data, not API changes	Changing a default, such as the page size or which events a webhook receives
Field order, whitespace and the contents of cursors (treat cursors as opaque)	A request that worked starts failing: a new required parameter or permission, stricter validation
Fixing behaviour that contradicted the documentation (announced if you might rely on it)	Changing how webhooks are signed, retried or deduplicated; renaming or reusing a series or source id

Notice periods

Minimum notice by kind of change
Change	Minimum notice
Breaking change to `/v1`	12 months from announcement to sunset
We stop collecting a public source or series by our own choice	6 months
An agency stops, replaces or changes a release	The agency decides; we announce it within 2 business days of learning of it
A licence is withdrawn, a legal order, a security fix	As much as the cause allows, announced the same day

A sunset date can move later, never earlier.

How you hear about it

Changelog. Every deprecation is an entry in the changelog with the date, what replaces it and the sunset date. Follow it by RSS or JSON Feed.
Response headers. Every call that uses a deprecated endpoint or parameter answers with Deprecation (RFC 9745), Sunset (RFC 8594), Link to this page with rel="deprecation", and Econfeed-Deprecated naming what to use instead.
API specification. The item is marked deprecated in the OpenAPI document, with its dates.
Our clients. The Python client raises a warning you see by default, the JavaScript client logs one, and both let you handle it yourself. The MCP server passes it on in tool results.
Email. Once account email is in place, owners of keys that used the item in the last 90 days get an email when it is announced, and again 90 and 30 days before the sunset.

Sunset process

We announce the deprecation in the changelog, the headers and the specification, with a sunset at least 12 months away.
Until the sunset it works exactly as before. We watch which keys still use it.
Reminders go out 90 and 30 days before the sunset.
On or after the sunset date it is removed. Calls then answer 410 Gone with an error that names the replacement and links here, for at least 6 months. Never a silent 404 or an empty answer.
The removal gets its own changelog entry.

When an agency changes or stops a release

Agencies stop series, start new ones and change their methods. We cannot give more notice than the agency does, but we can make sure you hear it from us first and lose nothing.

What econfeed does when an agency changes a release
The agency	econfeed
Stops a series or a release	The series keeps its id, its full history and every version; no new values arrive. A changelog entry (Retired) within 2 business days, and the release calendar stops listing it.
Replaces a series with a new method or classification	The new series gets a new id when its numbers are not comparable, the old one is retired as above, and the changelog names both. A rebase of the same series is a new version, not a new id.
Revises or withdraws figures	A new version marked as an agency revision; the old version stays in the history. If we served a wrong figure ourselves, it goes in the corrections log.
Moves a release date	The calendar's change log and calendar alerts show it. This is not a deprecation.
Changes its file format or web address	Our job to adapt. Nothing for you to do.
Changes its licence so we may no longer pass the data on	The licence register and the changelog say so. History is withdrawn only if the licence requires it.

Ids are never reused. A series id that has meant one thing will never mean another.