Referencia de la API

URL base: https://api.hotdoc.io. Los cuerpos de las solicitudes y respuestas son JSON; los nombres de campo están en camelCase. Excepciones: POST /v1/jobs/upload (respuesta) y el cuerpo de la solicitud del webhook, que usan snake_case.

Endpoints de procesamiento

POST /v1/jobs — crear una tarea

Cuerpo de la solicitud:

neural y ocr son siempre obligatorios, incluso cuando prompts está vacío. Con prompts vacío, el modelo no se invoca: cada archivo se marca como JOB_LLM_STATUS_SKIPPED con skipReason=no_prompt y, si el OCR es correcto, la tarea termina como JOB_STATUS_COMPLETE.

La respuesta es la tarea creada en estado JOB_STATUS_NEW; responseSchema se devuelve en ese objeto (vacío si no se estableció); consensus se devuelve como un objeto poblado — mode: "CONSENSUS_MODE_UNSPECIFIED" si no se estableció, nunca como un campo omitido o null.

Configuración de OCR

ocr selecciona el backend de reconocimiento (OCR) por solicitud (BYOK):

Mistral es el backend de OCR habitual (mistral-ocr-latest); otros proveedores ejecutan OCR mediante vision-chat. La clave se almacena cifrada y se elimina con la tarea.

Nota. El modo de extracción es un campo de nivel superior, extractionMode, no forma parte de ocr: determina si el OCR se ejecuta siempre (EXTRACTION_MODE_OCR_ALWAYS) o se aplica por archivo a criterio del convertidor (EXTRACTION_MODE_HYBRID, el valor predeterminado).

¿Qué modelo usar? Compare inteligencia, precio por token y proveedores en la comparativa de LLM y elija el modelo adecuado.

Opciones de fusión (merge)

merge es opcional y está desactivada por defecto — active merge.enabled para optar por ella. El resto de campos merge.* se ignoran mientras enabled sea false/se omita.

Consulte «Fusión de resultados fragmentados» en la documentación del Job API para el recorrido completo (alcance, resolución de conflictos, los dos tipos de deduplicación).

Opciones de consenso (consensus)

consensus es opcional y está desactivado por defecto. Cuando se define, consensus.mode debe ser un valor reconocido y la tarea debe tener responseSchema definido — una tarea con consensus.mode definido pero sin responseSchema se rechaza con 400 al crearla.

Consulte «Ejecuciones de consenso» en la documentación del Job API para el recorrido completo (modos, cómo leer minAgreement/disagreements, advertencias honestas).

Idempotencia

Envíe idempotencyKey para hacer que POST /v1/jobs sea seguro de reintentar. Un reintento con la misma clave y parámetros de solicitud idénticos devuelve la tarea original (no se crea ningún duplicado). La misma clave con parámetros diferentes se rechaza con 400 "idempotency key reused with different request parameters". La clave tiene como máximo 255 caracteres; genere un UUID nuevo por cada creación lógica.

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

Devuelve { "result": { "job": …, "ocr": [...], "llm": [...] } }. Ejemplo (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 en la respuesta no incluye apiKey; el objeto Job no tiene campo ocr: la clave de OCR nunca se devuelve. ocr[].content es el texto reconocido en el formato ocr[].outputFormat; el formato depende del tipo de archivo: PDF y HTML → html, .xml → xml, .txt → plain, todo lo demás (incluidas imágenes y archivos de oficina) → markdown. llm[].content es el texto de la respuesta del modelo tal cual (su prompt determina la estructura; no hay validación del lado del servidor, salvo que la tarea haya establecido responseSchema — en ese caso, llm[].schemaValid/schemaErrors informan la conformidad). En el ejemplo anterior se muestran campos vacíos/cero ("", {}, 0) por exhaustividad: protojson los omite, así que pueden estar ausentes en una respuesta real.

Campos de ocr[]:

Campos de llm[]:

Campos de llm[].consensus (presentes solo si la tarea definió consensus.mode; en tareas con consenso, las filas omitidas/fallidas siguen llevando consensus: null):

Campos de merged[] (presentes solo si la tarea definió merge.enabled):

Nota. Una descripción legible por máquina de la API de Jobs en formato OpenAPI 3.0.3 está publicada en /openapi.yaml. Se genera a partir de las definiciones protobuf del servicio, así que no se desvía de la API; esta página sigue siendo la referencia en prosa. Puedes pasarle el archivo a cualquier generador de clientes compatible con OpenAPI.

POST /v1/jobs/upload — subir un archivo

Un endpoint HTTP independiente (no grpc-gateway). Acepta un archivo vía multipart/form-data.

Respuesta (snake_case — una excepción al camelCase general):

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

Use la url devuelta en sourceUrls al crear una tarea.

El cuerpo de error de este endpoint es {"code": <int>, "message": "…"}, sin array details. El límite de tamaño de archivo lo fija la configuración (grpc.maxRecvMsgBytes; 20 MiB en el despliegue actual), no un valor por defecto del código.

Versionado

La ruta /v1 es estable. Los cambios incompatibles hacia atrás se publican bajo una nueva ruta (/v2). Los cambios aditivos (nuevos campos y endpoints opcionales) no rompen la compatibilidad y se anuncian en el Changelog.