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

# File

> Carica un file PDF, Word, PowerPoint, Excel, CSV, di testo o immagine come un unico documento ricercabile, oppure analizzalo in Markdown senza archiviare nulla.

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

| Route | Cosa fa | Dimensione |
| - | - | - |
| [`POST /namespaces/:namespace/files`](#caricare-un-file) | 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`](#analizzare-un-file) | 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](https://docs.conare.ai/it/file-types.md).

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

```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 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](https://docs.conare.ai/it/file-types.md)); 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](https://docs.conare.ai/it/file-types.md#blocchi-di-layout)) |
| `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](https://docs.conare.ai/it/api-reference/files/upload-a-file.md).

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

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

| Opzione | Tipo | Cosa fa |
| - | - | - |
| `user` | string | L'utente, per un file caricato con `user` |

Schema completo: [Read a file](https://docs.conare.ai/it/api-reference/files/read-a-file.md).

## 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](https://docs.conare.ai/it/query.md) | 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`](https://docs.conare.ai/it/documents#ottenere-un-documento) | 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](https://docs.conare.ai/it/filters.md) 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](https://docs.conare.ai/it/query.md) 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.

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

| 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](#opzioni) |

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

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

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

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

## 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`](https://docs.conare.ai/it/file-types#immagini-in-word-e-powerpoint) |

Le regole del Markdown sono in [Tipi di file](https://docs.conare.ai/it/file-types.md#markdown).

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


## Related topics

- [Upload a file](https://docs.conare.ai/it/api-reference/files/upload-a-file.md)
- [Read a file](https://docs.conare.ai/it/api-reference/files/read-a-file.md)
- [Parse a file to Markdown](https://docs.conare.ai/it/api-reference/parse/parse-a-file-to-markdown.md)
- [Tipi di file e Markdown](https://docs.conare.ai/it/file-types.md)
- [Google Cloud Storage](https://docs.conare.ai/it/gcs.md)


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