Versioning

The External API uses URL-path versioning. The current version is v1:

/api/tender/supplier/v1/companies/{companyId}/speci-finder/results

The path is /api/{platform}/{audience}/{version}/.... platform is the E1 platform serving the endpoint — every endpoint runs on tender today; audience is who the endpoint is for (supplier, builder). The version applies per platform and audience, so a v2 on one leaves the others untouched.

When a future version is released, the new version will live at a new path (e.g. /api/tender/supplier/v2/...) and v1 will continue to serve existing traffic for the deprecation window described below.

What counts as a breaking change

The following changes are breaking and will only be made in a new major version:

• Removing a field from a response.
• Changing the type of an existing field (e.g. string to number).
• Changing the semantics of an existing field.
• Removing an endpoint, or moving one so that its old path stops working. (Giving an endpoint a new path while keeping the old one working is not breaking — see Superseded paths.)
• Adding a new required request parameter.
• Tightening validation on an existing parameter in a way that rejects previously-accepted inputs.
• Changing the error code for an existing failure mode.

The following changes are non-breaking and may be made in the current major version without notice:

• Adding a new field to a response.
• Adding a new optional request parameter.
• Adding a new endpoint.
• Adding a new error code for a new failure mode.
• Relaxing validation on an existing parameter.
• Bug fixes where the existing behaviour was clearly unintended.

Your integration should therefore tolerate unknown response fields and not rely on a fixed set of error codes — new ones can appear at any time.

Superseded paths

An endpoint is sometimes given a better path without its behaviour changing at all — for example when the product namespace was introduced and /api/supplier/v1/companies/{companyId}/speci-finder/results became /api/tender/supplier/v1/companies/{companyId}/speci-finder/results.

This is not a new version, and it is not the deprecation process below. The old path keeps working indefinitely, serving byte-identical responses, and is not scheduled for removal. It is marked deprecated in the OpenAPI spec and its responses carry:

Header	Meaning
Deprecation	When the path was superseded, as a RFC 9745 date (@ + seconds since the Unix epoch).
Link	The replacement path, with rel="successor-version".

No Sunset header is sent, because no removal is planned. You should move to the new path when convenient, but nothing will break if you don’t.

Deprecation process

When a v1 endpoint is scheduled for removal:

1. E1 announces the deprecation in the Changelog and notifies integrating partners via the support channel.
2. A minimum 90-day notice period runs before removal.
3. During the notice period v1 continues to work unchanged; a v2 (or replacement) is available for integrators to migrate to.
4. At the end of the notice period the deprecated endpoint is removed and will return 404 Not Found.

Checking the current version

The version is part of the URL path — there is no separate version header. Each response is implicitly the current shape of the version you requested.

If you’re using code generated from the OpenAPI spec, regenerate on a regular cadence to pick up non-breaking additions.