API Versioning and Deprecation Policy

1. What this policy is for

If you integrate with Trooth, you need to know two things: what could break, and how much warning you get. This document answers both, exhaustively, so the question never has to be settled in a support thread.

2. How a version is named

A version is a date and a name: 2026-08-25.opal.

The date identifies the release. The name identifies the compatibility generation.

3. Selecting a version

Send the version in a request header:

Trooth-Version: 2026-08-25.opal

If you send no version header you receive the pinned default, never the newest. This is the important half of the policy. An unversioned integration that keeps working is the whole point; an unversioned integration that silently follows the newest release is worse than no versioning at all, because it breaks without anyone having chosen anything.

Every response echoes the version that served it, so you can always tell what you actually got.

4. What counts as breaking

Stated exhaustively. If a change is not on this list, it is not breaking.

Breaking

• Removing a field from a response.
• Renaming a field.
• Changing a field's type.
• Removing an enum value clients may already receive.
• Making an optional request field required.
• Changing the meaning of an existing value.
• Removing an endpoint.
• Tightening a rate limit.

Not breaking

• Adding a field to a response.
• Adding an endpoint.
• Adding a new enum value.
• Adding an optional request field.
• Relaxing a rate limit.
• Changing an error message while keeping its code.
• Reordering fields in a response.

5. What we need from your client

Two obligations, and they are what make the second list above a fair claim rather than a convenient one.

Tolerate fields you do not recognise. Do not fail on an unexpected key.

Tolerate enum values you have not seen. Handle an unknown value as unknown rather than as an error or a default.

The second matters more here than in most APIs. Evidence on the Trooth Network carries eight states: witnessed, verified, declared, inferred, unknown, unavailable, stale and conflicting. A ninth is entirely plausible, and a client that treats an unrecognised state as a failure would report a company badly because Trooth described it precisely.

6. Deprecation

Nothing is deprecated today. This is the rule, set before it is needed rather than after.

Ninety days is chosen because it is long enough to schedule work into a quarter and short enough that Trooth is not maintaining two behaviours indefinitely. It is a commitment, made once here rather than negotiated case by case.

7. Changes that move a published fact

Some changes are not breaking in the API sense and still matter more than any of them: a change to what a published fact means.

Examples: the evidence vocabulary gains, loses or redefines a state; the conditions under which a fact is rendered stale change; scoring composition changes in a way that moves published scores.

Each of those ships with a release note before it takes effect, stating what changed, what it means for a published profile, whether any score moved and by how much, and what to do if you disagree. That last one points at the dispute process, which is what makes the other three safe to publish.

8. Where to watch

Questions about an integration go to support@trooth.co.