Trust records your code can read.

Endpoints

Eight 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.

Authentication

The public API needs none. Every endpoint above 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.

Rate limits

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. There is no retry-after header yet; a short pause and one retry is the right behaviour.

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.

Pagination

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.

Offset still works and is not going away, because clients already ship with it: send limit and offset and follow next_offset. It is worth knowing what you are choosing. An offset counts rows; a cursor names a position. The network grows while you are reading it, so two companies getting witnessed between your first page and your second shifts everything down: you receive two rows you already had and never see two others, and nothing about the response tells you it happened. The cursor cannot do that, because inserting a row above your position does not change which rows sort after it.

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.

Idempotency

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.

Errors

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. Pause and retry once.
• 5xx ours. Retry with backoff.

Reading a record correctly

Trooth records carry a provenance label and a freshness stamp on every material fact, and a client that ignores them 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 never wrong. A fact past its expected refresh keeps its last value and says how old it is. Weigh it by age rather than discarding it.
• 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.

For AI agents

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.

There is no MCP server yet. When there is, it will be announced on this page and in the changelog, with the tool catalogue and its scopes.

Webhooks and SDKs

Webhooks are a company feature rather than a public one: a company configures them in its own workspace to push posture changes into its tools. There is no public subscription endpoint, so nothing to document here yet.

There is no SDK. 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.

Changes and status

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.