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.
| Rule | What it means for you |
|---|---|
| Non-breaking changes ship continuously | The version does not move. You do nothing |
| A new date within the same name | Guaranteed backward compatible with every earlier date under that name |
| A new name | The only signal that something breaks |
3. Selecting a version
Send the version in a request header:
Trooth-Version: 2026-08-25.opalIf 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.
| Stage | Notice | Where you see it |
|---|---|---|
| Announced | At least 90 days before removal | The changelog, and a release note if it changes what a published fact means |
| Warned | From announcement until removal | A Trooth-Deprecation response header naming the removal date |
| Removed | Never before the announced date | A changelog entry on the day |
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; the set of checks that make up a published result changes in a way that moves the published count of passing checks.
Each of those ships with a release note before it takes effect, stating what changed, what it means for a published profile, whether any published count of passing checks 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
| What | Where |
|---|---|
| Every customer-visible change | trooth.co/changelog |
| Deprecation warnings | The Trooth-Deprecation response header |
| The version that served a response | The response's own version header |
Questions about an integration go to support@trooth.co.
Revision note. Revised 4 September 2026. Two passages in the section on material changes referred to scoring. Trooth does not compute or publish a score; a Trust Profile reports what was witnessed and how many checks passed out of how many ran. No right or obligation was narrowed, and the correction is recorded under our publication and correction policy.