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

# Arquivos

> Envie um arquivo PDF, Word, PowerPoint, Excel, CSV, de texto ou de imagem como um único documento pesquisável, ou converta-o em Markdown sem armazenar nada.

Duas rotas leem arquivos com um único parser, as mesmas opções e o mesmo resultado:

| Rota | Faz | Tamanho |
| - | - | - |
| [`POST /namespaces/:namespace/files`](#enviar-um-arquivo) | Armazena o arquivo como um único documento pesquisável; uma pesquisa diz qual página, slide ou linhas respondem | Até 512 MiB e 5.000 páginas |
| [`POST /parse`](#converter-um-arquivo) | Retorna o arquivo em Markdown; não armazena nada | Até 20 MiB |

Digitalizações e imagens são lidas por OCR, independentemente do número de páginas. Formatos suportados: [Tipos de arquivo](https://docs.conare.ai/pt-BR/file-types.md).

## Enviar um arquivo

`POST /namespaces/:namespace/files`

Envie os bytes do arquivo como corpo, como a parte de arquivo de um formulário multipart, ou como JSON `{"url": "https://..."}` para que o Conare o busque.

```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": [] }
}
```

A resposta aguarda até `wait` segundos pela leitura do arquivo: `200` quando ele está `ready` ou `failed`, caso contrário `202` enquanto é lido.

### Opções

Parâmetros de query, em ambas as rotas, salvo indicação em contrário.

| Opção | Tipo | O que faz |
| - | - | - |
| `name` | string | O nome do arquivo, até 4.096 caracteres; sua extensão distingue `.csv`, `.tsv` e `.md` de texto |
| `id` | string | Apenas upload. O id do arquivo, o final do id do seu documento; o padrão é `name` com outros caracteres substituídos por `-` |
| `type` | string | `pdf`, `docx`, `pptx`, `xlsx`, `csv`, `png`, ... ([todos](https://docs.conare.ai/pt-BR/file-types.md)); caso contrário, detectado pelos bytes e depois pelo nome |
| `user` | string | Apenas upload. A quem o arquivo pertence; excluir o usuário o exclui |
| `metadata` | string | Apenas upload. Um objeto JSON copiado para os metadados do documento |
| `pages` | string | Páginas, slides ou frames a ler, como `1-20,25` ou `5-` |
| `password` | string | Abre um arquivo PDF, Word, PowerPoint ou Excel protegido, até 20 MiB |
| `layout` | boolean, padrão `false` | Cada parte lida por OCR também traz `blocks`: as regiões da sua página ([campos](https://docs.conare.ai/pt-BR/file-types.md#blocos-de-layout)) |
| `wait` | segundos, padrão 60 | Quanto tempo aguardar a leitura antes de `202`, até 300; `0` responde imediatamente |

* Um `Content-Type` como `application/pdf` também declara o tipo.
* `wait`: `true` equivale a 60; a resposta sempre chega em até 105 segundos. Em uploads, `false` responde assim que o texto é armazenado, com `ocr_pending`.
* Uma página fora de `pages` não é lida nem passa por OCR; `pages` em um arquivo sem páginas retorna `400`.

Schema completo: [Enviar um arquivo](https://docs.conare.ai/pt-br/api-reference/files/upload-a-file.md).

### Resposta

| Campo | Significado |
| - | - |
| `file_id`, `name`, `type` | O id usado, o nome e o tipo detectado (`image` para todo formato de imagem) |
| `state` | `queued`, `parsing`, `ocr` (OCR ainda lendo `ocr_pending`), `ready` ou `failed` com `error` |
| `source_id` | A fonte de arquivos do namespace; o id do documento começa com ele |
| `ids` | O único documento do arquivo, `["<source_id>:<file_id>"]`, quando `ready` |
| `uploaded_at` | Milissegundos Unix |
| `result` | `unchanged` quando o mesmo arquivo, nome, metadados e opções já foram enviados; nada é lido de novo |
| `pages` | As páginas de um PDF ou os frames de uma imagem |
| `ocr_failed` | Páginas que o OCR não conseguiu ler após várias tentativas; envie novamente para tentar de novo |
| `markdown`, `parts`, `without_text` | O [resultado](#resultado) |

`images_without_text`, `pages_without_text`, `pages_ocr`, `images_ocr`, `sheets`, `slides` e `slides_without_text` estão obsoletos: `parts` e `without_text` informam o mesmo.

## Verificar um arquivo

`GET /namespaces/:namespace/files/:id`

Retorna o upload mais recente do arquivo, com os mesmos campos; consulte-o após um `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");
```

| Opção | Tipo | O que faz |
| - | - | - |
| `user` | string | O usuário, para um arquivo enviado com `user` |

Schema completo: [Ler um arquivo](https://docs.conare.ai/pt-br/api-reference/files/read-a-file.md).

## Documentos armazenados

Um arquivo é um documento, `<source_id>:<file_id>`; suas páginas, slides, linhas de planilha, seções e imagens são suas partes.

| Onde | O que você recebe |
| - | - |
| [Pesquisa](https://docs.conare.ai/pt-BR/query.md) | Uma página de um PDF ou de uma imagem, um slide ou um intervalo de linhas de uma planilha é um resultado próprio, id `<source_id>:<file_id>$<part>`: `$page-3`, `$slide-4`, `$<sheet>-1` |
| Pesquisa em um arquivo de texto, Markdown ou Word | Um resultado, o arquivo `<source_id>:<file_id>`, com seus trechos de qualquer ponto dele |
| Os `metadata` de um resultado | Onde está sua parte, ou seu primeiro trecho, pelas chaves abaixo |
| [`GET /namespaces/:namespace/documents/:id`](https://docs.conare.ai/pt-BR/documents#obter-um-documento) | Com o id do arquivo, o texto do arquivo inteiro, com uma linha em branco entre as páginas; com o id de uma parte, só essa parte |

### Onde está uma parte

| Arquivo | Localização nos metadados |
| - | - |
| PDF | `page` |
| Word, texto, Markdown | `part`, `heading` e `lines` para texto |
| PowerPoint | `slide` |
| Excel, CSV, TSV | `sheet`, `rows` |
| Imagem | `page` e `frame` |
| Uma imagem no Word | `image`, `heading` |
| Uma imagem em um slide | `slide`, `image` |
| Um gráfico em uma planilha | `sheet` |

O documento também tem `file`, `file_id`, `file_type`, `uploaded_at`, os `metadata` do upload e `ocr: true` quando lido por OCR. Um arquivo enviado antes pode ainda ser um documento por parte, como `<source_id>:<file_id>:page-1`, até ser enviado novamente.

| Para | Faça |
| - | - |
| Substituir um arquivo | Envie-o novamente com o mesmo id |
| Tentar de novo com segurança | O mesmo arquivo, nome, metadados e opções respondem `unchanged`, sem precisar de `Idempotency-Key` |
| Pesquisar um único arquivo | [Filtre](https://docs.conare.ai/pt-BR/filters.md) por `{ "file_id": "report.pdf" }` |
| Pesquisar uma única página | Filtre por `{ "file_id": "report.pdf", "page": 3 }` |
| Manter usuários separados | Envie com `user`, [pesquise](https://docs.conare.ai/pt-BR/query.md) com `user` |
| Excluir o original | Ele é mantido até que o namespace, ou seu usuário, seja excluído |

## Converter um arquivo

`POST /parse`

Retorna o arquivo em Markdown e não armazena nada; qualquer chave pode converter, inclusive uma chave 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": [] }
}
```

| Opção | Tipo | O que faz |
| - | - | - |
| `url` | string | Em um corpo JSON: uma URL `https` em um endereço público, buscada em até 60 segundos, até 20 MiB |
| `name`, `type`, `pages`, `password`, `layout`, `wait` | | Como no [upload](#opções) |

* O corpo tem até 20 MiB, e o OCR lê até 100 páginas; as páginas seguintes mantêm sua camada de texto.
* Para converter um arquivo JSON, envie-o como `text/plain`.

Schema completo: [Converter um arquivo](https://docs.conare.ai/pt-br/api-reference/parse/parse-a-file-to-markdown.md).

### Buscar uma conversão

`GET /parse/:id`

Uma conversão que respondeu `202` (`state: "parsing"`) é mantida por 24 horas: busque-a até que `state` seja `done`, ou `failed` com seu `error`.

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

Schema completo: [Ler uma conversão](https://docs.conare.ai/pt-br/api-reference/parse/get-a-parse-result.md).

## Resultado

| Campo | Significado |
| - | - |
| `markdown` | O arquivo inteiro; cada página, slide e planilha começa com `<!-- page 3 -->`, `<!-- slide 4 -->` ou `<!-- sheet "Q3" -->` |
| `parts` | Em ordem de leitura, cada uma com seu `locator`, `markdown`, `ocr` e `confidence` |
| `parts[].locator` | `{"page": 3}`, `{"slide": 4, "image": 1}`, `{"sheet": "Q3", "rows": "2-41"}` ou `{"part": 2, "heading": "..."}` |
| `parts[].ocr` | Lido por OCR a partir da imagem da página, não da sua camada de texto |
| `parts[].confidence` | A certeza do OCR, de 0 a 1; `null` quando o OCR não informou nenhuma (a maioria das páginas nativamente digitais) |
| `without_text` | `pages`, `slides` e `images` que não contêm texto, cada imagem com seu [`reason`](https://docs.conare.ai/pt-BR/file-types#imagens-no-word-e-no-powerpoint) |

As regras do Markdown estão em [Tipos de arquivo](https://docs.conare.ai/pt-BR/file-types.md#markdown).

## Erros

| Erro | Quando |
| - | - |
| `400 invalid_request` | Uma opção não é válida: `pages` em um arquivo sem páginas, `wait` acima de 300, `metadata` que não é um objeto JSON, uma URL que não é `https` em um endereço público |
| `400 fetch_failed` | A URL não respondeu `200` com o arquivo |
| `404 parse_not_found` | Nenhuma conversão com esse id respondeu `202` nas últimas 24 horas |
| `409 file_replaced` | O arquivo foi excluído enquanto a resposta aguardava |
| `409 user_purging` | O usuário está sendo excluído |
| `413 payload_too_large` | Acima de 512 MiB (upload) ou 20 MiB (conversão, ou com `password`) |
| `415 unsupported_file` | Não é um tipo suportado, ou não é o `type` declarado; a mensagem diz em que formato salvá-lo |
| `422 password_protected` | O arquivo tem senha: envie-a como `password` |
| `422 unreadable_file` | O arquivo está danificado |
| `422 no_text` | Nenhuma página, planilha, slide, parágrafo ou imagem contém texto |
| `503 files_unavailable` | Não é possível armazenar arquivos agora; tente novamente mais tarde |

Um arquivo com mais de 5.000 páginas, planilhas ou slides termina como `failed` com `too_large`.


## Related topics

- [Tipos de arquivo e Markdown](https://docs.conare.ai/pt-BR/file-types.md)
- [Google Cloud Storage](https://docs.conare.ai/pt-BR/gcs.md)
- [Visão geral da API](https://docs.conare.ai/pt-BR/api.md)
- [Filtros](https://docs.conare.ai/pt-BR/filters.md)
- [Read a file](https://docs.conare.ai/pt-br/api-reference/files/read-a-file.md)


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