API reference

Base URL: https://api.hotdoc.io. Request and response bodies are JSON; field names are in camelCase. Exceptions: POST /v1/jobs/upload (response) and the webhook request body — both use snake_case.

Processing endpoints

POST /v1/jobs — create a job

Request body:

neural and ocr are always required, even when prompts is empty. With an empty prompts, the model isn’t called: each file is marked JOB_LLM_STATUS_SKIPPED with skipReason=no_prompt, and on successful OCR the job finishes as JOB_STATUS_COMPLETE.

The response is the created job in status JOB_STATUS_NEW; responseSchema is echoed back on it (empty if none was set); consensus is echoed back as a populated object — mode: "CONSENSUS_MODE_UNSPECIFIED" when none was set, never an omitted or null field.

OCR configuration

ocr selects the recognition (OCR) backend per request (BYOK):

Mistral is the typical OCR backend (mistral-ocr-latest); other providers run vision-chat OCR. The key is stored encrypted and deleted with the job.

Note. Extraction mode is a top-level extractionMode field, not part of ocr — it controls whether OCR runs at all (EXTRACTION_MODE_OCR_ALWAYS) or is applied per file at the converter’s discretion (EXTRACTION_MODE_HYBRID, the default).

Which model should you use? Compare intelligence, per-token price and providers side by side in the LLM comparison, then set the model accordingly.

Merge options (merge)

merge is optional and off by default — set merge.enabled to opt in. All other merge.* fields are ignored while enabled is false/omitted.

See “Merging chunked results” in the Job API docs for the full walkthrough (scope, conflict resolution, the two kinds of dedup).

Consensus options (consensus)

consensus is optional and off by default. When set, consensus.mode must be a recognized value and the job must set responseSchema — a job with consensus.mode set but no responseSchema is rejected with 400 at creation.

See “Consensus runs” in the Job API docs for the full walkthrough (modes, reading minAgreement/disagreements, honest caveats).

Idempotency

Send idempotencyKey to make POST /v1/jobs safe to retry. A replay with the same key and identical request parameters returns the original job (no duplicate is created). The same key with different parameters is rejected with 400 "idempotency key reused with different request parameters". The key is at most 255 characters; generate a fresh UUID per logical create.

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

Returns { "result": { "job": …, "ocr": [...], "llm": [...] } }. Example (abridged):

{
  "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 the response doesn’t include apiKey; the Job object has no ocr field — the OCR key is never returned. ocr[].content is the recognized text in the ocr[].outputFormat format; the format depends on the file type: PDF and HTML → html, .xml → xml, .txt → plain, everything else (including images and office files) → markdown. llm[].content is the model’s answer text as-is (your prompt determines the structure; there’s no server-side validation unless the job set responseSchema, in which case llm[].schemaValid/schemaErrors report conformance). In the example above, empty/zero fields ("", {}, 0) are shown for completeness — protojson omits them, so they may be absent from a real response.

ocr[] fields:

llm[] fields:

llm[].consensus fields (present only when the job set consensus.mode; on consensus jobs, skipped/failed rows still carry consensus: null):

merged[] fields (present only when the job set merge.enabled):

Note. A machine-readable OpenAPI 3.0.3 description of the Jobs API is published at /openapi.yaml. It is generated from the service’s protobuf definitions, so it does not drift from the API; this page stays the prose reference. Feed the file to any OpenAPI-compatible client generator.

POST /v1/jobs/upload — upload a file

A standalone HTTP endpoint (not grpc-gateway). Accepts a file via multipart/form-data.

Response (snake_case — an exception to the general camelCase):

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

Use the returned url in sourceUrls when creating a job.

This endpoint’s error body is {"code": <int>, "message": "…"}, with no details array. The file size limit is set by config (grpc.maxRecvMsgBytes; 20 MiB in the current deployment), not a code default.

Versioning

The /v1 path is stable. Backward-incompatible changes ship under a new path (/v2). Additive changes (new optional fields and endpoints) don’t break compatibility and are announced in the Changelog.