ClaimTrace documentation

One API key, one blocking endpoint, one SSE stream. The schema is stable: no field is removed without a major version. Errors are honest: explicit 401 / 402 / 422 / 429, degradations reported in warnings.

1. Get your key (free, self-serve)

curl -X POST https://claimtrace.dev/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.ch"}'

Your afk_… key is sent to that email address (it is never shown in the response nor on any page) with 50 trial credits (plus the monthly refill of the free tier). One key per email address: signing up again returns 409 and your existing key stays valid, it is never silently reset.

2. Blocking call — one JSON response

curl -X POST https://claimtrace.dev/v1/fetch \
  -H "X-API-Key: $CLAIMTRACE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "thematique": "restaurants menus du jour",
    "lieu": "Neuchâtel",
    "prompt": "the actual daily menu, with prices if published"
  }'

The response is a FetchResultV1 envelope: a list of entities, each carrying its claims — and every claim carries its provenance (source_url, date read, verbatim excerpt), a confidence score and a live-verification tri-state. When the source publishes nothing, the entity carries an explicit not_found with the reason and the source that was checked. Nothing is filled in.

3. SSE stream — entities as they come

curl -N "https://claimtrace.dev/v1/fetch/stream?\
thematique=restaurants%20menus%20du%20jour&lieu=Neuch%C3%A2tel&\
prompt=the%20actual%20daily%20menu" \
  -H "X-API-Key: $CLAIMTRACE_KEY"

Events arrive in order: meta (request id, echoed query) → entity (one EntityV1 at a time, as each is resolved) → done (usage and verification summary). The stream endpoint is a GET — pass the same parameters as the blocking call in the query string.

Re-read a result (idempotence)

Every response carries a request_id. For 24 hours you can re-fetch the same result without paying again:

curl https://claimtrace.dev/v1/requests/$REQUEST_ID \
  -H "X-API-Key: $CLAIMTRACE_KEY"

Results are isolated per key: you can only re-read your own.

Track your usage

curl https://claimtrace.dev/v1/usage -H "X-API-Key: $CLAIMTRACE_KEY"

Returns your tier, remaining credits and today's request count. Public service counters (real ones, measured in production — no extrapolated rates) are at GET /v1/stats, no key required.

What you are billed

1 credit = 1 entity freshly resolved and verified. A fact already verified recently (shared cache, at most 24 h for dated data) is served free. Refusals — rate limit reached, credits exhausted, invalid request — are never charged. The deep depth is reserved for Pack M and above.

Errors you can rely on

Request limits: thematique 2–200 characters (required) · prompt 2–4000 characters (required) · lieu up to 200 characters (optional) · depth one of fast, standard (default), deep · max_entities 1–30 (default 8) · day optional YYYY-MM-DD.

Next: the full API reference — every field of FetchResultV1, EntityV1 and ClaimV1, or try it without writing a line in the console.