Every request must include your API key. It is a personal server credential, distinct from any user session token, and should be handled with the same care as a database password.

You can send it in two ways, both valid and equivalent:

Option A — Dedicated header (recommended):

x-api-key: <YOUR_API_KEY>

Option B — Standard Authorization header:

Authorization: Bearer <YOUR_API_KEY>

You do not need to send both headers at once; either one is sufficient. If you send both, the x-api-key header takes priority.

What happens if authentication fails

Before processing any file, the system validates:

• That the API key exists and is active.
• That the account associated with that API key is in active status (not suspended).

If any of these checks fail, the request is rejected immediately with status code 401, without processing the attached document.

HTTP method: POST

Content-Type: multipart/form-data (required)

The request must be built as a multipart form (the same type as when uploading a file from an HTML <form> with enctype="multipart/form-data", or when using FormData in JavaScript, multipart/form-data in Python requests, or a Form-Data body in Postman/n8n/Insomnia).

Fields the form must contain

Additional fields with other names for the file are not supported (for example, documento, doc, upload) — the file field name must be exactly file, and the schema identifier field exactly schema_id.

Important schema requirement

The schema_id must correspond to a schema configured specifically for document-to-JSON extraction. If you send the identifier of a schema intended for another conversion direction (for example, Excel to JSON or PDF to JSON), the request will be rejected with a 400 error without processing the file.

Supported file formats

Explicitly NOT supported format: .doc (Word 97-2003, legacy binary format). If you send a file of this type (application/msword, or .doc extension), the request is rejected with 400 and a message asking you to convert it to .docx first.

If the file MIME type does not exactly match the table (some clients send generic types such as application/octet-stream), the system also checks the file name extension as a fallback.

File requirements

• The file cannot be empty (0 bytes).
• Maximum supported size: 10 MB. If you send a larger file, the request is rejected with status code 413 before attempting to process it.
• Extracted document text cannot exceed 300,000 characters. This is a limit independent of the original file size. If exceeded, the request is rejected with 413 after extraction but before calling the AI.
• The document must contain extractable text. An empty document, or one composed only of images without text, will be rejected.

1. Have your API key ready.
2. Have the schema_id of the corresponding schema ready (previously created in your account, of the correct type for this endpoint).
3. Build a POST request to the endpoint URL.
4. Add the authentication header (x-api-key or Authorization: Bearer).
5. Build the body as multipart/form-data with two parts: a file part with field name file, and a text part with field name schema_id containing the UUID as a string.
6. Send the request and wait for the response.
7. Check the HTTP status code before assuming success: only 200 indicates the document was processed correctly.

See the panel on the right for examples in cURL, JavaScript, Node.js, Python, PHP, and n8n.

200 OK · Content-Type: application/json

{
  "success": true,
  "schema_utilizado": "Contratos legales",
  "total_registros": 1,
  "data": [
    {
      "parte_a": "Inmobiliaria Norte S.L.",
      "parte_b": "Carlos Méndez",
      "fecha_firma": "2026-03-01"
    }
  ],
  "agent_data": {
    "clausula_penalizacion": true,
    "tipo_renovacion": "automatica",
    "resumen_contrato": "Arrendamiento con renovación automática y cláusula de penalización por impago."
  }
}

Every error response is JSON, with at least an error field containing a readable message. Some errors also include a detalle field with additional technical information.

{
  "error": "Descripción legible del problema.",
  "detalle": "Información técnica adicional (solo presente en algunos casos)."
}

400 — Invalid request

Specific cases:

• The file field was not sent, or it is not a valid file.
• The schema_id field was not sent.
• The body could not be parsed as multipart/form-data.
• The file is empty (0 bytes).
• The file format is not among the supported ones (.docx, .txt, .md, .rtf).
• A .doc file was sent (legacy Word 97-2003 format) — specific message asking to convert it to .docx.
• The .docx is corrupt or could not be opened as a valid ZIP.
• The .docx does not contain the expected internal structure (word/document.xml).
• No text could be extracted from the document (empty content, or only images).
• The schema indicated in schema_id is not of the correct type for this endpoint.

401 — Unauthorized — API key missing, nonexistent, deactivated, or account not active.

404 — Not found — The schema_id does not exist or does not belong to your API key account.

413 — File or text too large — The file exceeds 10 MB, or extracted text exceeds 300,000 characters.

422 — Unprocessable — Text was extracted successfully but no data related to your schema could be extracted.

502 — Processing service failure — Communication issue with the AI service (transient; retry with backoff).

405 — Method not allowed — HTTP method other than POST.

500 — Internal error — Unexpected server-side problem.

• Validate the HTTP status code before attempting to read data[0] from the response; a 4xx or 5xx error will not have that structure.
• Prefer .docx or .txt over .rtf when you have the option: extraction from the first two formats is more reliable than .rtf.
• If you generate documents yourself from another system, consider exporting directly to .txt or .md when visual layout does not matter.
• Remember that data always contains exactly one element on this endpoint — one per full document, not per page or section.
• Implement automatic retries only for status codes 500 and 502, never for 400, 401, 404, 413, or 422.
• The clearer your schema property descriptions, the better the extraction accuracy.
• Do not include your API key in frontend code or public repositories.