Docs
Versioning and deprecation
How we version the API, ship changes, and give notice before breaking changes or removals.
API and SDK versions
The REST API version is in the path: /v1. There is no version header. MCP at /mcp negotiates its own protocol version.
SDK package versions are separate from the API version.
Compatible changes
Within /v1, we can add endpoints and MCP tools, data sets, countries or coverage, and optional inputs that keep existing behaviour. These changes can ship at any time without notice.
We can also add optional or nullable response fields and new values in a response enum without notice. We list these changes in the changelog.
Clients should ignore fields they do not know and accept enum values they do not know. Our SDKs already do this.
Breaking changes
Removing or renaming a field is a breaking change. So is changing its type, meaning, unit, precision, or whether it is required.
Changing a route or method, authentication, authorization, quota, or default behaviour is also a breaking change.
We ship a breaking change as a new path or operation, or a new major version. We do not silently change an existing one.
Notice before changes
If a breaking change or removal affects an endpoint or field your account has called in the last 90 days, we tell you at least 3 months before it takes effect. We notify you by email and on the changelog.
Endpoints or fields no account has called in the last 90 days may be removed with shorter notice. We announce these removals on the changelog.
Where we announce changes
We announce changes in the changelog and its RSS feed.
Currently deprecated
The event_type field on economic events is a deprecated alias of type. Use type.
No removal date is set. When we set one, it will follow the notice policy above.