Operations

Versioning and deprecations

What may change within v1, how we announce changes and how long old paths keep working.

What may change in v1

The major version is part of the path, currently /v1 for the REST API and the MCP server. Within v1 things are only added, nothing is removed:

Change	Allowed in v1	What your code has to do
New dataset, endpoint or MCP tool	yes	nothing
New field in a response	yes	ignore unknown fields
New optional parameter	yes	nothing
New error code	yes	treat unknown codes by their HTTP status
New value in a list of allowed values (for example a component)	yes	do not treat unknown values as errors
Rename or remove a field, or change its meaning	no, only in v2	nothing while you use v1
New required parameter	no, only in v2	nothing
Rewording error texts (nachricht, detail)	yes	rely on code, not on the wording

Values themselves change when the legislator changes them. That is not a change of the interface but its purpose: every new step is listed in the changelog.

Version numbers

Besides the major version in the path there is a product version following Semantic Versioning, currently 1.3.0. It appears in three places and is the same everywhere: in the entry point https://api.quellenkontor.dev/v1/ as produkt_version, in info.version of the OpenAPI document and in serverInfo.version of the MCP server.

The minor number goes up with new datasets, fields, parameters, endpoints and tools.
The patch number goes up with fixes that add nothing new.
The major number only goes up together with a new path (/v2).

Deprecation with Deprecation and Sunset

An endpoint, parameter or tool is only removed with a new major version and in three steps:

Announcement: an entry in the changelog and an email to all accounts, at least twelve months before shutdown.
Marking: responses of the affected path carry the header Deprecation (RFC 9745) with the announcement date, Sunset (RFC 8594) with the shutdown date and a Link with rel="deprecation" to the migration guide.
Parallel operation: old and new version run side by side for at least twelve months. Only after the sunset date does the old path answer 410 Gone.

What a deprecated response would look like

HTTP/2 200
Deprecation: @1790812800
Sunset: Wed, 01 Mar 2028 00:00:00 GMT
Link: <https://quellenkontor.dev/en/docs/versioning#abkuendigung>; rel="deprecation"

Nothing is deprecated right now. Check these headers in your monitoring and you will notice on your own.

MCP protocol versions

The MCP server speaks the protocol versions 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 and answers in the version the client asks for in initialize. New protocol versions are added; older ones stay as long as common clients use them. Differences between versions are described in the MCP server docs, for example batches only up to 2025-03-26.

SDK and CLI

The packages @quellenkontor/sdk, @quellenkontor/cli and quellenkontor have their own version numbers following Semantic Versioning. A package only gets a new major version when its methods change. New datasets arrive in a new minor version; older packages can query new datasets with a raw request.

Something missing or unclear? Write to us and we will extend the docs.