Справочник API

Базовый URL: https://api.hotdoc.io. Тела запросов и ответов — JSON, имена полей в camelCase. Исключения: POST /v1/jobs/upload (ответ) и тело вебхук-запроса — snake_case.

Эндпоинты обработки

POST /v1/jobs — создание задачи

Тело запроса:

neural и ocr обязательны всегда, даже если prompts пуст. При пустом prompts модель не вызывается: каждому файлу проставляется JOB_LLM_STATUS_SKIPPED со skipReason=no_prompt, и при успешном OCR задача завершается JOB_STATUS_COMPLETE.

Ответ — созданная задача в статусе JOB_STATUS_NEW; responseSchema возвращается в этом объекте (пусто, если не задавалась); consensus возвращается как заполненный объект — mode: "CONSENSUS_MODE_UNSPECIFIED", если не задавался, а не как отсутствующее или null-поле.

Конфигурация OCR

ocr задаёт бэкенд распознавания (OCR) для каждого запроса (BYOK):

Mistral — типовой OCR-бэкенд (mistral-ocr-latest); остальные провайдеры выполняют vision-chat OCR. Ключ хранится в зашифрованном виде и удаляется вместе с задачей.

Примечание. Режим извлечения — это поле верхнего уровня extractionMode, а не часть ocr: оно определяет, запускается ли OCR вообще (EXTRACTION_MODE_OCR_ALWAYS) или применяется по каждому файлу на усмотрение конвертера (EXTRACTION_MODE_HYBRID, по умолчанию).

Какую модель использовать? Сравните интеллект, цену за токен и провайдеров в сравнении LLM и укажите подходящую модель.

Опции слияния (merge)

merge опционален и по умолчанию выключен — установите merge.enabled, чтобы включить его. Пока enabled равно false/не задано, остальные поля merge.* игнорируются.

Подробный разбор (область слияния, разрешение конфликтов, два вида дедупликации) — в «Слияние результатов по частям» в документации Job API.

Опции консенсуса (consensus)

consensus опционален и по умолчанию выключен. Если он задан, consensus.mode должен быть распознаваемым значением, и в задаче должен быть задан responseSchema — задача с заданным consensus.mode, но без responseSchema, отклоняется с 400 при создании.

Подробный разбор (режимы, чтение minAgreement/disagreements, важные оговорки) — в «Консенсус по нескольким запускам» в документации Job API.

Идемпотентность

Передайте idempotencyKey, чтобы сделать POST /v1/jobs безопасным для повтора. Повторный запрос с тем же ключом и идентичными параметрами вернёт исходную задачу (дубликат не создаётся). Тот же ключ с другими параметрами отклоняется с кодом 400 "idempotency key reused with different request parameters". Ключ — максимум 255 символов; генерируйте новый UUID для каждого логического создания задачи.

GET /v1/jobs/{id}/result — результат

Возвращает { "result": { "job": …, "ocr": [...], "llm": [...] } }. Пример (сокращён):

{
  "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 в ответе не содержит apiKey; объект Job не содержит поля ocr — ключ OCR не возвращается никогда. ocr[].content — это распознанный текст в формате ocr[].outputFormat; формат зависит от типа файла: PDF и HTML → html, .xml → xml, .txt → plain, остальное (включая изображения и офисные файлы) → markdown. llm[].content — текст ответа модели как есть (структуру держит ваш промпт; серверной валидации нет, если задача не задавала responseSchema — тогда соответствие сообщают поля llm[].schemaValid/schemaErrors). В примере выше пустые/нулевые поля ("", {}, 0) показаны для полноты — protojson опускает их, поэтому в реальном ответе они могут отсутствовать.

Поля ocr[]:

Поля llm[]:

Поля llm[].consensus (присутствуют, только если в задаче задан consensus.mode; в задачах с консенсусом пропущенные/сбойные строки всё равно несут consensus: null):

Поля merged[] (присутствуют, только если в задаче задан merge.enabled):

Примечание. Машиночитаемое описание Jobs API в формате OpenAPI 3.0.3 опубликовано по адресу /openapi.yaml. Оно генерируется из protobuf-определений сервиса и потому не расходится с API; эта страница остаётся текстовым справочником. Файл можно передать любому генератору клиентов, понимающему OpenAPI.

POST /v1/jobs/upload — загрузка файла

Отдельный HTTP-эндпоинт (не grpc-gateway). Принимает файл через multipart/form-data.

Ответ (snake_case, исключение из общего camelCase):

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

Используйте полученный url в sourceUrls при создании задачи.

Тело ошибки этого эндпоинта — {"code": <int>, "message": "…"} без массива details. Лимит размера файла задаётся конфигом (grpc.maxRecvMsgBytes; в текущем деплое — 20 MiB), не код-дефолтом.

Версионирование

Путь /v1 стабилен. Обратно несовместимые изменения выходят под новым путём (/v2). Аддитивные изменения (новые опциональные поля и эндпоинты) совместимость не ломают и анонсируются в Changelog.