File

Due route leggono i file con un unico parser, le stesse opzioni e lo stesso risultato:

Route	Cosa fa	Dimensione
`POST /namespaces/:namespace/files`	Archivia il file come un unico documento ricercabile; una ricerca indica quale pagina, slide o righe rispondono	Fino a 512 MiB e 5.000 pagine
`POST /parse`	Restituisce il file in Markdown; non archivia nulla	Fino a 20 MiB

Scansioni e immagini vengono lette tramite OCR, qualunque sia il numero di pagine. Formati supportati: Tipi di file.

Caricare un file

POST /namespaces/:namespace/files Invia i byte del file come body, come parte file di un form multipart, o come JSON {"url": "https://..."} perché Conare lo scarichi.

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 risposta attende fino a wait secondi che il file venga letto: 200 quando è ready o failed, altrimenti 202 durante la lettura.

Opzioni

Parametri di query, validi su entrambe le route salvo diversa indicazione.

Opzione	Tipo	Cosa fa
`name`	string	Il nome del file, fino a 4.096 caratteri; la sua estensione distingue `.csv`, `.tsv` e `.md` dal testo
`id`	string	Solo caricamento. L’id del file, la parte finale dell’id del suo documento; predefinito `name` con gli altri caratteri sostituiti da `-`
`type`	string	`pdf`, `docx`, `pptx`, `xlsx`, `csv`, `png`, … (tutti); altrimenti ricavato dai byte, poi dal nome
`user`	string	Solo caricamento. A chi appartiene il file; eliminare l’utente lo elimina
`metadata`	string	Solo caricamento. Un oggetto JSON copiato nei metadati del documento
`pages`	string	Pagine, slide o frame da leggere, come `1-20,25` o `5-`
`password`	string	Apre un file PDF, Word, PowerPoint o Excel protetto, fino a 20 MiB
`layout`	boolean, predefinito `false`	Ogni parte letta con OCR include anche `blocks`: le regioni della sua pagina (campi)
`wait`	secondi, predefinito 60	Quanto attendere la lettura prima di `202`, fino a 300; `0` risponde subito

Anche un Content-Type come application/pdf dichiara il tipo.
wait: true vale 60; la risposta arriva sempre entro 105 secondi. Nei caricamenti, false risponde appena il testo è archiviato, con ocr_pending.
Una pagina fuori da pages non viene letta né elaborata con OCR; pages su un file senza pagine restituisce 400.

Schema completo: Upload a file.

Risposta

Campo	Significato
`file_id`, `name`, `type`	L’id usato, il nome e il tipo rilevato (`image` per ogni formato immagine)
`state`	`queued`, `parsing`, `ocr` (l’OCR sta ancora leggendo `ocr_pending`), `ready` o `failed` con `error`
`source_id`	La sorgente dei file del namespace; l’id del documento inizia con essa
`ids`	L’unico documento del file, `["<source_id>:<file_id>"]`, una volta `ready`
`uploaded_at`	Millisecondi Unix
`result`	`unchanged` quando lo stesso file, nome, metadati e opzioni erano già stati caricati; nulla viene riletto
`pages`	Le pagine di un PDF o i frame di un’immagine
`ocr_failed`	Pagine che l’OCR non ha potuto leggere dopo diversi tentativi; carica di nuovo per riprovarle
`markdown`, `parts`, `without_text`	Il risultato

images_without_text, pages_without_text, pages_ocr, images_ocr, sheets, slides e slides_without_text sono deprecati: parts e without_text dicono lo stesso.

Controllare un file

GET /namespaces/:namespace/files/:id Restituisce l’ultimo caricamento del file, con gli stessi campi; interrogalo dopo 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");

Opzione	Tipo	Cosa fa
`user`	string	L’utente, per un file caricato con `user`

Schema completo: Read a file.

Documenti archiviati

Un file è un documento, <source_id>:<file_id>; le sue pagine, slide, righe di foglio, sezioni e immagini sono le sue parti.

Dove	Cosa ottieni
Ricerca	Una pagina di un PDF o di un’immagine, una slide o un intervallo di righe di un foglio è un risultato a sé, id `<source_id>:<file_id>$<part>`: `$page-3`, `$slide-4`, `$<sheet>-1`
Ricerca in un file di testo, Markdown o Word	Un solo risultato, il file `<source_id>:<file_id>`, con i suoi passaggi da qualunque punto del file
I `metadata` di un risultato	Dove si trova la sua parte, o il suo primo passaggio, con le chiavi qui sotto
`GET /namespaces/:namespace/documents/:id`	Con l’id del file, il testo dell’intero file, con una riga vuota tra le pagine; con l’id di una parte, solo quella parte

Dove si trova una parte

File	Posizione nei metadati
PDF	`page`
Word, testo, Markdown	`part`, `heading`, e `lines` per il testo
PowerPoint	`slide`
Excel, CSV, TSV	`sheet`, `rows`
Immagine	`page`, e `frame`
Un’immagine in Word	`image`, `heading`
Un’immagine in una slide	`slide`, `image`
Un grafico in un foglio	`sheet`

Il documento ha anche file, file_id, file_type, uploaded_at, i metadata del caricamento e ocr: true quando è stato letto con OCR. Un file caricato in precedenza può essere ancora un documento per parte, come <source_id>:<file_id>:page-1, finché non viene ricaricato.

Per	Fai
Sostituire un file	Caricalo di nuovo con lo stesso id
Riprovare in sicurezza	Lo stesso file, nome, metadati e opzioni restituisce `unchanged`, senza bisogno di `Idempotency-Key`
Cercare in un solo file	Filtra su `{ "file_id": "report.pdf" }`
Cercare in una sola pagina	Filtra su `{ "file_id": "report.pdf", "page": 3 }`
Separare gli utenti	Carica con `user`, cerca con `user`
Eliminare l’originale	Viene conservato finché il namespace, o il suo utente, non viene eliminato

Analizzare un file

POST /parse Restituisce il file in Markdown e non archivia nulla; qualsiasi chiave può analizzare, anche una chiave 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": [] }
}

Opzione	Tipo	Cosa fa
`url`	string	In un body JSON: un URL `https` su un indirizzo pubblico, scaricato entro 60 secondi, fino a 20 MiB
`name`, `type`, `pages`, `password`, `layout`, `wait`		Come nel caricamento

Il body è al massimo di 20 MiB e l’OCR legge fino a 100 pagine; le pagine successive mantengono il loro livello di testo.
Per analizzare un file JSON, invialo come text/plain.

Schema completo: Parse a file.

Recuperare un’analisi

GET /parse/:id Un’analisi che ha risposto 202 (state: "parsing") viene conservata 24 ore: recuperala finché state non è done, o failed con il suo error.

curl

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

Schema completo: Read a parse.

Risultato

Campo	Significato
`markdown`	L’intero file; ogni pagina, slide e foglio inizia con `<!-- page 3 -->`, `<!-- slide 4 -->` o `<!-- sheet "Q3" -->`
`parts`	In ordine di lettura, ciascuna con `locator`, `markdown`, `ocr` e `confidence`
`parts[].locator`	`{"page": 3}`, `{"slide": 4, "image": 1}`, `{"sheet": "Q3", "rows": "2-41"}` o `{"part": 2, "heading": "..."}`
`parts[].ocr`	Letta tramite OCR dall’immagine della pagina, non dal suo livello di testo
`parts[].confidence`	La certezza dell’OCR, da 0 a 1; `null` quando l’OCR non ne ha fornita (la maggior parte delle pagine nate digitali)
`without_text`	`pages`, `slides` e `images` che non contengono testo, ogni immagine con il suo `reason`

Le regole del Markdown sono in Tipi di file.

Errori

Errore	Quando
`400 invalid_request`	Un’opzione non è valida: `pages` su un file senza pagine, `wait` oltre 300, `metadata` che non è un oggetto JSON, un URL che non è `https` su un indirizzo pubblico
`400 fetch_failed`	L’URL non ha risposto `200` con il file
`404 parse_not_found`	Nessuna analisi con quell’id ha risposto `202` nelle ultime 24 ore
`409 file_replaced`	Il file è stato eliminato mentre la risposta era in attesa
`409 user_purging`	L’utente è in corso di eliminazione
`413 payload_too_large`	Oltre 512 MiB (caricamento) o 20 MiB (analisi, o con `password`)
`415 unsupported_file`	Non è un tipo supportato, o non è il `type` dichiarato; il messaggio indica in che formato salvarlo
`422 password_protected`	Il file ha una password: inviala come `password`
`422 unreadable_file`	Il file è danneggiato
`422 no_text`	Nessuna pagina, foglio, slide, paragrafo o immagine contiene testo
`503 files_unavailable`	Al momento non è possibile archiviare file; riprova più tardi

Un file con oltre 5.000 pagine, fogli o slide termina failed con too_large.

Primi passi

Fondamenti

Sincronizzazione

Modelli

Strumenti

File

Caricare un file

Opzioni

Risposta

Controllare un file

Documenti archiviati

Dove si trova una parte

Analizzare un file

Recuperare un’analisi

Risultato

Errori

​Caricare un file

​Opzioni

​Risposta

​Controllare un file

​Documenti archiviati

​Dove si trova una parte

​Analizzare un file

​Recuperare un’analisi

​Risultato

​Errori

Caricare un file

Opzioni

Risposta

Controllare un file

Documenti archiviati

Dove si trova una parte

Analizzare un file

Recuperare un’analisi

Risultato

Errori