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

# Dateien

> Laden Sie eine PDF-, Word-, PowerPoint-, Excel-, CSV-, Text- oder Bilddatei als durchsuchbares Dokument hoch oder parsen Sie sie zu Markdown.

Zwei Routen lesen Dateien mit demselben Parser, denselben Optionen und demselben Ergebnis:

| Route | Funktion | Größe |
| - | - | - |
| [`POST /namespaces/:namespace/files`](#eine-datei-hochladen) | Speichert die Datei als ein durchsuchbares Dokument; eine Suche nennt die Seite, Folie oder Zeilen, die antworten | Bis zu 512 MiB und 5.000 Seiten |
| [`POST /parse`](#eine-datei-parsen) | Gibt die Datei als Markdown zurück; speichert nichts | Bis zu 20 MiB |

Scans und Bilder werden per OCR gelesen, egal wie viele Seiten es sind. Unterstützte Formate: [Dateitypen](https://docs.conare.ai/de/file-types.md).

## Eine Datei hochladen

`POST /namespaces/:namespace/files`

Senden Sie die Bytes der Datei als Body, als Dateiteil eines Multipart-Formulars oder als JSON `{"url": "https://..."}`, damit Conare sie abruft.

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

Die Antwort wartet bis zu `wait` Sekunden, bis die Datei gelesen ist: `200`, wenn sie `ready` oder `failed` ist, sonst `202`, solange sie gelesen wird.

### Optionen

Query-Parameter, für beide Routen, sofern nicht anders angegeben.

| Option | Typ | Funktion |
| - | - | - |
| `name` | string | Der Name der Datei, bis zu 4.096 Zeichen; seine Endung unterscheidet `.csv`, `.tsv` und `.md` von Text |
| `id` | string | Nur Upload. Die ID der Datei, das Ende der ID ihres Dokuments; standardmäßig `name`, wobei andere Zeichen durch `-` ersetzt werden |
| `type` | string | `pdf`, `docx`, `pptx`, `xlsx`, `csv`, `png`, ... ([alle](https://docs.conare.ai/de/file-types.md)); sonst aus den Bytes, dann aus dem Namen ermittelt |
| `user` | string | Nur Upload. Wem die Datei gehört; das Löschen des Benutzers löscht sie |
| `metadata` | string | Nur Upload. Ein JSON-Objekt, das in die Metadaten des Dokuments kopiert wird |
| `pages` | string | Zu lesende Seiten, Folien oder Frames, etwa `1-20,25` oder `5-` |
| `password` | string | Öffnet eine geschützte PDF-, Word-, PowerPoint- oder Excel-Datei, bis zu 20 MiB |
| `layout` | boolean, Standard `false` | Jeder per OCR gelesene Teil enthält zusätzlich `blocks`: die Bereiche seiner Seite ([Felder](https://docs.conare.ai/de/file-types.md#layout-blöcke)) |
| `wait` | Sekunden, Standard 60 | Wie lange vor `202` auf das Lesen gewartet wird, bis zu 300; `0` antwortet sofort |

* Ein `Content-Type` wie `application/pdf` gibt ebenfalls den Typ an.
* `wait`: `true` entspricht 60; die Antwort kommt immer innerhalb von 105 Sekunden. Bei Uploads antwortet `false`, sobald der Text gespeichert ist, mit `ocr_pending`.
* Eine Seite außerhalb von `pages` wird weder gelesen noch per OCR erfasst; `pages` bei einer Datei ohne Seiten ergibt `400`.

Vollständiges Schema: [Eine Datei hochladen](https://docs.conare.ai/de/api-reference/files/upload-a-file.md).

### Antwort

| Feld | Bedeutung |
| - | - |
| `file_id`, `name`, `type` | Die verwendete ID, der Name und der erkannte Typ (`image` für jedes Bildformat) |
| `state` | `queued`, `parsing`, `ocr` (OCR liest noch `ocr_pending`), `ready` oder `failed` mit `error` |
| `source_id` | Die Dateiquelle des Namespace; die ID des Dokuments beginnt damit |
| `ids` | Das eine Dokument der Datei, `["<source_id>:<file_id>"]`, sobald `ready` |
| `uploaded_at` | Unix-Millisekunden |
| `result` | `unchanged`, wenn dieselbe Datei mit demselben Namen, denselben Metadaten und Optionen schon hochgeladen wurde; nichts wird erneut gelesen |
| `pages` | Die Seiten einer PDF oder die Frames eines Bildes |
| `ocr_failed` | Seiten, die OCR nach mehreren Versuchen nicht lesen konnte; laden Sie erneut hoch, um sie zu wiederholen |
| `markdown`, `parts`, `without_text` | Das [Ergebnis](#ergebnis) |

`images_without_text`, `pages_without_text`, `pages_ocr`, `images_ocr`, `sheets`, `slides` und `slides_without_text` sind veraltet: `parts` und `without_text` sagen dasselbe aus.

## Eine Datei prüfen

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

Gibt den neuesten Upload der Datei mit denselben Feldern zurück; fragen Sie ihn nach einem `202` regelmäßig ab.

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

| Option | Typ | Funktion |
| - | - | - |
| `user` | string | Der Benutzer, für eine mit `user` hochgeladene Datei |

Vollständiges Schema: [Eine Datei lesen](https://docs.conare.ai/de/api-reference/files/read-a-file.md).

## Gespeicherte Dokumente

Eine Datei ist ein Dokument, `<source_id>:<file_id>`; ihre Seiten, Folien, Tabellenzeilen, Abschnitte und Bilder sind seine Teile.

| Wo | Was Sie erhalten |
| - | - |
| [Suche](https://docs.conare.ai/de/query.md) | Eine Seite einer PDF oder eines Bildes, eine Folie oder ein Zeilenbereich einer Tabelle ist ein eigener Treffer, ID `<source_id>:<file_id>$<part>`: `$page-3`, `$slide-4`, `$<sheet>-1` |
| Suche in einer Text-, Markdown- oder Word-Datei | Ein Treffer, die Datei `<source_id>:<file_id>`, mit ihren Passagen von überall in ihr |
| Die `metadata` eines Treffers | Wo sein Teil oder seine erste Passage steht, nach den Schlüsseln unten |
| [`GET /namespaces/:namespace/documents/:id`](https://docs.conare.ai/de/documents#ein-dokument-abrufen) | Mit der ID der Datei der Text der ganzen Datei, eine Leerzeile zwischen den Seiten; mit der ID eines Teils nur dieser Teil |

### Wo ein Teil steht

| Datei | Position in den Metadaten |
| - | - |
| PDF | `page` |
| Word, Text, Markdown | `part`, `heading` und bei Text `lines` |
| PowerPoint | `slide` |
| Excel, CSV, TSV | `sheet`, `rows` |
| Bild | `page` und `frame` |
| Ein Bild in Word | `image`, `heading` |
| Ein Bild auf einer Folie | `slide`, `image` |
| Ein Diagramm in einer Tabelle | `sheet` |

Das Dokument hat außerdem `file`, `file_id`, `file_type`, `uploaded_at`, die `metadata` des Uploads und `ocr: true`, wenn OCR es gelesen hat. Eine früher hochgeladene Datei kann noch ein Dokument pro Teil sein, etwa `<source_id>:<file_id>:page-1`, bis sie erneut hochgeladen wird.

| Ziel | Vorgehen |
| - | - |
| Eine Datei ersetzen | Laden Sie sie erneut mit derselben ID hoch |
| Sicher wiederholen | Dieselbe Datei mit demselben Namen, denselben Metadaten und Optionen antwortet `unchanged`, ganz ohne `Idempotency-Key` |
| Eine Datei durchsuchen | [Filtern](https://docs.conare.ai/de/filters.md) Sie nach `{ "file_id": "report.pdf" }` |
| Eine Seite durchsuchen | Filtern Sie nach `{ "file_id": "report.pdf", "page": 3 }` |
| Benutzer trennen | Laden Sie mit `user` hoch, [suchen](https://docs.conare.ai/de/query.md) Sie mit `user` |
| Das Original löschen | Es bleibt erhalten, bis der Namespace oder sein Benutzer gelöscht wird |

## Eine Datei parsen

`POST /parse`

Gibt die Datei als Markdown zurück und speichert nichts; jeder Schlüssel kann parsen, auch ein Nur-Modelle-Schlüssel.

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

| Option | Typ | Funktion |
| - | - | - |
| `url` | string | In einem JSON-Body: eine `https`-URL unter einer öffentlichen Adresse, innerhalb von 60 Sekunden abgerufen, bis zu 20 MiB |
| `name`, `type`, `pages`, `password`, `layout`, `wait` | | Wie beim [Upload](#optionen) |

* Der Body umfasst bis zu 20 MiB, und OCR liest bis zu 100 Seiten; spätere Seiten behalten ihre Textebene.
* Um eine JSON-Datei zu parsen, senden Sie sie als `text/plain`.

Vollständiges Schema: [Eine Datei parsen](https://docs.conare.ai/de/api-reference/parse/parse-a-file-to-markdown.md).

### Einen Parse-Vorgang abrufen

`GET /parse/:id`

Ein Parse-Vorgang, der mit `202` (`state: "parsing"`) geantwortet hat, wird 24 Stunden aufbewahrt: Rufen Sie ihn ab, bis `state` den Wert `done` hat, oder `failed` mit seinem `error`.

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

Vollständiges Schema: [Einen Parse-Vorgang lesen](https://docs.conare.ai/de/api-reference/parse/get-a-parse-result.md).

## Ergebnis

| Feld | Bedeutung |
| - | - |
| `markdown` | Die gesamte Datei; jede Seite, Folie und Tabelle beginnt mit `<!-- page 3 -->`, `<!-- slide 4 -->` oder `<!-- sheet "Q3" -->` |
| `parts` | In Lesereihenfolge, jeweils mit `locator`, `markdown`, `ocr` und `confidence` |
| `parts[].locator` | `{"page": 3}`, `{"slide": 4, "image": 1}`, `{"sheet": "Q3", "rows": "2-41"}` oder `{"part": 2, "heading": "..."}` |
| `parts[].ocr` | Per OCR aus dem Bild der Seite gelesen, nicht aus ihrer Textebene |
| `parts[].confidence` | Die Sicherheit der OCR, 0 bis 1; `null`, wenn OCR keine angab (die meisten digital erstellten Seiten) |
| `without_text` | `pages`, `slides` und `images` ohne Text, jedes Bild mit seinem [`reason`](https://docs.conare.ai/de/file-types#bilder-in-word-und-powerpoint) |

Die Regeln für das Markdown stehen unter [Dateitypen](https://docs.conare.ai/de/file-types.md#markdown).

## Fehler

| Fehler | Wann |
| - | - |
| `400 invalid_request` | Eine Option ist ungültig: `pages` bei einer Datei ohne Seiten, `wait` über 300, `metadata`, das kein JSON-Objekt ist, eine URL, die nicht `https` unter einer öffentlichen Adresse ist |
| `400 fetch_failed` | Die URL hat nicht mit `200` und der Datei geantwortet |
| `404 parse_not_found` | Kein Parse-Vorgang mit dieser ID hat in den letzten 24 Stunden mit `202` geantwortet |
| `409 file_replaced` | Die Datei wurde gelöscht, während die Antwort wartete |
| `409 user_purging` | Der Benutzer wird gerade gelöscht |
| `413 payload_too_large` | Über 512 MiB (Upload) oder 20 MiB (Parsen oder mit `password`) |
| `415 unsupported_file` | Kein unterstützter Typ oder nicht der angegebene `type`; die Meldung nennt das Format zum Speichern |
| `422 password_protected` | Die Datei hat ein Passwort: Senden Sie es als `password` |
| `422 unreadable_file` | Die Datei ist beschädigt |
| `422 no_text` | Keine Seite, Tabelle, Folie, kein Absatz und kein Bild enthält Text |
| `503 files_unavailable` | Dateien können gerade nicht gespeichert werden; versuchen Sie es später erneut |

Eine Datei mit über 5.000 Seiten, Tabellen oder Folien endet als `failed` mit `too_large`.


## Related topics

- [Google Cloud Storage](https://docs.conare.ai/de/gcs.md)
- [Dateitypen und Markdown](https://docs.conare.ai/de/file-types.md)
- [Read a file](https://docs.conare.ai/de/api-reference/files/read-a-file.md)
- [Upload a file](https://docs.conare.ai/de/api-reference/files/upload-a-file.md)
- [TypeScript SDK](https://docs.conare.ai/de/sdk.md)


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