SonarSend API Getting started Versioning & compatibility

Versioning & compatibility

The API is at v1. Every tenant-scoped path is /t/{tenant_slug}/api/…; there is no version segment and no version header to send.

That is deliberate. A version in the URL earns its place when you need to serve two incompatible versions at once — and the promise below is designed so that day arrives rarely, if ever. When it does, v2 will appear as a new path prefix served alongside this one, not as a change to it. Nothing you have built will start behaving differently because a new version exists.

What may change without warning#

These are additive, and your integration must tolerate them:

New fields in a response. Objects gain fields as the product grows.
New endpoints, and new resources.
New optional request parameters, and new values in a response enum where the field describes an open-ended state.
New error codes, for conditions that previously surfaced as a more general code.

The practical requirement is one line of discipline: ignore fields you do not recognise. Do not deserialise into a strict type that rejects unknown keys, and do not assert on the exact set of keys in a response. Almost every “the API broke” report against an API like this one traces back to a strict parser.

What will not change inside v1#

A field will not be removed, renamed, or change type.
A field’s meaning will not change.
An endpoint will not be removed, and its path will not move.
Required request parameters will not be added, and validation will not be tightened on input that is accepted today.
The shape of a list response will not change.
An error code will not be reused for a different condition.

If we need to do any of these, it ships as v2 on its own prefix, this page says so, and the current surface keeps working.

Deprecation#

An endpoint being replaced keeps working. It is:

announced in the changelog,
marked deprecated in this reference,
served with an RFC 9745 Deprecation header (a @<unix-timestamp> marking when it was deprecated) and a Link: <…>; rel="successor-version" pointing at its replacement, and
left in place until its traffic is genuinely gone.

There are none today. Nothing in this reference is deprecated.

The version number#

GET /api/openapi.json reports the current version in info.version, and GET /api/discover reports it as api.version. It follows semver over the wire contract:


MINOR	Something was added. Safe under the rules above.
PATCH	Behaviour was corrected to match what this reference already said.
MAJOR	A break — which, per the contract, means a new prefix rather than a change here.

You do not need to pin it. It exists so you can tell what you are looking at, and so the changelog has something to hang entries on.

What this promise is worth#

It is a commitment about the surface, not a guarantee about the future of every product decision behind it. If something genuinely has to break — a security fix, or a behaviour that was wrong rather than merely awkward — we will say so plainly in the changelog rather than quietly reinterpret the rules above. What you can rely on is that it will not happen silently.