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 whole number, the contract: 2 today. It moves only when something on the breaking list in section 4 changes. Everything on the non-breaking list ships under the same number, so a client that reads the fields it knows and tolerates the rest keeps working across additions.
3. Selecting a version
Choose a contract in the query or in a request header, not both:
GET /api/network/profile?q=acme.com&contract=2
Trooth-Contract: 2If you send both and they differ, the request is refused with 400, rather than one silently winning. A number this deployment does not serve is refused with 400 and a sentence saying which numbers it serves. If you send neither, you receive the current contract. Pin one if you want to be told, by a refusal, the day it changes.
Every response names the contract that served it, in the Trooth-Contract response header and in contractVersion, and names the contract you asked for in requestedContract, so you can always tell what you actually got.
An earlier text of this policy described a dated Trooth-Version header. It was never read, and it still is not: a response to a request that sends it carries a Warning header saying so.
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 recognize. 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 ten states on the wire: witnessed, verified, declared, inferred, unknown, not-applicable, restricted, stale, conflicting and unavailable. verified is a stored contract value and does not change; a reader is shown Public record for it, which is what it means: read from an authoritative public or registry source. An eleventh state is entirely plausible, and a client that treats an unrecognized state as a failure would report a company badly because Trooth described it precisely.
6. Deprecation
Contract 1 is deprecated and is withdrawn on March 1, 2027. It promised one answer per question, which was not true where two sources disagree. A request for contract 1 is served contract 1, named in contractVersion and the Trooth-Contract header, with the reason in deprecation and Deprecation and Sunset response headers naming the date. Contract 1 means each fact's value is the answer, which holds only where no two sources disagree, so a contract 1 response leaves out every fact two sources answered differently and names each in withheldContested; contract 2 publishes them with every account in conflicts. After March 1, 2027 a request for contract 1 is refused with the versions that are answered. This notice is announced here on September 26, 2026, 156 days before the withdrawal.
The older profile lookup, GET https://api.trooth.co/public/trust/{slug}, is deprecated and is withdrawn after April 30, 2027. The canonical read is GET https://trooth.co/api/network/profile?q={domain-or-slug}&contract=2. Until the withdrawal the older route answers as it does today, and every answer carries Deprecation (RFC 9745), Sunset (RFC 8594) and a Link header naming the migration recipe at /docs/trust-profile-api and the canonical lookup for the same identifier. After April 30, 2027 it answers 410 Gone with the same links. This notice is announced here on October 12, 2026, 200 days before the withdrawal.
The version 1 webhook signature, x-trooth-signature without a prefix on workspace endpoints and profile subscriptions, is withdrawn after April 30, 2027. It signs the body alone, with no timestamp, so a captured delivery keeps verifying. Until the withdrawal it is still sent, beside x-trooth-signature-v1-sunset naming the date; the receiver recipe at /docs/webhooks checks Standard Webhooks or version 2 and never version 1. This notice is announced here on October 12, 2026, 200 days before the withdrawal.
| Stage | Notice | Where you see it |
|---|---|---|
| Announced | At least 90 days before removal | This policy, the changelog, and a release note if it changes what a published fact means |
| Warned | From announcement until removal | Deprecation and Sunset response headers, and deprecation in the body |
| 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 behaviors 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 facts Trooth reads for a published profile changes, so that facts are added to or removed from it.
Each of those ships with a release note before it takes effect, stating what changed, what it means for a published profile, which published facts changed and how, 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 September 4, 2026. Two passages in the section on material changes referred to a composite figure. Trooth does not compute or publish a composite figure; a Trust Profile reports what was witnessed and when. No right or obligation was narrowed, and the correction is recorded under our publication and correction policy.
Revision note. Revised September 20, 2026. This section named eight evidence states and the API answers with ten; not-applicable and restricted were missing from the list, on the page that tells a client how to treat a state it does not recognize. All ten are named now, and the section says that verified is a wire value that does not change while what a reader is shown for it is Public record. No right or obligation was narrowed, and the correction is recorded under our publication and correction policy.
Revision note. Revised September 23, 2026. Section 7 described a published count of checks, a measure this product no longer uses. It now describes a change to the set of facts Trooth reads for a profile, and the release note that goes with such a change says which published facts changed and how. An earlier revision note above described a Trust Profile by a count of checks, a measure this product no longer uses; it now says what a profile reports. Spelling is now American throughout, as Trooth is a Florida limited liability company, and dates are written month first. No right or obligation was narrowed, and the correction is recorded under our publication and correction policy.
Revision note. Revised September 26, 2026. Sections 2, 3 and 6 described a dated Trooth-Version header that was never read, promised an echo of it, and said nothing was deprecated while contract 1 carried a withdrawal notice. They now describe the mechanism that runs: a whole-number contract chosen in the query or the Trooth-Contract header, a refusal when the two differ, the served and requested contract named on every response, and contract 1's withdrawal on March 1, 2027 with Deprecation and Sunset headers. No right was narrowed, and the correction is recorded under our publication and correction policy.
Revision note. Revised September 28, 2026. Section 6 said a request for contract 1 is served contract 2 with a warning. A warning does not keep a pinned meaning, so a request for contract 1 is now served contract 1 itself, with every fact two sources disagree about left out and named rather than resolved. The withdrawal date is unchanged. No right was narrowed, and the correction is recorded under our publication and correction policy.
Revision note. Revised October 4, 2026. Wording only: the word this document used for a single number summing a company up, in its clauses and in the earlier revision notes above, is now "composite figure" or "rating", the words used everywhere else Trooth publishes. The meaning is unchanged: no right or obligation was added, narrowed or removed, and the correction is recorded under our publication and correction policy.
Revision note. Revised October 12, 2026. Section 6 announces two withdrawals, each after April 30, 2027 and each 200 days after this notice: the older profile lookup on api.trooth.co, which now names its successor and its sunset in standard headers, and the version 1 webhook signature, which carries no timestamp. Both stay in service until that date. No right or obligation was narrowed, and the change is recorded under our publication and correction policy.