Migration du contrat de réponse v2

Cette page documente une mise à jour du contrat de réponse des endpoints publics /v2. Elle corrige plusieurs incohérences entre le comportement réel de l’API et ce qui était documenté : type de certains champs, structure des erreurs, réponses d’authentification.

Danger

Ces changements sont des breaking changes pour tout client qui parse les réponses selon l’ancien format (typage strict d’un champ, accès positionnel, lecture en stream). Testez votre intégration contre le nouveau format avant de basculer en production.

Résumé des changements

Endpoint	Changement
POST /v2/extractor[/:agentReference]	Erreurs enveloppées avec code ; metadata.duration passe de string à nombre
POST /v2/extractor (global)	data initialisé à [] (plus null) ; metadata.thread_id ajouté
POST /v2/extractor/async[/:agentReference]	Réponse immédiate simplifiée à {status, extract_id} ; callback et webhook d’échec enveloppés avec code et detail.http_status numérique
POST /v2/documentalist/:agentReference	Déprécié (sunset 2026-11-30) — reste un flux texte HTTP 200 ; remplacé par /v2/knowledge
POST /v2/knowledge/:agentReference	Nouveau — réponse JSON classique avec de vrais status HTTP d’erreur (mêmes paramètres que /v2/documentalist)
GET /v2/token	Le 401 renvoie désormais une enveloppe d’erreur (au lieu d’un corps vide)
Toutes les routes protégées	Les rejets 401/403 renvoient une enveloppe d’erreur (au lieu de {message: "Unauthorized"})
Endpoints organisation (/v2/organization/webhooks, /v2/organization/usage)	Le code d’erreur 404 d’organisation introuvable passe de agent_not_found à organization_not_found

Extracteur

Erreurs synchrones (/v2/extractor et /v2/extractor/:agentReference)

Avant — un message générique, identique quelle que soit la cause réelle de l’échec :

{
    "status": "error",
    "error": "Error while processing the extraction"
}

Après

{
    "status": "error",
    "code": "extraction_failed",
    "error": "Extraction stream failed",
    "detail": { }
}

code est désormais un identifiant machine stable (voir tableau des codes) — error reste un message humain qui peut évoluer sans préavis. detail est optionnel et absent la plupart du temps.

Attention

Ne pilotez jamais votre logique sur le texte de error — utilisez code.

metadata.duration : string → nombre

Avant

{ "metadata": { "duration": "3.45", "tokens_consumed": 1 } }

Après

{ "metadata": { "duration": 3.45, "tokens_consumed": 1 } }

Si votre client parse déjà duration avec parseFloat/Number() par précaution, aucun changement requis. Si vous concaténez ou comparez la valeur comme une string, adaptez le typage.

Extracteur global : data et thread_id

Avant — en cas d’échec de lecture du flux, data pouvait valoir null et metadata n’incluait pas thread_id :

{ "data": null, "metadata": { "filename": "facture.pdf", "duration": "0.00", "tokens_consumed": 0 } }

Après — data est toujours un tableau ([] si rien n’a été extrait), et metadata.thread_id est désormais présent (déjà le cas pour l’extracteur avec agent) :

{ "data": [], "metadata": { "filename": "facture.pdf", "duration": 0, "tokens_consumed": 0, "thread_id": "01J..." } }

Réponse immédiate asynchrone (/v2/extractor/async et /v2/extractor/async/:agentReference)

Avant

{
    "status": "started",
    "extract_id": "550e8400-e29b-41d4-a716-446655440000",
    "data": {
        "message": "Old extraction id is deprecated, use extract_id instead",
        "extraction_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}

Après

{
    "status": "started",
    "extract_id": "550e8400-e29b-41d4-a716-446655440000"
}

Le champ data (et extraction_id) était un résidu de l’ancien identifiant — il n’a plus lieu d’être. Si votre code lisait data.extraction_id, basculez sur extract_id (c’était déjà la valeur recommandée).

Callback et webhook d’échec

Concerne le callback transmis par requête et l’événement extraction.completed en échec.

Avant

{
    "extract_id": "550e8400-e29b-41d4-a716-446655440000",
    "error": "Extraction failed: Unable to process the document",
    "detail": "HTTP status: 500"
}

Après

{
    "status": "error",
    "extract_id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "agent_timeout",
    "error": "Agent response timed out",
    "detail": { "http_status": 504 }
}

Trois changements : un champ status: "error" explicite apparaît (avant, l’absence de status: "success" était le seul signal d’échec) ; code porte désormais le vrai code machine de l’erreur (avant : toujours un message générique, aucun code) ; detail devient un objet { http_status: <number> } (avant : une string "HTTP status: X").

Attention

Si votre parsing du callback ou du webhook extrait le status HTTP depuis la string detail (ex. detail.split(": ")[1]), il cassera — lisez detail.http_status directement.

Documentaliste

POST /v2/documentalist/:agentReference est déprécié (sunset 30 novembre 2026) et reste un flux texte brut HTTP 200 — c’est POST /v2/knowledge/:agentReference qui prend le relais, avec une réponse JSON classique et de vrais status HTTP d’erreur. Les deux endpoints acceptent les mêmes paramètres d’entrée (query, instructions optionnel, thread_id optionnel, historic optionnel).

Danger

POST /v2/documentalist/:agentReference renvoie désormais les en-têtes Deprecation: true, Sunset: Sun, 30 Nov 2026 23:59:59 GMT et Link: </v2/knowledge/:agentReference>; rel="successor-version". Migrez vers /v2/knowledge avant cette date.

Avant / toujours sur /v2/documentalist — HTTP 200, réponse en stream (un seul chunk émis) :

Désolé, je ne peux pas vous donner de réponse pour le moment.

Ce même texte d’excuse est renvoyé pour la plupart des échecs internes — impossible de distinguer une erreur réelle d’une réponse normale sans inspecter le contenu. Seuls agent_not_found et thread_not_found court-circuitent le flux avec un vrai 404 (corps texte brut, sans enveloppe JSON).

Après / sur /v2/knowledge — succès :

{
    "status": "success",
    "data": { "answer": "Dimarc est une plateforme d'intelligence artificielle..." },
    "metadata": { "thread_id": "01J..." }
}

Après / sur /v2/knowledge — erreurs, avec de vrais status HTTP :

Status	Code	Cas
404	agent_not_found	Agent introuvable, mauvais type, privé, ou hors de votre organisation
404	thread_not_found	thread_id fourni ne correspond pas à un thread de cet agent
503	agent_unavailable	File de traitement indisponible
504	agent_timeout	Timeout de la réponse agent
502	extraction_failed	L’agent n’a pas pu répondre

Attention

Si votre client lit la réponse comme un ReadableStream (response.body.getReader(), fetch en streaming, etc.), c’est qu’il cible encore /v2/documentalist — basculez vers /v2/knowledge, qui renvoie un JSON classique. /v2/documentalist ne redeviendra pas du JSON avant son retrait.

Token

GET /v2/token — le succès est inchangé. Le 401 renvoie désormais une enveloppe :

Avant

(corps vide)

Après

{
    "status": "error",
    "code": "invalid_client",
    "error": "Invalid client credentials"
}

Rejets d’authentification (toutes les routes protégées)

Avant

{ "message": "Unauthorized" }

Après

Status	Code	Cas
401	unauthorized	En-tête x-api-key manquant ou invalide
403	forbidden	Accès API désactivé pour votre organisation

{ "status": "error", "code": "unauthorized", "error": "Unauthorized" }

Codes d’erreur

L’ensemble des codes machine (code) que l’API peut renvoyer dans une enveloppe d’erreur :

Code	Signification
agent_not_found	Agent introuvable, mauvais type, privé, ou organisation invalide
thread_not_found	thread_id fourni introuvable pour cet agent
infected_file	Fichier rejeté par l’antivirus
antivirus_unavailable	Service antivirus indisponible
agent_unavailable	Agent temporairement indisponible (file de traitement)
agent_timeout	Timeout de la réponse agent
extraction_failed	Échec du traitement (extraction ou réponse knowledge)
classification_failed	Échec du traitement de classification
invalid_request	Requête invalide (validation du body ou de l’URL)
internal_error	Erreur interne inattendue
unsupported_file_type	Type de fichier non supporté
file_too_large	Fichier dépassant la taille maximale autorisée
document_already_exists	Document déjà existant
document_not_found	Document introuvable
quota_exceeded	Quota d’utilisation dépassé
invalid_agent_type	Type d’agent invalide pour cet endpoint
invalid_config	Configuration d’agent invalide
webhook_not_found	Aucun webhook configuré pour cet événement
organization_not_found	Organisation introuvable
unauthorized	Authentification manquante ou invalide
invalid_client	Identifiants client invalides (/v2/token)
forbidden	Accès API désactivé pour l’organisation

Astuce

Pilotez votre logique d’erreur sur code, jamais sur error (message humain, sujet à évoluer) ni sur le status HTTP seul — plusieurs codes peuvent partager le même status (ex. agent_not_found et thread_not_found sont tous deux en 404).

Support et assistance

Pour toute question sur cette migration, contactez notre équipe de support à l’adresse contact@dimarc.fr