Documentation ClaimTrace

Une clé API, un endpoint bloquant, un flux SSE. Le schéma est stable : aucun champ n'est retiré sans version majeure. Les erreurs sont honnêtes : 401 / 402 / 422 / 429 explicites, dégradations signalées dans warnings.

1. Obtenez votre clé (gratuit, self-serve)

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

Votre clé afk_… est envoyée à cette adresse email (elle n'est jamais affichée, ni dans la réponse ni sur une page) avec 50 crédits d'essai (plus la recharge mensuelle du tier gratuit). Une clé par adresse email : une réinscription renvoie 409 et votre clé existante reste valide, jamais réinitialisée en silence.

2. Appel bloquant — une réponse JSON

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": "le menu du jour réel, avec prix si publié"
  }'

La réponse est une enveloppe FetchResultV1 : une liste d'entités, chacune portant ses claims — et chaque claim porte sa provenance (source_url, date de lecture, extrait verbatim), un score de confiance et un tri-état de vérification live. Quand la source ne publie rien, l'entité porte un not_found explicite avec la raison et la source consultée. Rien n'est comblé.

3. Flux SSE — les entités au fil de l'eau

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

Les événements arrivent dans l'ordre : meta (id de requête, écho de la requête) → entity (une EntityV1 à la fois, au fil de leur résolution) → done (résumé usage et vérification). L'endpoint de stream est un GET — passez les mêmes paramètres que l'appel bloquant dans la query string.

Relire un résultat (idempotence)

Chaque réponse porte un request_id. Pendant 24 heures, vous pouvez relire le même résultat sans repayer :

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

Les résultats sont isolés par clé : vous ne relisez que les vôtres.

Suivre votre consommation

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

Renvoie votre tier, vos crédits restants et le compteur de requêtes du jour. Les compteurs publics du service (les vrais, mesurés en production — aucun taux extrapolé) sont sur GET /v1/stats, sans clé.

Ce qui vous est facturé

1 crédit = 1 entité résolue et vérifiée à neuf. Un fait déjà vérifié récemment (cache partagé, 24 h au plus pour les données datées) est servi gratuitement. Les refus — limite atteinte, crédits épuisés, requête invalide — ne sont jamais facturés. La profondeur deep est réservée aux packs M et supérieurs.

Des erreurs sur lesquelles compter

Limites de requête : thematique 2–200 caractères (requis) · prompt 2–4000 caractères (requis) · lieu jusqu'à 200 caractères (optionnel) · depth parmi fast, standard (défaut), deep · max_entities 1–30 (défaut 8) · day optionnel AAAA-MM-JJ.

Suite : la référence API complète — chaque champ de FetchResultV1, EntityV1 et ClaimV1, ou essayez sans écrire une ligne dans la console.