API-Referenz

Basis-URL: https://api.hotdoc.io. Anfrage- und Antwort-Bodies sind JSON; Feldnamen sind in camelCase. Ausnahmen: POST /v1/jobs/upload (Antwort) und der Webhook-Anfrage-Body — beide verwenden snake_case.

Verarbeitungs-Endpunkte

POST /v1/jobs — Job erstellen

Anfrage-Body:

neural und ocr sind immer erforderlich, auch wenn prompts leer ist. Bei leerem prompts wird das Modell nicht aufgerufen: Jede Datei wird mit JOB_LLM_STATUS_SKIPPED und skipReason=no_prompt markiert, und bei erfolgreicher OCR endet der Job als JOB_STATUS_COMPLETE.

Die Antwort ist der erstellte Job im Status JOB_STATUS_NEW; responseSchema wird auf diesem Objekt zurückgespiegelt (leer, falls nicht gesetzt); consensus wird als befülltes Objekt zurückgegeben — mode: "CONSENSUS_MODE_UNSPECIFIED", falls nicht gesetzt, niemals als fehlendes oder null-Feld.

OCR-Konfiguration

ocr wählt das Erkennungs-Backend (OCR) pro Anfrage (BYOK):

Mistral ist das typische OCR-Backend (mistral-ocr-latest); andere Provider führen Vision-Chat-OCR aus. Der Schlüssel wird verschlüsselt gespeichert und zusammen mit dem Job gelöscht.

Hinweis. Der Extraktionsmodus ist ein Feld auf oberster Ebene, extractionMode, nicht Teil von ocr: Es bestimmt, ob OCR immer läuft (EXTRACTION_MODE_OCR_ALWAYS) oder je Datei nach Ermessen des Konverters angewendet wird (EXTRACTION_MODE_HYBRID, der Standard).

Welches Modell verwenden? Vergleichen Sie Intelligenz, Preis pro Token und Anbieter im LLM-Vergleich und wählen Sie das passende Modell.

Merge-Optionen (merge)

merge ist optional und standardmäßig deaktiviert — setzen Sie merge.enabled, um es zu aktivieren. Solange enabled false/nicht gesetzt ist, werden alle übrigen merge.*-Felder ignoriert.

Den vollständigen Durchgang (Umfang, Konfliktbehandlung, die zwei Arten der Deduplizierung) finden Sie unter „Zusammenführen von Chunk-Ergebnissen” in der Job-API-Dokumentation.

Konsens-Optionen (consensus)

consensus ist optional und standardmäßig deaktiviert. Ist es gesetzt, muss consensus.mode ein erkannter Wert sein und der Job muss responseSchema gesetzt haben — ein Job mit gesetztem consensus.mode, aber ohne responseSchema, wird bei der Erstellung mit 400 abgelehnt.

Den vollständigen Durchgang (Modi, Lesen von minAgreement/disagreements, ehrliche Einschränkungen) finden Sie unter „Konsens-Durchläufe” in der Job-API-Dokumentation.

Idempotenz

Senden Sie idempotencyKey, um POST /v1/jobs sicher wiederholbar zu machen. Eine Wiederholung mit demselben Schlüssel und identischen Anfrageparametern gibt den ursprünglichen Job zurück (es wird kein Duplikat erstellt). Derselbe Schlüssel mit anderen Parametern wird mit 400 "idempotency key reused with different request parameters" abgelehnt. Der Schlüssel ist maximal 255 Zeichen lang; generieren Sie eine frische UUID pro logischer Erstellung.

GET /v1/jobs/{id}/result — Ergebnis

Gibt { "result": { "job": …, "ocr": [...], "llm": [...] } } zurück. Beispiel (gekürzt):

{
  "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 in der Antwort enthält kein apiKey; das Job-Objekt hat kein ocr-Feld — der OCR-Schlüssel wird niemals zurückgegeben. ocr[].content ist der erkannte Text im Format ocr[].outputFormat; das Format hängt vom Dateityp ab: PDF und HTML → html, .xml → xml, .txt → plain, alles andere (einschließlich Bildern und Office-Dateien) → markdown. llm[].content ist der Antworttext des Modells unverändert (Ihr Prompt bestimmt die Struktur; es gibt keine serverseitige Validierung, es sei denn, der Job hat responseSchema gesetzt — dann melden llm[].schemaValid/schemaErrors die Konformität). Im obigen Beispiel werden leere/Null-Felder ("", {}, 0) der Vollständigkeit halber gezeigt — protojson lässt sie weg, sodass sie in einer echten Antwort fehlen können.

ocr[]-Felder:

llm[]-Felder:

llm[].consensus-Felder (nur vorhanden, wenn der Job consensus.mode gesetzt hat; bei Konsens-Jobs tragen übersprungene/fehlgeschlagene Zeilen weiterhin consensus: null):

merged[]-Felder (nur vorhanden, wenn der Job merge.enabled gesetzt hat):

Hinweis. Eine maschinenlesbare OpenAPI-3.0.3-Beschreibung der Jobs-API ist unter /openapi.yaml veröffentlicht. Sie wird aus den Protobuf-Definitionen des Dienstes generiert und weicht daher nicht von der API ab; diese Seite bleibt die ausformulierte Referenz. Übergeben Sie die Datei einem beliebigen OpenAPI-fähigen Client-Generator.

POST /v1/jobs/upload — Datei hochladen

Ein eigenständiger HTTP-Endpunkt (kein grpc-gateway). Nimmt eine Datei über multipart/form-data entgegen.

Antwort (snake_case — eine Ausnahme zum allgemeinen camelCase):

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

Verwenden Sie die zurückgegebene url beim Erstellen eines Jobs in sourceUrls.

Der Fehler-Body dieses Endpunkts ist {"code": <int>, "message": "…"}, ohne details-Array. Das Dateigrößenlimit wird per Konfiguration gesetzt (grpc.maxRecvMsgBytes; 20 MiB im aktuellen Deployment), nicht durch einen Code-Standardwert.

Versionierung

Der /v1-Pfad ist stabil. Rückwärtsinkompatible Änderungen erscheinen unter einem neuen Pfad (/v2). Additive Änderungen (neue optionale Felder und Endpunkte) brechen die Kompatibilität nicht und werden im Changelog angekündigt.