Arquivos

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

Rota	Faz	Tamanho
`POST /namespaces/:namespace/files`	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`	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.

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.

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

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); 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)
`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.

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

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.

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

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.

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

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

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

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.

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.

curl

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

Schema completo: Ler uma conversão.

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`

As regras do Markdown estão em Tipos de arquivo.

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.

Primeiros passos

Essencial

Sincronização

Modelos

Ferramentas

Arquivos

Enviar um arquivo

Opções

Resposta

Verificar um arquivo

Documentos armazenados

Onde está uma parte

Converter um arquivo

Buscar uma conversão

Resultado

Erros

​Enviar um arquivo

​Opções

​Resposta

​Verificar um arquivo

​Documentos armazenados

​Onde está uma parte

​Converter um arquivo

​Buscar uma conversão

​Resultado

​Erros

Enviar um arquivo

Opções

Resposta

Verificar um arquivo

Documentos armazenados

Onde está uma parte

Converter um arquivo

Buscar uma conversão

Resultado

Erros