Файли

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

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

Скани й зображення читаються за допомогою OCR, незалежно від кількості сторінок. Підтримувані формати: Типи файлів.

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

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

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

Відповідь чекає до 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`, … (усі); інакше визначається за байтами, потім за назвою
`user`	string	Лише для завантаження. Кому належить файл; видалення користувача видаляє і файл
`metadata`	string	Лише для завантаження. JSON-об’єкт, що копіюється в метадані документа
`pages`	string	Сторінки, слайди або кадри для читання, як-от `1-20,25` чи `5-`
`password`	string	Відкриває захищений файл PDF, Word, PowerPoint або Excel, до 20 MiB
`layout`	boolean, за замовчуванням `false`	Кожна частина, прочитана OCR, також містить `blocks`: області її сторінки (поля)
`wait`	секунди, за замовчуванням 60	Скільки чекати на читання перед `202`, до 300; `0` відповідає одразу

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

Повна схема: Upload a file.

Відповідь

Поле	Значення
`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.

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

const file = await reports.getFile("report.pdf");

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

Повна схема: Read a file.

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

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

Де	Що ви отримуєте
Пошук	Сторінка 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`	З 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`
Шукати в одному файлі	Фільтруйте за `{ "file_id": "report.pdf" }`
Шукати на одній сторінці	Фільтруйте за `{ "file_id": "report.pdf", "page": 3 }`
Розділити користувачів	Завантажуйте з `user`, шукайте з `user`
Видалити оригінал	Він зберігається, доки не буде видалено простір імен або його користувача

Розбір файлу

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

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

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

Повна схема: Parse a file.

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

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

curl

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

Повна схема: Read a parse.

Результат

Поле	Значення
`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`

Правила 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.

Початок роботи

Основне

Синхронізація

Моделі

Інструменти

Файли

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

Параметри

Відповідь

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

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

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

Розбір файлу

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

Результат

Помилки

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

​Параметри

​Відповідь

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

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

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

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

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

​Результат

​Помилки

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

Параметри

Відповідь

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

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

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

Розбір файлу

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

Результат

Помилки