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"}'

You receive your afk_… key — shown only once — 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.