LOOMA / ДОКУМЕНТАЦИЯ

API приложения

Локальный бэкенд по умолчанию работает на http://127.0.0.1:8765. Embed-сервер — отдельный API на порту 8766 с другой авторизацией. Не подменяйте один адрес другим.

Полный справочник API приложения · Справочник embed-сервера

Доступ и авторизация#

Для защищённых маршрутов приложения используется заголовок X-API-Key, если в настройках включена авторизация и задан ключ. Это не глобальная защита всех маршрутов: часть настроек и управляющих endpoints не требует ключа. Локальный API рассчитан на loopback; не открывайте порт 8765 в публичную сеть.

Embed-сервер использует Authorization: Bearer <ключ>; его /health открыт. Текущая реализация допускает работу без авторизации при пустом или повреждённом файле ключей — сохраняйте корректный непустой файл и ограничьте сетевой доступ. Ключ embed-сервера также даёт доступ к управлению ключами.

Живой Swagger UI каждого сервера находится на /docs, OpenAPI — на /openapi.json. Статический справочник ниже работает офлайн и не отправляет запросы к вашей библиотеке. Это снимок схемы той версии исходников, из которой собрана документация.

Поиск с текстом и координатами#

curl --get 'http://127.0.0.1:8765/api/search' \
  --data-urlencode 'q=солнечная энергия' \
  --data-urlencode 'semantic_weight=0.5' \
  --data-urlencode 'k=10' \
  --data-urlencode 'include_text=true' \
  -H "X-API-Key: $LOOMA_API_KEY"

semantic_weight=0 — только BM25; 1 — только визуальные эмбеддинги; между ними — гибридный поиск. space_id выбирает одно пространство; повторяющийся space_ids — несколько. k от 1 до 100.

Ответ содержит results, total, warnings, имя модели и баланс. Результат содержит pdf_id, page_number, score, match_types, snippet, text_url. При include_text=true добавляется text_layer с сохранёнными слоями и координатами. total — число возвращённых результатов, а не размер всей библиотеки. score — ранг гибридного поиска, не вероятность.

Получить слой страницы#

Страницы в API нумеруются с нуля: 0 — первая страница.

curl --get 'http://127.0.0.1:8765/api/pages/12/0/text' \
  --data-urlencode 'q=энергия' \
  -H "X-API-Key: $LOOMA_API_KEY"

Ответ включает has_native_text, has_ocr, checked, coordinate_system и layers. Каждый слой содержит source (native или ocr), text, spans, width, height и сведения о движке. bbox слова имеет вид [x0,y0,x1,y1]: координаты нормализованы относительно страницы, начало в левом верхнем углу. Умножьте X на ширину изображения, Y — на высоту. match отмечает совпадение с q.

Наличие OCR не означает, что собственный текст удалён: оба источника хранятся отдельно. checked=false означает, что проверка собственного текста ещё не сохранена.

Прогресс поиска#

GET /api/search/stream возвращает NDJSON, не SSE: одна JSON-запись на строку. Пустые строки — keepalive. События progress содержат step и state; финальное result — ответ в data; error — описание сбоя.

curl -N --get 'http://127.0.0.1:8765/api/search/stream' \
  --data-urlencode 'q=энергия' \
  --data-urlencode 'semantic_weight=0' \
  -H "X-API-Key: $LOOMA_API_KEY"

Этапы: prepare, text, model, query, visual, rank, results. Не все этапы выполняются для каждого режима. Поток индексации /api/indexing/stream, напротив, использует SSE.

OCR одной страницы#

curl -X POST 'http://127.0.0.1:8765/api/ocr/pages/12/0' \
  -H "X-API-Key: $LOOMA_API_KEY"

Запрос принудительно распознаёт страницу без общей очереди и изменяет сохранённый OCR. Он может выполняться долго. Для массовой обработки используйте POST /api/ocr/enqueue; очереди OCR и извлечения текста имеют разные kind (ocr и text).

API embed-сервера#

curl 'http://127.0.0.1:8766/embedders' \
  -H "Authorization: Bearer $EMBED_API_KEY"
curl 'http://127.0.0.1:8766/embed/queries' \
  -H "Authorization: Bearer $EMBED_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"colqwen3_2b","queries":["солнечная энергия"]}'

Для файлов приложение использует задания:

Метод и путь	Назначение
`POST /document-jobs/{client_id}`	Отправить бинарный файл; параметры `model`, `sha256`, `dpi`, `kind`
`GET /document-jobs/{client_id}`	Получить состояние и готовые порции
`GET /document-jobs/{client_id}/batches/{number}`	Скачать порцию ZIP; отсчёт с нуля
`POST /document-jobs/{client_id}/control`	`{"paused":true}` или `false`
`DELETE /document-jobs/{client_id}`	Подтвердить получение или отменить с очисткой

client_id — 64 шестнадцатеричных символа. Повторное создание того же задания возвращает существующее; для продолжения нужен тот же API-ключ. Исходник передаётся бинарным телом, не multipart. Старые /embed/images и /embed/queries возвращают JSON.

Ошибки#

Проверяйте HTTP-статус и поле detail: 401/403 — доступ, 404 — отсутствующий объект, 409 — конфликт состояния, 422 — неверные параметры, 503 — временная недоступность вычисления. У потокового поиска ошибка после открытия ответа передаётся событием error, поэтому одного HTTP 200 недостаточно.

Нашли неточность? Сообщите на GitHub ↗