> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`.
> The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown.
> Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1.
> Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples.
> Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt.

# Archivos

> Sube un archivo PDF, Word, PowerPoint, Excel, CSV, de texto o de imagen como un documento en el que buscar, o analízalo a Markdown sin almacenar nada.

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

| Ruta | Hace | Tamaño |
| - | - | - |
| [`POST /namespaces/:namespace/files`](#subir-un-archivo) | 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`](#analizar-un-archivo) | 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](https://docs.conare.ai/es/file-types.md).

## 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.

```bash curl theme={null}
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
```

```bash curl (form) theme={null}
curl https://api.conare.ai/namespaces/reports/files \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -F file=@report.pdf
```

```bash curl (URL) theme={null}
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"}'
```

```ts TypeScript theme={null}
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" },
});
```

```json Response theme={null}
{
  "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](https://docs.conare.ai/es/file-types.md)); 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](https://docs.conare.ai/es/file-types.md#bloques-de-diseño)) |
| `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](https://docs.conare.ai/es/api-reference/files/upload-a-file.md).

### 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](#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`.

```bash curl theme={null}
curl https://api.conare.ai/namespaces/reports/files/report.pdf \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

```ts TypeScript theme={null}
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](https://docs.conare.ai/es/api-reference/files/read-a-file.md).

## 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](https://docs.conare.ai/es/query.md) | 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`](https://docs.conare.ai/es/documents#obtener-un-documento) | 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](https://docs.conare.ai/es/filters.md) por `{ "file_id": "report.pdf" }` |
| Buscar en una página | Filtra por `{ "file_id": "report.pdf", "page": 3 }` |
| Separar usuarios | Sube con `user`, [busca](https://docs.conare.ai/es/query.md) 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.

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

```bash curl (URL) theme={null}
curl https://api.conare.ai/parse \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/report.pdf"}'
```

```ts TypeScript theme={null}
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));
```

```json Response theme={null}
{
  "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](#opciones) |

* 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](https://docs.conare.ai/es/api-reference/parse/parse-a-file-to-markdown.md).

### 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`.

```bash curl theme={null}
curl https://api.conare.ai/parse/prs_0e631c59528ac4f7424dc776 \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

Esquema completo: [Read a parse](https://docs.conare.ai/es/api-reference/parse/get-a-parse-result.md).

## 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`](https://docs.conare.ai/es/file-types#imágenes-en-word-y-powerpoint) |

Las reglas del Markdown están en [Tipos de archivo](https://docs.conare.ai/es/file-types.md#markdown).

## 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`.


## Related topics

- [Tipos de archivo y Markdown](https://docs.conare.ai/es/file-types.md)
- [Google Cloud Storage](https://docs.conare.ai/es/gcs.md)
- [Descripción general de la API](https://docs.conare.ai/es/api.md)
- [Filtros](https://docs.conare.ai/es/filters.md)
- [Read a file](https://docs.conare.ai/es/api-reference/files/read-a-file.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.