The Trooth application programming interface (API) answers questions about software and AI companies from what has been published about them. Every public endpoint is a read over an encrypted connection, answers in machine-readable JavaScript Object Notation (JSON), and needs no key and no account.

Each answer carries its own limits: where a fact came from, when Trooth last read it, and what Trooth did not read. No response contains a score, a rating or a rank for a company, and the published schema refuses one.

What you can build

• A vendor check inside your own toolResolve a domain to its Trust Profile and show what Trooth witnessed, what the company declared and what is unknown, each labeled as which.
• Search over the NetworkA search box or a typeahead over the same published companies the public directory lists, paged with a cursor.
• An agent that cites its sourcesConnect an assistant to the Model Context Protocol server and let it read a record, with its sources and dates, instead of guessing.
• An alert when a posture changesFollow a published profile and receive a signed event when what Trooth witnessed about it changes.

What is not offered

There is no write endpoint, no test environment, no software development kit (SDK) and no credentialed public API. Each of those is stated again where it matters below, with what to do instead, because an integration planned around something that does not exist fails late and expensively.

This list is deliberately short: if it is here, it works now. Anything not listed is not live, and Trooth does not advertise endpoints it has not shipped.

• Public Trust Profile JSONWitnessed state and the date it was last read, for any listed company.
• Embeddable witnessed badgeA company's live record on its own site in one line.
• Webhooks for driftPosture changes push to your tools.
• OpenAPI 3.1 contractServed at /openapi.json, generated from the routes and checked on every build.
• Trooth CLInpx trooth check <domain> reads a public record from the terminal, and trooth lint reads what your own repository declares, locally. The package is trooth on npm. No account required.

1. Check the prerequisites

   Any client that can make a request over an encrypted connection. For the samples, Node.js 18 or later, or Python 3.8 or later. There is no account to create and no key to request.

2. Read a Trust Profile

   Send GET /api/network/profile with a domain in q. Trooth's own record is on the Network, so q=trooth.co is a query with an answer to test against.

3. Branch on found, not on the status alone

   A company the Network does not hold is 200 with { "found": false }. That is an answer. A 503 is not: it means Trooth could not read its own record, and it says nothing about the company. Keep the two apart in your code from the first line.

4. Read each fact with its origin

   Every entry in facts carries origin: what the company declared, what Trooth witnessed, or what a public source says. Show it next to the value. It is most of what the fact is worth.

5. Pin the contract

   Send Trooth-Contract: 2 so a future change of meaning cannot reach your code unannounced. The response names the contract that served it in the same header.

That is a working integration. Next, walk the directory with the cursor, or follow a profile for changes. Before a decision depends on it, read the production checklist.

The public application programming interface (API) needs none. Every endpoint in this reference reads records that are already published, so there is no key to request and no header to set.

Trooth does have authenticated endpoints. They are the ones this product uses to run the company and buyer workspaces, they are session scoped, and they are deliberately not offered as a public API. A documented internal route map helps an attacker and promises an integration that is not supported. When there is a credentialed API worth building on, it will be published here with scopes.

Errors are JSON with an error field. Status codes carry the meaning:

• 400 the request was malformed. The body says which field.
• 404 the Network holds no such record. This is an answer, not a failure, and it is the correct response to a company Trooth has never seen.
• 429 a rate limit. Honor Retry-After when the response carries one. When it does not, pause and retry once.
• 502 and 503 Trooth could not read its own upstream. The body says so in words, and it is never a statement about the company you asked for. Retryable, with a bound.
• 5xx ours. Retryable, with the same bound.

Retries, and where they stop

Three rules, and the third is the one that gets left out.

• Retry only the classes that can change. 429, 502, 503 and the rest of 5xx. A 400 and a 404 are answers: the same request gets the same answer for ever, and repeating it is a loop with a network call in it. A refused cursor is the one to watch, because it arrives in the middle of a paging loop that is already retrying by construction. Start again from the first page, once.
• Count the attempts and stop. Back off between them, cap the number, and surface the failure when the cap is reached rather than continuing quietly. Cap the pages in a paging loop too, for the same reason.
• An outage is not a finding. A 503 means Trooth could not read; it does not mean the company has no record, and writing it down as one publishes our own gap as a fact about a named company. Leave the last good answer in place, or show that the read failed.

Limits are per IP address and run two windows at once, one by the minute and one by the hour. Over either, the response is 429 with a JSON body carrying a plain message. Of the operations in this reference, comparison is the only one this site rate limits itself: 20 requests a minute and 200 an hour from one address. Those figures are read from the constant the route enforces, so this sentence and the limit cannot disagree.

Read the header before you decide how long to wait. Some answers carry Retry-After and some do not, and it varies by route rather than by status code. GET /api/public-mesh/{handle} sends one with its 503, and some of the credentialed workspace routes send one with their 429. The 429 from comparison does not. Where the header is present it is an instruction and the number in it is the wait. Where it is absent, back off yourself and cap the attempts, as the errors section sets out.

Comparison is the tightest of the reads because it fans out. Cached reads are generous: the directory and typeahead sit behind a sixty second edge cache, company records behind one hundred and twenty seconds, and a legal document behind an hour, so a well-behaved client mostly never reaches the origin.

Use the cursor. Send limit, then pass the next_cursor the response returns back as cursor. When next_cursor is null you have the last page. A cursor that cannot be read answers 400 with a sentence, rather than an empty page that looks like the end of the list.

The order, and the tie-break

One key decides the order, and the cursor carries that key. It is built from four fields in this sequence: whether the company is witnessed, then when it was last witnessed with the most recent first, then the lowercased name, then the company's own identifier. The identifier is not decoration. Two companies can share a name, and a sort that leaves a tie unresolved still sorts correctly while making "everything after this row" unanswerable. The last field is unique, so the order is total and every row has exactly one position. That key is in lib/directory-rank.ts, and the comparator the list is sorted with is derived from it rather than written a second time.

What the cursor prevents

It prevents the offset failure, which is real and is why the cursor exists. An offset counts rows. The network grows while you are reading it, so two companies listed between your first page and your second shift everything down: you receive two rows you already had and never see two others, and nothing about the response tells you. A cursor names a position instead, and inserting a row above your position does not change which keys sort after yours.

What it does not prevent

It is not a snapshot, and there is nothing to pin. Every request reads the directory as it stands at that moment. There is no snapshot identifier, no as-of parameter and no version boundary in the cursor. Two of the four fields in the sort key are facts that move: whether a company is witnessed, and the time it was last witnessed. A key that moves across your position has two outcomes, and the response marks neither.

• An omission. A company you have not reached yet is witnessed, or witnessed again, during your walk. Its key moves earlier, which is behind your cursor, and you finish the walk without ever seeing it.
• A duplicate. A company you already received stops being witnessed during your walk. Its key moves later, which is ahead of your cursor, and you receive it a second time.

Both follow from paging a list whose sort key is the thing being updated, and a cursor on its own cannot close either. Treat one walk as one walk, not as one consistent view of the Network.

Deduplicating, and resynchronizing

Key what you receive on slug and drop a repeat; that covers the duplicate, and it is cheap. The omission cannot be detected from inside a single walk, so for a set you intend to treat as complete, walk it again and reconcile the two results rather than trusting one walk. A short walk is worth more than a careful one here: the smaller the window between your first page and your last, the less the list moves underneath it. If your reconciler needs a boundary to work from, use last_scan on the rows themselves rather than the time you made the request.

Every key on a page sorts after the marker you sent, so the marker strictly advances and you cannot loop on the same one. That is not the same as a bounded number of pages: rows added ahead of your position are served to you, so a walk of a fast-growing list can run longer than you expect. Cap the pages, refuse to send a marker you have already sent, and stop on next_cursor being null rather than on an empty page.

Expiry, and what the cursor is not bound to

The cursor does not expire. It carries a payload version and a position, and no issue time, so a marker kept from last week is still read and still honored against today's list. What is refused is a marker from an older payload version, a marker that cannot be decoded, and a marker issued to a workspace-scoped list being used on a public one. Each is a 400 naming which, not a silent reset to page one, because silently restarting is how a client pages for ever without noticing.

The cursor is not bound to your query. q and industry are not carried in it. Send the same cursor with a different filter and it is accepted: you get rows of the new filter that sort after the old position, which is almost certainly not what you meant and looks like a short page rather than an error. Keep the filter beside the cursor in your own code. total is included in every page and is the size of the filtered set on that request, so it changes between pages and is not a target to count up to.

The cursor is opaque and belongs to this list. Do not parse it, build one, or carry it to another endpoint; a marker from elsewhere is refused rather than silently misread.

The offset alias, and how to migrate off it

offset and next_offset still work, because clients already shipped with them. They are deprecated: a response to a request that pages by offset carries a Deprecation header and a Link header with rel="deprecation" pointing here. No withdrawal date is set, so no Sunset header is sent; if one is ever set it will be announced in the changelog before it takes effect. The migration is one step rather than a rewrite: next_cursor is returned on the offset path too, so read it from whichever page you are on, send it as cursor, and stop sending offset. A request carrying both is answered from the cursor, since it is the one that is right.

There is none, and every public endpoint is a read. No operation in this reference creates or changes anything, so a repeated request is safe by construction and there is no idempotency key to send.

This is worth stating rather than leaving to inference, because the answer changes the day a write endpoint appears. When one does, it will carry an idempotency key and this section will say so. Until then, any client that retries a Trooth call is retrying a read.

The profile read is versioned by contract. The current contract is 2, and this deployment answers 1 and 2. Choose one with the Trooth-Contract request header or the contract query parameter. Send neither and you get the current contract.

• Both, disagreeing, is refused. A header and a query parameter naming different contracts is a 400, not a guess at which you meant.
• An unsupported version is refused. A contract this deployment does not answer is a 400 with nothing approximated.
• Every answer names its contract. In the Trooth-Contract response header, in contractVersion, and, for the one you asked for, in requestedContract.
• What moves the number. Removing or renaming a field, or changing what a value means. Adding a field does not, so read the fields you know and ignore the rest.

Deprecations and deadlines

Version 1 is withdrawn on 2027-03-01. It promised one answer per question. That was not true where two sources disagree: the older resolver published whichever answer arrived first and dropped the other without saying so. This response is the version 2 shape, so `facts[].value` is one account and a row with `contested: true` has others in `conflicts`. Move to 2 and read `conflicts`. Until then, a request for version 1 is served the current contract with a Deprecation header and a Sunset header carrying the date.

The full policy is on API versioning, and every deprecation is announced in the changelog with its deadline before it takes effect.

There is one environment, production, and no test mode. Because every public endpoint is a read of published data, a call made while you build changes nothing and costs nothing, so the production endpoints are safe to develop against.

What production cannot do is put a company into a state on request. A domain under .invalid, which is reserved and can never be registered, reliably returns found: false, and a missing q reliably returns 400. For the rest, a failed read, a company with no observation and a contested fact, write fixtures from the published schema and test your handling against them. Those are the states integrations most often get wrong, and they are the ones you will not meet by chance while building.

Validate what you receive against the schema in your own tests. It is the document the route is tested against on every push and checked against after every deployment, so a response that fails it is worth reporting.

Four stable objects underpin every Trooth surface. They are versioned conservatively: fields are added, never silently changed.

Company record

Identity, products, and witnessed posture for one company: stable slug, domains, and the last-witnessed state.

Evidence receipt

One signed reading: source, scope, timestamp, and signature. The unit everything else is built from.

Provenance label

A closed vocabulary for where a fact came from: Trooth witnessed, Re-read on a schedule, Integration supplied, Independent third-party, Declared, Public record, Customer reported, Disputed, Stale, Unknown.

Freshness stamp

Last witnessed date, expected cadence, and stale behavior, so a reader (human or agent) can weigh a fact by its age.

Every material fact carries where it came from, and a client that ignores that will report things Trooth did not say. Three rules matter more than the rest.

• Unknown is never no. An absent fact means Trooth has no evidence either way. Rendering it as a failing control is wrong and is the most common mistake.
• Stale is not the same as wrong. A fact past the refresh window for its category keeps its last value. Weigh it by age rather than discarding it, and take the age from the record's last reading and the category's window rather than from the fact, which carries no date of its own.
• Declared is not witnessed. A company saying something and Trooth reading it from a live system are different claims and carry different labels. Keep them distinct wherever you show them.

The full vocabulary and how each state is reached is in the methodology.

One fact, in full

This is a single entry from facts[] on GET /api/network/profile, which is the unit a Trust Profile is built out of:

{    "key": "hosting.production-regions",    "category": "Hosting",    "label": "Production regions",    "value": "us-east-1, eu-west-1",    "origin": "company-declared"  }

key is stable and scoped to its category, which is not tidiness: Region under hosting and Region under registration are different questions, and a comparison aligned on the bare label puts one company's data residency beside another's registered address. origin is one of three values, company-declared, witnessed and public-source, and it is most of what the fact is worth. A row whose value is blank is not published at all, so an unanswered question reads as unanswered rather than as an empty string.

Where two sources answered one question differently, the fact carries contested and every account sits under the same key in the top-level conflicts array:

"conflicts": [    {      "key": "hosting.production-regions",      "category": "Hosting",      "label": "Production regions",      "accounts": [        { "origin": "company-declared", "value": "eu-west-1" },        { "origin": "witnessed", "value": "us-east-1, eu-west-1" }      ]    }  ]

On a contested fact, value is one account and not the answer. There is no winner field, no preferred source, and the order accounts appear in is the origin vocabulary's fixed order rather than a ranking. Deciding between two accounts is a judgment about the company, and Trooth does not make it for you.

Five dimensions, and they are separate fields

These get collapsed into one another more often than anything else on this contract, and each collapse produces a different wrong sentence about a real company.

• Provenance is facts[].origin, one per fact, always present. Trooth reading a live system and a company writing an answer are different claims.
• Availability is whether Trooth could read at all, and it has three distinct shapes: found: false means the Network holds no such record, a 503 means the read failed and asserts nothing about the company, and witnessed.standing: null means no observation came back on the last reading. Three different kinds of nothing. Collapsing them is how an outage becomes a published finding.
• Freshness is witnessed.lastWitnessed for the last reading and methodology.freshness for the window each category is expected to be refreshed within. It is not on the fact. Do not manufacture a per-fact date by copying the record's.
• Dispute is contested and conflicts, shown above. An uncontested fact is one nobody has answered differently, which is not the same as one that has been corroborated.
• Integrity covers one field of this body and no more. The profile response as a whole is not signed, and a 200 from this endpoint is not a signature over its contents. When the reading behind witnessed was signed under Trooth's witness statement, the body carries witnessStatement: its payload is the exact string Trooth signed, the facts of that reading with no verdict, and its signature is Ed25519 over those bytes, checked with the key its key_id names at verify/keys. An older reading has no statement and the field is absent. Every other field is unsigned.

The contract also names what it deliberately does not carry, in contractOmissions on every response: there is no confidence number per fact or overall, no adjudication between disagreeing sources, no completeness signal, and no merging of two wordings that look equivalent. Each of those is something a reader will otherwise infer from the fields that are present.

Contract version, and the alias still answered

Every response carries contractVersion. It is 2 today and it moves only when a field is removed or renamed or when the meaning of a value changes, so adding a field does not move it and a caller reading known fields is safe across additions. The versions still answered are 1 and 2. Pin one, and treat a value you did not expect as a reason to stop rather than to guess.

Version 1 is withdrawn on 2027-03-01. It promised one answer per question. That was not true where two sources disagree: the older resolver published whichever answer arrived first and dropped the other without saying so. This response is the version 2 shape, so `facts[].value` is one account and a row with `contested: true` has others in `conflicts`. Move to 2 and read `conflicts`. That notice also arrives in the deprecation field of every response served at version 1, while it still works, so a caller does not have to be reading this page to find out.

Nine operations, every one a read of published data, and none of them needs a credential. The machine-readable contract is at /openapi.json, OpenAPI 3.1, generated from the source and checked on every build.

• GET /api/compareCompare companies side by side
• GET /api/legal/{slug}A published legal document
• GET /api/mobile/directory/featuredCompanies with a witnessed record
• GET /api/mobile/directory/searchSearch the Trooth Network
• GET /api/mobile/directory/vendor/{slug}One company record
• GET /api/network/profileOne company's canonical profile and witness facts
• GET /api/network/suggestTypeahead over published companies
• GET /api/public-mesh/{handle}A company's public evidence rollup
• GET /api/versionThe deployment currently serving

Each operation has its own entry below, with its parameters, the answers it gives and a request you can copy.

One company's canonical profile and witness facts.

The canonical published profile for a company, keyed by domain or slug, with the witness facts a buyer's tool needs: the standing field (the witnessed state), lastWitnessed (freshness), firstWitnessedAt and the unbroken run of Trooth's own hourly readings (continuity), and checksPassed out of checksRun on the signed result (coverage: checks that read as expected, out of checks run). Continuity is never claimed older than Trooth's own record and stays null until two consecutive readings agree. Responds { found: false } with 200 when no profile is published, 400 when q is missing. Cached at the edge for 120 seconds. Every response carries a methodology object stating the reading cadence, the gap tolerance that defines an unbroken series, the retention period, the per-category freshness windows, and an explicit list of coverage limits - what Trooth does not read. A caller restating witnessed or updatedAt elsewhere must carry those limits with it: neither field is a certification nor an audit opinion.

Parameters

qstring, in queryRequired

Company domain (example.com) or Trooth slug.

contractstring, in query

Pin the response contract version, here or in the Trooth-Contract request header (not both with different values, which is refused with 400). Omit for the current contract. A version this deployment does not answer is refused with 400 rather than approximated. Every response names the contract that served it in the Trooth-Contract response header and in contractVersion, and the one requested in requestedContract; a request for contract 1 is served contract 2 with Deprecation and Sunset headers until 2027-03-01.

Returns

200

The record, or { found: false } when the Network holds none. The body is written to a published JSON Schema and validated against it on every push and after every deployment.

400

The q parameter is missing, a contract version this deployment does not answer was requested, or the query and the Trooth-Contract header asked for different contracts.

503

Trooth could not read its own record on this load. Retry after the Retry-After interval; nothing is asserted about the company.

Search the Trooth Network.

Full-text search over published company listings. Returns the same companies the public directory shows. Prefer cursor pagination: pass the returned next_cursor back as cursor. Offset pagination still works and is kept for clients that already ship with it, but it is deprecated: it counts rows rather than naming a position, so a directory that grows between two requests can serve the same company twice and skip another without erroring. A response to an offset-paged request carries a Deprecation header and a Link header with rel="deprecation"; no withdrawal date is set, so no Sunset header is sent. A cursor that cannot be read returns 400 rather than an empty page. Cached at the edge for 60 seconds with a 300 second stale-while-revalidate window.

Parameters

qstring, in query

Search terms. Matched against company name and description.

industrystring, in query

Restrict to one industry.

limitinteger, in query

Results per page. Clamped to 100; anything unreadable falls back to 25.

cursorstring, in query

Opaque page marker. Use next_cursor from the previous response. Preferred over offset.

offsetinteger, in queryDeprecated

Zero-based offset. Use next_offset from the previous response. Deprecated in favor of cursor; still answered, with a Deprecation header on the response.

Returns

200

A page of results.

400

A cursor that cannot be read.

503

The directory could not be read. Not a statement about any company.

Companies with a witnessed record.

The Trooth Network's front page: published companies, those with a witnessed record first. Cached at the edge for 120 seconds.

Parameters

None.

Returns

200

Published companies.

503

The directory could not be read.

One company record.

A published company profile, and its live witnessed state where Trooth has witnessed the company. A slug of the form d--example.com resolves a witnessed company that has not yet published a rich profile. Cached at the edge for 120 seconds.

Parameters

slugstring, in pathRequired

Company slug, or d--<domain>.

Returns

200

The company record.

404

The company is not on the Trooth Network.

503

The record could not be read. Not a statement about the company.

Typeahead over published companies.

Name-to-company suggestions for a search box, over the same published listings the directory shows. Cached at the edge for 60 seconds.

Parameters

qstring, in queryRequired

Partial company name.

Returns

200

Suggestions, possibly none.

A company's public evidence rollup.

The buyer-facing projection of a company's evidence: the witnessed state per pillar, provider status with the time each connected system was last read. Framework rollups were retired on 2026-09-26 and the frameworks array is always empty. Individual control rows, owners and internal notes are never returned here. Responds 404 when the company has no public record, which is a privacy-preserving answer rather than an error. Readable cross-origin (Access-Control-Allow-Origin: *); this is the read the embeddable badge performs. Cached at the edge for 300 seconds.

Parameters

handlestring, in pathRequired

Company handle.

Returns

200

The rollup, with framework percentages retired (empty) since 2026-09-26.

404

No public record for this handle.

503

The record could not be read. Not a statement about the company.

Compare companies side by side.

A comparison of published witnessed facts across up to a handful of companies. Control rows are stripped, so a company's internal posture is never exposed through the comparison. Rate limited.

Parameters

handlesstring, in queryRequired

Comma-separated company handles.

Returns

200

The comparison.

429

Rate limited. Retry after a short pause.

502

No company in the request could be read.

A published legal document.

The full text of one of the twenty published Trooth legal documents, with its title, effective date and body. The slug must be one of the published set; anything else responds 404. Cached at the edge for one hour with a one day stale-while-revalidate window.

Parameters

slugstring, in pathRequired

Document slug, for example privacy, terms, subprocessors.

Returns

200

The document.

404

Unknown document.

The deployment currently serving.

The build stamp of the running deployment. Never cached. Useful for confirming which release answered a request.

Parameters

None.

Returns

200

The build stamp.

Retrieval agents are welcome and robots.txt says so explicitly: an assistant answering a question about a vendor right now is the case this network exists for. Model-training crawlers are blocked, because the companies whose evidence is published here did not consent to wholesale ingestion.

Cite what you read. Every material fact has a source and a date, and an answer that carries them is worth more than one that does not. When Trooth holds no record, say so rather than filling the gap.

The Model Context Protocol (MCP) server is live at https://api.trooth.co/public/mcp, over JSON-RPC 2.0. It is public and needs no key. It leads with protocol 2026-07-28 and reports itself as trooth-mcp 1.1.0, and it still answers 2025-06-18, 2025-03-26 or 2024-11-05, so a client written against the earlier handshake keeps working. It serves 4 tools: trooth_public_trust_profile, trooth_outside_in_read, trooth_verify and trooth_ask. Each is read only, takes one required string argument, and answers with structuredContent (status, provenance, subject, summary) next to the text. The server also lists 4 resources (trooth://methodology, trooth://provenance-labels, trooth://verify-a-vendor, trooth://what-a-call-sends) and 3 prompts (vendor_trust_check, verify_trust_token, before_you_trust). Setup and the full catalog are on Agents and MCP, and changes are announced in the changelog.

Companies configure webhooks in their own workspace to push posture changes into their tools. There is also one public subscription route for agents and buyers: POST https://api.trooth.co/public/trust/:slug/agent-subscribe with a webhookUrl returns a signing secret, follows published profiles only, and delivers trust.posture.changed events signed with x-trooth-signature. That event and its envelope belong to this route alone; the workspace endpoints have their own event list. Details are on Agents and MCP.

There is no SDK, and no Trooth package under a scope: any @trooth/ scope name you find is not ours. The endpoints are plain HTTP and JSON, and a fetch or a curl is the whole integration. A generated client from /openapi.json works if you want types.

One package is published: trooth on npm, the command line client, source at github.com/troothllc/trooth-cli. It has two commands. trooth check <domain> reads a public record, and trooth lint [path] reads what your own repository declares and makes no request at all. It is not a wrapper around this reference: it does not read a key and it reaches only the directory endpoint. Anything else you have seen it described as doing, trooth scan in particular, was retired and now exits with a sentence explaining that rather than running.

Six checks, each one a failure an integration has already had somewhere.

1. Handle every class of answerA 200 with found: false, a 400, a 404, a 429 and a 5xx each need their own branch. A 503 is never written down as a finding about a company.
2. Bound retries and pagesRetry 429 and 5xx only, back off, cap the attempts and surface the failure. Cap the pages of a cursor walk and refuse to send a cursor twice.
3. Stay inside the limitsComparison allows 20 requests a minute and 200 an hour from one address. The other reads are served from an edge cache, so polling faster than the cache window returns the same answer.
4. Pin the contract and watch for deprecationSend the contract header, read the deprecation field on every response, and treat a Deprecation or Sunset header as a dated task, not a warning to ignore.
5. Carry provenance and dates to your usersKeep origin next to each value, take age from the record's last reading and the category's window, and never render unknown as no.
6. Know what is promisedThe service level agreement and the API terms state what Trooth commits to and the remedies available. Read both before a decision depends on this interface.

The terms are the service level agreement and the API terms.

Breaking changes to the shape of these responses are announced in the changelog before they ship, and the versioning and deprecation policy is at API versioning. Live availability is at status, and GET /api/version tells you which deployment answered your request.

Questions go to developers@trooth.co.