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.

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.

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

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). 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:

Note. A machine-readable spec (OpenAPI/Swagger) isn’t generated yet; this reference is maintained by hand. OpenAPI is planned as a separate task.

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.