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

# Файли

> Завантажуйте файли PDF, Word, PowerPoint, Excel, CSV, текстові файли й зображення як один документ для пошуку або розбирайте їх у Markdown без збереження.

Два маршрути читають файли одним парсером, з однаковими параметрами й однаковим результатом:

| Маршрут | Що робить | Розмір |
| - | - | - |
| [`POST /namespaces/:namespace/files`](#завантаження-файлу) | Зберігає файл як один документ для пошуку; пошук називає сторінку, слайд або рядки, що відповідають | До 512 MiB і 5 000 сторінок |
| [`POST /parse`](#розбір-файлу) | Повертає файл у форматі Markdown; нічого не зберігає | До 20 MiB |

Скани й зображення читаються за допомогою OCR, незалежно від кількості сторінок. Підтримувані формати: [Типи файлів](https://docs.conare.ai/uk/file-types.md).

## Завантаження файлу

`POST /namespaces/:namespace/files`

Надішліть байти файлу як тіло запиту, як файлову частину multipart-форми або як JSON `{"url": "https://..."}`, щоб Conare завантажив його сам.

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

Відповідь чекає до `wait` секунд, поки файл буде прочитано: `200`, коли він `ready` або `failed`, інакше `202`, поки триває читання.

### Параметри

Параметри запиту, для обох маршрутів, якщо не зазначено інше.

| Параметр | Тип | Що робить |
| - | - | - |
| `name` | string | Назва файлу, до 4 096 символів; її розширення відрізняє `.csv`, `.tsv` і `.md` від тексту |
| `id` | string | Лише для завантаження. Id файлу, кінець id його документа; за замовчуванням — `name`, де інші символи замінено на `-` |
| `type` | string | `pdf`, `docx`, `pptx`, `xlsx`, `csv`, `png`, ... ([усі](https://docs.conare.ai/uk/file-types.md)); інакше визначається за байтами, потім за назвою |
| `user` | string | Лише для завантаження. Кому належить файл; видалення користувача видаляє і файл |
| `metadata` | string | Лише для завантаження. JSON-об’єкт, що копіюється в метадані документа |
| `pages` | string | Сторінки, слайди або кадри для читання, як-от `1-20,25` чи `5-` |
| `password` | string | Відкриває захищений файл PDF, Word, PowerPoint або Excel, до 20 MiB |
| `layout` | boolean, за замовчуванням `false` | Кожна частина, прочитана OCR, також містить `blocks`: області її сторінки ([поля](https://docs.conare.ai/uk/file-types.md#блоки-макета)) |
| `wait` | секунди, за замовчуванням 60 | Скільки чекати на читання перед `202`, до 300; `0` відповідає одразу |

* `Content-Type`, як-от `application/pdf`, також задає тип.
* `wait`: `true` означає 60; відповідь завжди надходить протягом 105 секунд. Під час завантаження `false` відповідає, щойно текст збережено, з `ocr_pending`.
* Сторінка поза `pages` не читається й не обробляється OCR; `pages` для файлу без сторінок дає `400`.

Повна схема: [Upload a file](https://docs.conare.ai/uk/api-reference/files/upload-a-file.md).

### Відповідь

| Поле | Значення |
| - | - |
| `file_id`, `name`, `type` | Використаний id, назва й визначений тип (`image` для всіх форматів зображень) |
| `state` | `queued`, `parsing`, `ocr` (OCR ще читає `ocr_pending`), `ready` або `failed` з `error` |
| `source_id` | Файлове джерело простору імен; з нього починається id документа |
| `ids` | Єдиний документ файлу, `["<source_id>:<file_id>"]`, щойно стан `ready` |
| `uploaded_at` | Мілісекунди Unix |
| `result` | `unchanged`, якщо той самий файл із тими самими назвою, метаданими й параметрами вже завантажувався; повторно нічого не читається |
| `pages` | Сторінки PDF або кадри зображення |
| `ocr_failed` | Сторінки, які OCR не зміг прочитати після кількох спроб; завантажте файл знову, щоб повторити |
| `markdown`, `parts`, `without_text` | [Результат](#результат) |

`images_without_text`, `pages_without_text`, `pages_ocr`, `images_ocr`, `sheets`, `slides` і `slides_without_text` застаріли: `parts` і `without_text` містять те саме.

## Перевірка файлу

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

Повертає останнє завантаження файлу з тими самими полями; опитуйте його після `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");
```

| Параметр | Тип | Що робить |
| - | - | - |
| `user` | string | Користувач, для файлу, завантаженого з `user` |

Повна схема: [Read a file](https://docs.conare.ai/uk/api-reference/files/read-a-file.md).

## Збережені документи

Файл — це один документ, `<source_id>:<file_id>`; його сторінки, слайди, рядки аркушів, розділи й зображення — його частини.

| Де | Що ви отримуєте |
| - | - |
| [Пошук](https://docs.conare.ai/uk/query.md) | Сторінка PDF чи зображення, слайд або діапазон рядків аркуша — окремий результат з id `<source_id>:<file_id>$<part>`: `$page-3`, `$slide-4`, `$<sheet>-1` |
| Пошук у текстовому, Markdown- чи Word-файлі | Один результат, файл `<source_id>:<file_id>`, з уривками з будь-якого його місця |
| `metadata` результату | Де його частина або перший уривок, за ключами нижче |
| [`GET /namespaces/:namespace/documents/:id`](https://docs.conare.ai/uk/documents#отримайте-документ) | З id файлу — текст усього файлу, з порожнім рядком між сторінками; з id частини — лише ця частина |

### Де розташована частина

| Файл | Розташування в метаданих |
| - | - |
| PDF | `page` |
| Word, текст, Markdown | `part`, `heading` і `lines` для тексту |
| PowerPoint | `slide` |
| Excel, CSV, TSV | `sheet`, `rows` |
| Зображення | `page` і `frame` |
| Зображення у Word | `image`, `heading` |
| Зображення на слайді | `slide`, `image` |
| Діаграма на аркуші | `sheet` |

Документ також має `file`, `file_id`, `file_type`, `uploaded_at`, `metadata` завантаження та `ocr: true`, якщо його прочитав OCR. Файл, завантажений раніше, може й далі бути одним документом на частину, наприклад `<source_id>:<file_id>:page-1`, доки його не завантажать знову.

| Щоб | Зробіть |
| - | - |
| Замінити файл | Завантажте його знову з тим самим id |
| Безпечно повторити | Той самий файл із тими самими назвою, метаданими й параметрами отримує `unchanged`, без потреби в `Idempotency-Key` |
| Шукати в одному файлі | [Фільтруйте](https://docs.conare.ai/uk/filters.md) за `{ "file_id": "report.pdf" }` |
| Шукати на одній сторінці | Фільтруйте за `{ "file_id": "report.pdf", "page": 3 }` |
| Розділити користувачів | Завантажуйте з `user`, [шукайте](https://docs.conare.ai/uk/query.md) з `user` |
| Видалити оригінал | Він зберігається, доки не буде видалено простір імен або його користувача |

## Розбір файлу

`POST /parse`

Повертає файл у форматі Markdown і нічого не зберігає; розбирати може будь-який ключ, зокрема ключ 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": [] }
}
```

| Параметр | Тип | Що робить |
| - | - | - |
| `url` | string | У тілі JSON: URL `https` на публічній адресі, що завантажується протягом 60 секунд, до 20 MiB |
| `name`, `type`, `pages`, `password`, `layout`, `wait` | | Як під час [завантаження](#параметри) |

* Тіло запиту — до 20 MiB, а OCR читає до 100 сторінок; подальші сторінки зберігають свій текстовий шар.
* Щоб розібрати файл JSON, надішліть його як `text/plain`.

Повна схема: [Parse a file](https://docs.conare.ai/uk/api-reference/parse/parse-a-file-to-markdown.md).

### Отримання результату розбору

`GET /parse/:id`

Розбір, що відповів `202` (`state: "parsing"`), зберігається 24 години: запитуйте його, доки `state` не стане `done` або `failed` з `error`.

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

Повна схема: [Read a parse](https://docs.conare.ai/uk/api-reference/parse/get-a-parse-result.md).

## Результат

| Поле | Значення |
| - | - |
| `markdown` | Увесь файл; кожна сторінка, слайд і аркуш починаються з `<!-- page 3 -->`, `<!-- slide 4 -->` або `<!-- sheet "Q3" -->` |
| `parts` | У порядку читання, кожна з `locator`, `markdown`, `ocr` і `confidence` |
| `parts[].locator` | `{"page": 3}`, `{"slide": 4, "image": 1}`, `{"sheet": "Q3", "rows": "2-41"}` або `{"part": 2, "heading": "..."}` |
| `parts[].ocr` | Прочитано OCR із зображення сторінки, а не з її текстового шару |
| `parts[].confidence` | Упевненість OCR, від 0 до 1; `null`, якщо OCR її не надав (більшість цифрових сторінок) |
| `without_text` | `pages`, `slides` і `images` без тексту, кожне зображення зі своєю [`reason`](https://docs.conare.ai/uk/file-types#зображення-у-word-і-powerpoint) |

Правила Markdown описано в розділі [Типи файлів](https://docs.conare.ai/uk/file-types.md#markdown).

## Помилки

| Помилка | Коли |
| - | - |
| `400 invalid_request` | Недійсний параметр: `pages` для файлу без сторінок, `wait` понад 300, `metadata`, що не є JSON-об’єктом, URL не `https` або не на публічній адресі |
| `400 fetch_failed` | URL не відповів `200` із файлом |
| `404 parse_not_found` | Жоден розбір із цим id не відповідав `202` за останні 24 години |
| `409 file_replaced` | Файл було видалено, поки відповідь очікувала |
| `409 user_purging` | Користувач видаляється |
| `413 payload_too_large` | Понад 512 MiB (завантаження) або 20 MiB (розбір чи з `password`) |
| `415 unsupported_file` | Тип не підтримується або не відповідає вказаному `type`; у повідомленні сказано, у якому форматі його зберегти |
| `422 password_protected` | Файл має пароль: надішліть його як `password` |
| `422 unreadable_file` | Файл пошкоджено |
| `422 no_text` | Жодна сторінка, аркуш, слайд, абзац чи зображення не містить тексту |
| `503 files_unavailable` | Зараз неможливо зберегти файли; повторіть пізніше |

Файл понад 5 000 сторінок, аркушів або слайдів завершується станом `failed` із `too_large`.


## Related topics

- [Google Cloud Storage](https://docs.conare.ai/uk/gcs.md)
- [Read a file](https://docs.conare.ai/uk/api-reference/files/read-a-file.md)
- [Upload a file](https://docs.conare.ai/uk/api-reference/files/upload-a-file.md)
- [Типи файлів і Markdown](https://docs.conare.ai/uk/file-types.md)
- [Вступ](https://docs.conare.ai/uk/index.md)


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