Référence API

URL de base : https://api.hotdoc.io. Les corps de requête et de réponse sont en JSON ; les noms de champs sont en camelCase. Exceptions : POST /v1/jobs/upload (réponse) et le corps de la requête webhook — tous deux utilisent snake_case.

Endpoints de traitement

POST /v1/jobs — créer un job

Corps de la requête :

neural et ocr sont toujours requis, même lorsque prompts est vide. Avec un prompts vide, le modèle n’est pas appelé : chaque fichier est marqué JOB_LLM_STATUS_SKIPPED avec skipReason=no_prompt, et en cas d’OCR réussi le job se termine avec le statut JOB_STATUS_COMPLETE.

La réponse est le job créé au statut JOB_STATUS_NEW ; responseSchema est renvoyé dans cet objet (vide si non défini) ; consensus est renvoyé comme un objet peuplé — mode: "CONSENSUS_MODE_UNSPECIFIED" si non défini, jamais comme un champ omis ou null.

Configuration OCR

ocr sélectionne le backend de reconnaissance (OCR) par requête (BYOK) :

Mistral est le backend OCR typique (mistral-ocr-latest) ; les autres fournisseurs exécutent un OCR de type vision-chat. La clé est stockée chiffrée et supprimée avec le job.

Remarque. Le mode d’extraction est un champ de premier niveau, extractionMode, il ne fait pas partie de ocr : il détermine si l’OCR s’exécute toujours (EXTRACTION_MODE_OCR_ALWAYS) ou est appliqué par fichier à la discrétion du convertisseur (EXTRACTION_MODE_HYBRID, la valeur par défaut).

Quel modèle utiliser ? Comparez l’intelligence, le prix par token et les fournisseurs dans le comparatif LLM, puis choisissez le modèle adapté.

Options de fusion (merge)

merge est facultatif et désactivé par défaut — définissez merge.enabled pour l’activer. Tous les autres champs merge.* sont ignorés tant que enabled vaut false/est omis.

Voir « Fusion des résultats en chunks » dans la documentation du Job API pour le parcours complet (portée, résolution des conflits, les deux types de déduplication).

Options de consensus (consensus)

consensus est facultatif et désactivé par défaut. Lorsqu’il est défini, consensus.mode doit être une valeur reconnue et le job doit définir responseSchema — un job avec consensus.mode défini mais sans responseSchema est rejeté avec 400 à la création.

Voir « Exécutions de consensus » dans la documentation du Job API pour le parcours complet (modes, lecture de minAgreement/disagreements, limites honnêtement énoncées).

Idempotence

Envoyez idempotencyKey pour rendre POST /v1/jobs sûr à réessayer. Un nouvel envoi avec la même clé et des paramètres de requête identiques renvoie le job d’origine (aucun doublon n’est créé). La même clé avec des paramètres différents est rejetée avec 400 "idempotency key reused with different request parameters". La clé fait au plus 255 caractères ; générez un UUID frais par création logique.

GET /v1/jobs/{id}/result — résultat

Renvoie { "result": { "job": …, "ocr": [...], "llm": [...] } }. Exemple (abrégé) :

{
  "result": {
    "job": {
      "id": "15b07304-…", "accountId": "…", "title": "Invoice #42",
      "metadata": {}, "status": "JOB_STATUS_COMPLETE", "error": "",
      "sourceUrls": ["https://example.com/invoice.pdf"],
      "files": ["https://…/files/15b07304-…/invoice.pdf"],
      "prompts": ["…"], "neural": { "type": "NEURAL_CLIENT_TYPE_XIAOMI", "model": "mimo-v2-flash", "chunkBudgetTokens": 240000 },
      "created": "2026-06-17T16:57:49Z", "updated": "2026-06-17T16:58:05Z"
    },
    "ocr": [
      { "jobId": "15b07304-…", "file": "https://…/invoice.pdf",
        "status": "JOB_OCR_STATUS_DONE", "content": "<p><b>…</b></p>",
        "outputFormat": "html", "model": "pdf_fitz", "error": "", "duration": "149508116",
        "created": "…", "updated": "…" }
    ],
    "llm": [
      { "jobId": "15b07304-…", "file": "https://…/invoice.pdf",
        "promptIndex": 0, "chunkIndex": 0, "chunkTotal": 1,
        "status": "JOB_LLM_STATUS_DONE", "skipReason": "",
        "model": "mimo-v2-flash", "content": "{\"total\": 15000}",
        "error": "", "duration": "601925111", "created": "…", "updated": "…" }
    ]
  }
}

neural dans la réponse n’inclut pas apiKey ; l’objet Job n’a pas de champ ocr — la clé OCR n’est jamais renvoyée. ocr[].content est le texte reconnu au format ocr[].outputFormat ; le format dépend du type de fichier : PDF et HTML → html, .xml → xml, .txt → plain, tout le reste (y compris les images et les fichiers bureautiques) → markdown. llm[].content est le texte de la réponse du modèle tel quel (votre prompt en détermine la structure ; il n’y a aucune validation côté serveur, sauf si le job a défini responseSchema — auquel cas llm[].schemaValid/schemaErrors rapportent la conformité). Dans l’exemple ci-dessus, les champs vides/à zéro ("", {}, 0) sont affichés par souci d’exhaustivité — protojson les omet, ils peuvent donc être absents d’une réponse réelle.

Champs ocr[] :

Champs llm[] :

Champs llm[].consensus (présents uniquement si le job a défini consensus.mode ; sur les jobs avec consensus, les lignes ignorées/en échec portent tout de même consensus: null) :

Champs merged[] (présents uniquement si le job a défini merge.enabled) :

Remarque. Une description lisible par machine de l’API Jobs au format OpenAPI 3.0.3 est publiée à l’adresse /openapi.yaml. Elle est générée à partir des définitions protobuf du service et ne diverge donc pas de l’API ; cette page reste la référence rédigée. Vous pouvez fournir ce fichier à n’importe quel générateur de clients compatible OpenAPI.

POST /v1/jobs/upload — envoi de fichier

Un endpoint HTTP autonome (pas grpc-gateway). Accepte un fichier via multipart/form-data.

Réponse (snake_case — une exception au camelCase général) :

{"url": "https://…/files/…/document.pdf", "name": "document.pdf", "size_bytes": 204800}

Utilisez l’url renvoyée dans sourceUrls lors de la création d’un job.

Le corps d’erreur de cet endpoint est {"code": <int>, "message": "…"}, sans tableau details. La limite de taille du fichier est définie par la configuration (grpc.maxRecvMsgBytes ; 20 MiB dans le déploiement actuel), et non par une valeur par défaut du code.

Versionnage

Le chemin /v1 est stable. Les changements incompatibles sont livrés sous un nouveau chemin (/v2). Les changements additifs (nouveaux champs et endpoints facultatifs) ne rompent pas la compatibilité et sont annoncés dans le Changelog.