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

Vous recevez votre clé afk_… — affichée une seule fois — 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.