# TruthFoundry - Verified News Intelligence API
> https://truthfoundry.ai

A signed, dated record of world events for humans and AI agents, frozen day by day. Rich
structured fields per article (entities, signals, events, facts), Ed25519 provenance
throughout.
678 publishers in 17 languages in the last 24 hours; 4,835 publishers and 19 languages on the record.

## Endpoints
- GET /v1/search?q={query}&since=7d&limit=20&kind= - Full-text search
- GET /v1/articles?topic=&category=&language=&since=24h&kind= - Browse
- GET /v1/articles/{id} - Article detail with all fields
- GET /v1/articles/{id}/provenance - Ed25519 receipt chain
- GET /v1/ask?q={question}&kind= - Retrieve-then-reason cited answer
- GET /v1/factcheck?q={claim} - Check a claim against the signed record: verdict + the exact facts, witnesses, and a receipt on every line (instruments=1 for the free agent contract)
- GET /v1/signals?ticker=TSLA&direction=DOWN - Momentum signals
- GET /v1/topics?since=24h - Trending topics
- GET /v1/entities?name=Jensen+Huang&type=person&kind= - Entity search
- GET /v1/events?since=7d&type=deadline&kind= - Event calendar
- GET /v1/facts?subject=Federal+Reserve - Fact search
- GET /v1/claims - Corroborated claims (2+ publishers word-for-word; default browse holds back generic boilerplate and reports generic_excluded, generic=1 for the raw tier)
- GET /health - Service health

## Content kinds (added 2026-06-12)
Every article carries a kind: news | blog | release_notes | spec | forum_social.
Filter with kind= (comma-separated multi-value, e.g. kind=news,blog; invalid
values are a 400). No kind param = all kinds. News surfaces (homepage, digests,
movers) default to news+blog; dev content (Reddit/HN threads, GitHub release
notes, EIP/RFC specs) is segmented behind kind=, not dropped. e.g.
kind=release_notes,spec,forum_social is the dev-radar slice.

## Machine-readable surfaces
- GET /openapi.json - OpenAPI 3.1 spec (live origin injected)
- POST /mcp - MCP JSON-RPC endpoint (Streamable HTTP)
- GET /mcp.json - ready-to-paste MCP client config
- GET /.well-known/mcp/server-card.json - MCP server card
- GET /.well-known/api-catalog - RFC 9727 catalog of these surfaces
- GET /pricing.json - canonical machine-readable prices + quotas (subscriptions, x402, free doors)
- GET /.well-known/security.txt - security contact (RFC 9116)
- GET /llms.txt - this file

## MCP (Model Context Protocol)
Streamable HTTP MCP server at POST /mcp - 13 tools: search_news, list_articles, get_article, get_article_provenance, get_signals, get_trending_topics, search_entities, get_events, search_facts, check_claim, get_digests, list_query_templates, run_query.
Client config: GET /mcp.json

## Authentication
X-Newsboy-Key header or Authorization: Bearer. /v1/* endpoints require a key, with
two free exceptions: the full record is free to read on the web, and keyless
GET /v1/factcheck?instruments=1 answers without a key or payment (the agent
contract - deterministic, per-IP rate limited). Free keys: POST /billing/signup.
Paid plans: live prices and quotas at GET /pricing.json (the one canonical machine
source; the human page is /pricing). Keyless agents: any other credentialless /v1
GET answers 402 with complete x402 terms (USDC on Base; see /auth.md). Usage: GET /v1/usage.

## Verify (worked example)
Provenance keys: GET /.well-known/truth-foundry-keys.json (frozen issuance dates;
the fleet registry at https://status.drm3.network/.well-known/drm3-keys.json carries
the fetch/analyze signers and the Root). A REAL receipt you can verify right now, no
key, no payment:
https://feeds.data.drm3.network/receipts/rcpt_06f75feb3ca19a8d/verify?day=2026-08-01
Fleet-registry signature envelope: registry_integrity.signature is Ed25519 over the
UTF-8 bytes of the content_hash STRING ("sha256:<hex>"); content_hash is SHA-256 of
the canonical JSON of services[] (recursively sorted keys, compact separators, no
whitespace, undefined-valued keys dropped, UTF-8).

TruthFoundry is an open alpha: expect schema additions and visible sync lag on /health.