Référence API ClaimTrace (v1)

URL de base : https://claimtrace.dev. Authentification : header X-API-Key: afk_…. Le contrat de transport v1 est stable : aucun champ n'est retiré ni ne change de sémantique sans version majeure.

Endpoints

Méthode	Chemin	Rôle
`POST`	`/v1/signup`	Clé self-serve (email → clé `afk_…`, affichée une fois, 50 crédits d'essai)
`POST`	`/v1/fetch`	Appel bloquant — JSON `FetchResultV1` complet
`GET`	`/v1/fetch/stream`	Flux SSE — `meta` → `entity`… → `done`
`GET`	`/v1/requests/{request_id}`	Relecture d'un résultat (TTL 24 h, isolé par clé)
`GET`	`/v1/usage`	Votre tier, crédits restants, requêtes du jour
`GET`	`/v1/stats`	Compteurs publics du service du jour (sans clé)
`GET`	`/v1/health`	État du service + version du schéma

Requête — `POST /v1/fetch`

{
  "thematique": "restaurants menus du jour",
  "lieu": "Neuchâtel",
  "prompt": "le menu du jour réel, avec prix si publié",
  "depth": "standard",
  "max_entities": 8,
  "day": "2026-08-08"
}

Champ	Type	Contraintes
`thematique`	string	requis, 2–200 caractères — quel type d'entités
`prompt`	string	requis, 2–4000 caractères — le fait à établir
`lieu`	string	optionnel, ≤ 200 caractères — périmètre géographique
`depth`	string	`fast` · `standard` (défaut) · `deep` (Pack M+)
`max_entities`	int	1–30, défaut 8
`day`	string	optionnel, `AAAA-MM-JJ` — pour les données datées (ex. menus du jour)

Réponse — `FetchResultV1`

Champ	Type	Signification
`schema_version`	`"1"`	Version du contrat
`request_id`	string	Poignée de relecture pour `/v1/requests/{id}` (24 h)
`query`	`QueryEchoV1`	Écho : `thematique`, `lieu`, `day`, `depth`, `vertical`
`entities`	`EntityV1[]`	Les entités résolues
`verification`	`VerificationV1`	`truth_rules_version`, `verified_live`, `checked_at`, `notes`
`usage`	`UsageV1`	`credits_charged`, `cache_hits`, `cost_class`
`warnings`	string[]	Les dégradations, dites plutôt que cachées
`attribution`	string[]	ex. `© OpenStreetMap contributors (ODbL)`

`EntityV1`

Champ	Type	Signification
`id`	string	Identifiant stable de l'entité dans la réponse
`title`	string	Nom de l'entité
`summary`	string \	null	Description courte si disponible
`location`	`GeoV1` \	null	`address`, `city`, `country`, `lat`, `lng`
`contact`	`ContactV1` \	null	`phone`, `email`, `website`
`attributes`	object	Attributs propres au vertical
`claims`	`ClaimV1[]`	Les faits vérifiés — voir ci-dessous
`images`	`ImageV1[]`	`url`, `role`, `caption`
`confidence`	float \	null	Confiance au niveau entité, 0–1
`not_found`	`NotFoundV1` \	null	Présent quand la donnée demandée n'est pas publiée

`ClaimV1` — le cœur du produit

Champ	Type	Signification
`field`	string	Quel fait, ex. `menu_du_jour`
`value`	any	Le fait lui-même — `null` autorisé et assumé
`provenance.source_url`	string \	null	La page ou le document où le fait a été lu
`provenance.fetched_at`	string \	null	Quand il a été lu (ISO 8601 UTC)
`provenance.verbatim`	string \	null	Court extrait de preuve, littéral depuis la source
`provenance.page_kind`	string \	null	ex. `menu_du_jour`, `carte`
`provenance.domain_owned_by_entity`	bool \	null	La source appartient-elle à l'entité
`confidence`	float \	null	0–1
`verified_live`	bool \	null	Tri-état : confirmé live / démenti / non vérifié

`NotFoundV1` — l'absence est une réponse

Champ	Type	Signification
`reason`	string	ex. `not_published`, `source_unreachable`
`detail`	string \	null	Explication lisible
`source_checked`	string \	null	La source réellement consultée

Ce que la v1 ne renvoie jamais

Les champs dont la seule source est Google Places — notes, nombres d'avis, niveaux de prix, images hébergées par Google — sont exclus du payload pour des raisons juridiques (les conditions Google Maps Platform interdisent d'exporter ou repartager le contenu Places). Les claims proviennent exclusivement de sources appartenant à l'entité, garanties par une liste blanche de propriété de domaine.

Erreurs

Code	Signification
`401`	Clé API absente ou invalide
`402`	Crédits épuisés — rechargez ou attendez la recharge mensuelle
`404`	Sur `/v1/requests/{id}` : résultat inconnu ou expiré pour cette clé
`409`	Sur `/v1/signup` : une clé active existe déjà pour cet email
`422`	Erreur de validation — un champ viole les contraintes ci-dessus
`429`	Limite de débit — la réponse porte `Retry-After`

Les refus ne sont jamais facturés.

Référence API ClaimTrace (v1)

Endpoints

Requête — POST /v1/fetch

Réponse — FetchResultV1

EntityV1

ClaimV1 — le cœur du produit

NotFoundV1 — l'absence est une réponse