ClaimTrace API reference (v1)

Base URL: https://claimtrace.dev. Authentication: header X-API-Key: afk_…. The v1 transport contract is stable: no field is removed or changes meaning without a major version.

Endpoints

Method	Path	Purpose
`POST`	`/v1/signup`	Self-serve key (email → `afk_…` key, shown once, 50 trial credits)
`POST`	`/v1/fetch`	Blocking call — full `FetchResultV1` JSON
`GET`	`/v1/fetch/stream`	SSE stream — `meta` → `entity`… → `done`
`GET`	`/v1/requests/{request_id}`	Re-read a result (24 h TTL, isolated per key)
`GET`	`/v1/usage`	Your tier, remaining credits, requests today
`GET`	`/v1/stats`	Public service counters of the day (no key required)
`GET`	`/v1/health`	Service status + schema version

Request — `POST /v1/fetch`

{
  "thematique": "restaurants menus du jour",
  "lieu": "Neuchâtel",
  "prompt": "the actual daily menu, with prices if published",
  "depth": "standard",
  "max_entities": 8,
  "day": "2026-08-08"
}

Field	Type	Constraints
`thematique`	string	required, 2–200 chars — what kind of entities
`prompt`	string	required, 2–4000 chars — the fact you want established
`lieu`	string	optional, ≤ 200 chars — geographic scope
`depth`	string	`fast` · `standard` (default) · `deep` (Pack M+)
`max_entities`	int	1–30, default 8
`day`	string	optional, `YYYY-MM-DD` — for dated data (e.g. daily menus)

Response — `FetchResultV1`

Field	Type	Meaning
`schema_version`	`"1"`	Contract version
`request_id`	string	Re-read handle for `/v1/requests/{id}` (24 h)
`query`	`QueryEchoV1`	Echo: `thematique`, `lieu`, `day`, `depth`, `vertical`
`entities`	`EntityV1[]`	The resolved entities
`verification`	`VerificationV1`	`truth_rules_version`, `verified_live`, `checked_at`, `notes`
`usage`	`UsageV1`	`credits_charged`, `cache_hits`, `cost_class`
`warnings`	string[]	Degradations, stated instead of hidden
`attribution`	string[]	e.g. `© OpenStreetMap contributors (ODbL)`

`EntityV1`

Field	Type	Meaning
`id`	string	Stable entity id within the response
`title`	string	Entity name
`summary`	string \	null	Short description when available
`location`	`GeoV1` \	null	`address`, `city`, `country`, `lat`, `lng`
`contact`	`ContactV1` \	null	`phone`, `email`, `website`
`attributes`	object	Vertical-specific attributes
`claims`	`ClaimV1[]`	The verified facts — see below
`images`	`ImageV1[]`	`url`, `role`, `caption`
`confidence`	float \	null	Entity-level confidence, 0–1
`not_found`	`NotFoundV1` \	null	Present when the requested data is not published

`ClaimV1` — the heart of the product

Field	Type	Meaning
`field`	string	Which fact, e.g. `menu_du_jour`
`value`	any	The fact itself — `null` is allowed and assumed
`provenance.source_url`	string \	null	The page or document the fact was read from
`provenance.fetched_at`	string \	null	When it was read (ISO 8601 UTC)
`provenance.verbatim`	string \	null	Short proof excerpt, literally from the source
`provenance.page_kind`	string \	null	e.g. `menu_du_jour`, `carte`
`provenance.domain_owned_by_entity`	bool \	null	Whether the source belongs to the entity
`confidence`	float \	null	0–1
`verified_live`	bool \	null	Tri-state: live-confirmed / contradicted / not checked

`NotFoundV1` — absence is an answer

Field	Type	Meaning
`reason`	string	e.g. `not_published`, `source_unreachable`
`detail`	string \	null	Human-readable explanation
`source_checked`	string \	null	The source that was actually read

What v1 never returns

Fields whose only source is Google Places — ratings, review counts, price levels, Google-hosted images — are excluded from the payload for legal reasons (Google Maps Platform terms of service prohibit exporting or re-sharing Places content). Claims come exclusively from sources owned by the entity, enforced by a domain-ownership whitelist.

Errors

Code	Meaning
`401`	Missing or invalid API key
`402`	Credits exhausted — top up or wait for the monthly refill
`404`	On `/v1/requests/{id}`: unknown or expired result for this key
`409`	On `/v1/signup`: an active key already exists for this email
`422`	Validation error — a field violates the constraints above
`429`	Rate limit — response carries `Retry-After`

Refusals are never charged.

ClaimTrace API reference (v1)

Endpoints

Request — POST /v1/fetch

Response — FetchResultV1

EntityV1

ClaimV1 — the heart of the product

NotFoundV1 — absence is an answer