Referência da API

URL base: https://api.hotdoc.io. Os corpos de requisição e resposta são JSON; os nomes dos campos estão em camelCase. Exceções: POST /v1/jobs/upload (resposta) e o corpo da requisição do webhook — ambos usam snake_case.

Endpoints de processamento

POST /v1/jobs — criar um job

Corpo da requisição:

neural e ocr são sempre obrigatórios, mesmo quando prompts está vazio. Com prompts vazio, o modelo não é chamado: cada arquivo é marcado como JOB_LLM_STATUS_SKIPPED com skipReason=no_prompt e, em caso de OCR bem-sucedido, o job termina como JOB_STATUS_COMPLETE.

A resposta é o job criado com status JOB_STATUS_NEW; responseSchema é ecoado nesse objeto (vazio se não foi definido); consensus é ecoado como um objeto preenchido — mode: "CONSENSUS_MODE_UNSPECIFIED" quando não foi definido, nunca como um campo omitido ou nulo.

Configuração de OCR

ocr seleciona o backend de reconhecimento (OCR) por requisição (BYOK):

O Mistral é o backend de OCR típico (mistral-ocr-latest); os demais provedores executam OCR via vision-chat. A chave é armazenada criptografada e excluída junto com o job.

Nota. O modo de extração é um campo de nível superior, extractionMode, e não faz parte de ocr: ele determina se o OCR roda sempre (EXTRACTION_MODE_OCR_ALWAYS) ou é aplicado por arquivo a critério do conversor (EXTRACTION_MODE_HYBRID, o padrão).

Qual modelo usar? Compare inteligência, preço por token e provedores no comparativo de LLM e escolha o modelo ideal.

Opções de mesclagem (merge)

merge é opcional e está desativada por padrão — defina merge.enabled para ativá-la. Os demais campos merge.* são ignorados enquanto enabled for false/omitido.

Veja “Mesclagem de resultados em chunks” na documentação do Job API para o passo a passo completo (escopo, resolução de conflitos, os dois tipos de deduplicação).

Opções de consenso (consensus)

consensus é opcional e está desativado por padrão. Quando definido, consensus.mode precisa ser um valor reconhecido e o job precisa ter responseSchema definido — um job com consensus.mode definido mas sem responseSchema é rejeitado com 400 na criação.

Veja “Execuções de consenso” na documentação do Job API para o passo a passo completo (modos, como ler minAgreement/disagreements, ressalvas honestas).

Idempotência

Envie idempotencyKey para tornar POST /v1/jobs seguro para repetição. Uma repetição com a mesma chave e parâmetros de requisição idênticos retorna o job original (nenhum duplicado é criado). A mesma chave com parâmetros diferentes é rejeitada com 400 "idempotency key reused with different request parameters". A chave tem no máximo 255 caracteres; gere um novo UUID por criação lógica.

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

Retorna { "result": { "job": …, "ocr": [...], "llm": [...] } }. Exemplo (abreviado):

{
  "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 na resposta não inclui apiKey; o objeto Job não tem campo ocr — a chave de OCR nunca é retornada. ocr[].content é o texto reconhecido no formato ocr[].outputFormat; o formato depende do tipo do arquivo: PDF e HTML → html, .xml → xml, .txt → plain, todo o resto (incluindo imagens e arquivos de office) → markdown. llm[].content é o texto da resposta do modelo exatamente como está (seu prompt determina a estrutura; não há validação no lado do servidor, a menos que o job tenha definido responseSchema — nesse caso, llm[].schemaValid/schemaErrors reportam a conformidade). No exemplo acima, campos vazios/zerados ("", {}, 0) são exibidos por completude — o protojson os omite, então eles podem estar ausentes em uma resposta real.

Campos de ocr[]:

Campos de llm[]:

Campos de llm[].consensus (presentes apenas se o job definiu consensus.mode; em jobs com consenso, linhas ignoradas/com falha ainda carregam consensus: null):

Campos de merged[] (presentes apenas se o job definiu merge.enabled):

Nota. Uma descrição legível por máquina da API de Jobs no formato OpenAPI 3.0.3 está publicada em /openapi.yaml. Ela é gerada a partir das definições protobuf do serviço, portanto não diverge da API; esta página continua sendo a referência em prosa. Você pode passar o arquivo para qualquer gerador de clientes compatível com OpenAPI.

POST /v1/jobs/upload — enviar um arquivo

Um endpoint HTTP autônomo (não é grpc-gateway). Aceita um arquivo via multipart/form-data.

Resposta (snake_case — uma exceção ao camelCase geral):

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

Use a url retornada em sourceUrls ao criar um job.

O corpo de erro deste endpoint é {"code": <int>, "message": "…"}, sem o array details. O limite de tamanho do arquivo é definido pela config (grpc.maxRecvMsgBytes; 20 MiB no deployment atual), e não por um padrão de código.

Versionamento

O caminho /v1 é estável. Mudanças incompatíveis com versões anteriores são lançadas sob um novo caminho (/v2). Mudanças aditivas (novos campos opcionais e endpoints) não quebram a compatibilidade e são anunciadas no Changelog.