Archivos

Dos rutas leen archivos con un mismo analizador, las mismas opciones y el mismo resultado:

Ruta	Hace	Tamaño
`POST /namespaces/:namespace/files`	Almacena el archivo como un documento en el que buscar; una búsqueda dice qué página, diapositiva o filas responden	Hasta 512 MiB y 5.000 páginas
`POST /parse`	Devuelve el archivo como Markdown; no almacena nada	Hasta 20 MiB

Los escaneos y las imágenes se leen por OCR, tengan las páginas que tengan. Formatos compatibles: Tipos de archivo.

Subir un archivo

POST /namespaces/:namespace/files Envía los bytes del archivo como cuerpo, como la parte de archivo de un formulario multipart o como JSON {"url": "https://..."} para que Conare lo descargue.

curl "https://api.conare.ai/namespaces/reports/files?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -F file=@report.pdf

curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'

import { readFile } from "node:fs/promises";

const reports = conare.namespace("reports");
const file = await reports.uploadFile(await readFile("report.pdf"), "report.pdf", {
  metadata: { site: "north-pit" },
});

Response

{
  "file_id": "report.pdf",
  "name": "report.pdf",
  "type": "pdf",
  "state": "ready",
  "source_id": "src_01139ca8ca59f2556f65b60e",
  "uploaded_at": 1792618822534,
  "pages": 2,
  "ids": ["src_01139ca8ca59f2556f65b60e:report.pdf"],
  "ocr_failed": [],
  "ocr_pending": [],
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}

La respuesta espera hasta wait segundos a que se lea el archivo: 200 cuando está ready o failed, y si no 202 mientras se lee.

Opciones

Parámetros de consulta, en ambas rutas salvo que se indique lo contrario.

Opción	Tipo	Qué hace
`name`	string	El nombre del archivo, hasta 4.096 caracteres; su extensión distingue `.csv`, `.tsv` y `.md` del texto
`id`	string	Solo en la subida. El id del archivo, el final del id de su documento; por defecto es `name` con los demás caracteres sustituidos por `-`
`type`	string	`pdf`, `docx`, `pptx`, `xlsx`, `csv`, `png`, … (todos); si no, se deduce de los bytes y luego del nombre
`user`	string	Solo en la subida. A quién pertenece el archivo; eliminar el usuario lo elimina
`metadata`	string	Solo en la subida. Un objeto JSON copiado en los metadatos del documento
`pages`	string	Páginas, diapositivas o fotogramas que leer, como `1-20,25` o `5-`
`password`	string	Abre un archivo PDF, Word, PowerPoint o Excel protegido, de hasta 20 MiB
`layout`	boolean, predeterminado `false`	Cada parte leída por OCR incluye también `blocks`: las regiones de su página (campos)
`wait`	segundos, predeterminado 60	Cuánto esperar a la lectura antes de `202`, hasta 300; `0` responde de inmediato

Un Content-Type como application/pdf también declara el tipo.
wait: true equivale a 60; la respuesta siempre llega en 105 segundos como máximo. En las subidas, false responde en cuanto se almacena el texto, con ocr_pending.
Una página fuera de pages no se lee ni pasa por OCR; pages en un archivo sin páginas da 400.

Esquema completo: Upload a file.

Respuesta

Campo	Significado
`file_id`, `name`, `type`	El id usado, el nombre y el tipo leído (`image` para cualquier formato de imagen)
`state`	`queued`, `parsing`, `ocr` (el OCR aún lee `ocr_pending`), `ready` o `failed` con `error`
`source_id`	La fuente de archivos del namespace; el id del documento empieza por ella
`ids`	El único documento del archivo, `["<source_id>:<file_id>"]`, una vez `ready`
`uploaded_at`	Milisegundos Unix
`result`	`unchanged` cuando ya se subió el mismo archivo con el mismo nombre, metadatos y opciones; no se vuelve a leer nada
`pages`	Las páginas de un PDF o los fotogramas de una imagen
`ocr_failed`	Páginas que el OCR no pudo leer tras varios intentos; vuelve a subir el archivo para reintentarlas
`markdown`, `parts`, `without_text`	El resultado

images_without_text, pages_without_text, pages_ocr, images_ocr, sheets, slides y slides_without_text están obsoletos: parts y without_text dicen lo mismo.

Consultar un archivo

GET /namespaces/:namespace/files/:id Devuelve la última subida del archivo, con los mismos campos; consúltalo periódicamente tras un 202.

curl https://api.conare.ai/namespaces/reports/files/report.pdf \
  -H "Authorization: Bearer $CONARE_API_KEY"

const file = await reports.getFile("report.pdf");

Opción	Tipo	Qué hace
`user`	string	El usuario, para un archivo subido con `user`

Esquema completo: Read a file.

Documentos almacenados

Un archivo es un documento, <source_id>:<file_id>; sus páginas, diapositivas, filas de hoja, secciones e imágenes son sus partes.

Dónde	Qué obtienes
Búsqueda	Una página de un PDF o de una imagen, una diapositiva o un rango de filas de una hoja es un resultado propio, id `<source_id>:<file_id>$<part>`: `$page-3`, `$slide-4`, `$<sheet>-1`
Búsqueda en un archivo de texto, Markdown o Word	Un resultado, el archivo `<source_id>:<file_id>`, con sus pasajes de cualquier parte de él
Los `metadata` de un resultado	Dónde está su parte, o su primer pasaje, con las claves de abajo
`GET /namespaces/:namespace/documents/:id`	Con el id del archivo, el texto del archivo entero, con una línea en blanco entre páginas; con el id de una parte, solo esa parte

Dónde está una parte

Archivo	Ubicación en los metadatos
PDF	`page`
Word, texto, Markdown	`part`, `heading`, y `lines` para texto
PowerPoint	`slide`
Excel, CSV, TSV	`sheet`, `rows`
Imagen	`page`, y `frame`
Una imagen en Word	`image`, `heading`
Una imagen en una diapositiva	`slide`, `image`
Un gráfico en una hoja	`sheet`

El documento tiene además file, file_id, file_type, uploaded_at, los metadata de la subida, y ocr: true cuando lo leyó el OCR. Un archivo subido antes puede seguir siendo un documento por parte, como <source_id>:<file_id>:page-1, hasta que se vuelva a subir.

Para	Haz
Reemplazar un archivo	Vuelve a subirlo con el mismo id
Reintentar sin riesgo	El mismo archivo, nombre, metadatos y opciones responde `unchanged`, sin necesidad de `Idempotency-Key`
Buscar en un archivo	Filtra por `{ "file_id": "report.pdf" }`
Buscar en una página	Filtra por `{ "file_id": "report.pdf", "page": 3 }`
Separar usuarios	Sube con `user`, busca con `user`
Eliminar el original	Se conserva hasta que se elimina el namespace o su usuario

Analizar un archivo

POST /parse Devuelve el archivo como Markdown y no almacena nada; cualquier clave puede analizar, también una clave Models only.

curl "https://api.conare.ai/parse?name=report.pdf" \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

curl https://api.conare.ai/parse \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'

import { readFile } from "node:fs/promises";

const out = await conare.parse(await readFile("report.pdf"), { name: "report.pdf" });
if (out.state === "parsing") console.log(await conare.getParse(out.id));

Response

{
  "id": "prs_76149e8db2be257fa8a0ac01",
  "state": "done",
  "type": "pdf",
  "name": "report.pdf",
  "pages": 2,
  "markdown": "<!-- page 1 -->\n\n# Q3 report\n\nRevenue grew 12 percent in EMEA.\n\n<!-- page 2 -->\n\n# Outlook\n\nWe expect Q4 revenue to grow again.",
  "parts": [
    { "locator": { "page": 1 }, "markdown": "# Q3 report\n\nRevenue grew 12 percent in EMEA.", "ocr": true, "confidence": null },
    { "locator": { "page": 2 }, "markdown": "# Outlook\n\nWe expect Q4 revenue to grow again.", "ocr": true, "confidence": null }
  ],
  "without_text": { "pages": [], "slides": [], "images": [] }
}

Opción	Tipo	Qué hace
`url`	string	En un cuerpo JSON: una URL `https` en una dirección pública, descargada en 60 segundos como máximo, de hasta 20 MiB
`name`, `type`, `pages`, `password`, `layout`, `wait`		Como en la subida

El cuerpo admite hasta 20 MiB, y el OCR lee hasta 100 páginas; las páginas posteriores conservan su capa de texto.
Para analizar un archivo JSON, envíalo como text/plain.

Esquema completo: Parse a file.

Obtener un análisis

GET /parse/:id Un análisis que respondió 202 (state: "parsing") se conserva 24 horas: consúltalo hasta que state sea done, o failed con su error.

curl

curl https://api.conare.ai/parse/prs_0e631c59528ac4f7424dc776 \
  -H "Authorization: Bearer $CONARE_API_KEY"

Esquema completo: Read a parse.

Resultado

Campo	Significado
`markdown`	El archivo completo; cada página, diapositiva y hoja empieza con `<!-- page 3 -->`, `<!-- slide 4 -->` o `<!-- sheet "Q3" -->`
`parts`	En orden de lectura, cada una con su `locator`, `markdown`, `ocr` y `confidence`
`parts[].locator`	`{"page": 3}`, `{"slide": 4, "image": 1}`, `{"sheet": "Q3", "rows": "2-41"}` o `{"part": 2, "heading": "..."}`
`parts[].ocr`	Leída por OCR a partir de la imagen de la página, no de su capa de texto
`parts[].confidence`	La certeza del OCR, de 0 a 1; `null` cuando el OCR no dio ninguna (la mayoría de las páginas nativas digitales)
`without_text`	`pages`, `slides` e `images` que no contienen texto, cada imagen con su `reason`

Las reglas del Markdown están en Tipos de archivo.

Errores

Error	Cuándo
`400 invalid_request`	Una opción no es válida: `pages` en un archivo sin páginas, `wait` mayor que 300, `metadata` que no es un objeto JSON, una URL que no es `https` en una dirección pública
`400 fetch_failed`	La URL no respondió `200` con el archivo
`404 parse_not_found`	Ningún análisis con ese id respondió `202` en las últimas 24 horas
`409 file_replaced`	El archivo se eliminó mientras la respuesta esperaba
`409 user_purging`	El usuario se está eliminando
`413 payload_too_large`	Más de 512 MiB (subida) o 20 MiB (análisis, o con `password`)
`415 unsupported_file`	No es un tipo compatible, o no es el `type` declarado; el mensaje indica en qué formato guardarlo
`422 password_protected`	El archivo tiene contraseña: envíala como `password`
`422 unreadable_file`	El archivo está dañado
`422 no_text`	Ninguna página, hoja, diapositiva, párrafo o imagen contiene texto
`503 files_unavailable`	Ahora mismo no se pueden almacenar archivos; reinténtalo más tarde

Un archivo de más de 5.000 páginas, hojas o diapositivas termina en failed con too_large.

Primeros pasos

Esenciales

Sincronización

Modelos

Herramientas

Archivos

Subir un archivo

Opciones

Respuesta

Consultar un archivo

Documentos almacenados

Dónde está una parte

Analizar un archivo

Obtener un análisis

Resultado

Errores

​Subir un archivo

​Opciones

​Respuesta

​Consultar un archivo

​Documentos almacenados

​Dónde está una parte

​Analizar un archivo

​Obtener un análisis

​Resultado

​Errores

Subir un archivo

Opciones

Respuesta

Consultar un archivo

Documentos almacenados

Dónde está una parte

Analizar un archivo

Obtener un análisis

Resultado

Errores