Папки и файлы

Список папок, содержимое, постраничный список файлов, удаление и повторная обработка.

Все запросы этого раздела требуют того же заголовка Authorization, что и загрузка, и работают только с папками, разрешёнными ключу.

Список своих папок

GET /api/admin/library-folders/mine

Отдаёт только папки этого ключа. Пример ответа — в начале раздела.

Одна папка

GET /api/admin/library-folders/<id папки>

Возвращает название, описание и число файлов. Запрос можно использовать для проверки ключа и доступа к папке.

Содержимое папки

GET /api/admin/library-folders/<id папки>/contents?path=2026/01

Возвращает подпапки и файлы по указанному пути. Без path — корень папки. Постранично: page (по умолчанию 1) и pageSize (по умолчанию 50, потолок 200).

Используйте запрос для обхода дерева. Если нужен плоский список файлов с состоянием обработки — следующий запрос.

Список файлов

GET /api/admin/library-folders/<id папки>/files?page=1&pageSize=50

Параметр	Значение
`page`	Номер страницы, с единицы. По умолчанию 1
`pageSize`	Размер страницы. По умолчанию 20, потолок 100 — больше запросить нельзя, значение просто урежется
`search`	Подстрока. Ищет по имени файла и по краткому описанию, которое портал составил при обработке
`path`	Точный путь подпапки. Пустая строка — только корень
`sortBy`	`filename` или `indexStatus`. Другое значение молча заменяется на `filename`
`sortOrder`	`asc` или `desc`

Ответ:

{
  "data": [
    {
      "linkId": "0a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7081",
      "id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "filename": "договор-2026-014.pdf",
      "fileSize": 384021,
      "mimeType": "application/pdf",
      "indexStatus": "done",
      "indexError": null,
      "createdAt": "2026-08-30T07:41:12.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "totalPages": 3 }
}

indexStatus — состояние обработки файла: pending (в очереди), processing (разбирается), done (готов), failed (разобрать не удалось, причина — в indexError), flagged (файл отложен на проверку администратором). На экране те же состояния подписаны по-русски и разобраны в справочнике статусов.

flagged — то, с чем внешняя система сталкивается чаще человека. Файлы, загруженные ключом, портал считает недоверенными и просматривает на текст, похожий на постороннюю инструкцию. Нашёл — файл откладывается целиком: задачам он недоступен, и снять пометку может только администратор. Причина стоит в indexError. Ошибкой загрузки это не является: 201 вы уже получили, а состояние появилось позже.

В строке два идентификатора с разным назначением. id обозначает сам файл и подставляется в запрос удаления. linkId обозначает связь файла с папкой, поэтому у одного файла он различается в разных папках.

Удаление файла

DELETE /api/admin/library-folders/<id папки>/files/<id файла>

Убирает файл из этой папки. Если он лежал ещё где-то, там он останется; если это была последняя папка, портал уберёт его у себя совсем.

Ответ — 200 и {"data": {"success": true}}.

Очистить папку целиком одним запросом ключом нельзя: такой запрос существует, но открыт только администратору в браузере, а ключу отвечает 403.

Повторная обработка

POST /api/admin/library-folders/<id папки>/reindex-failed
POST /api/admin/library-folders/<id папки>/reindex-all

Первый запрос ставит в очередь заново только те файлы, обработка которых закончилась ошибкой. Второй — все файлы папки.

Оба отвечают числом затронутых файлов:

{ "data": { "updated": 12 } }

reindex-all заново читает каждый файл и создаёт заметную нагрузку для большой папки. Если нужно повторить обработку нескольких файлов после сбоя, используйте reindex-failed.

Чего ключом сделать нельзя

Эти запросы существуют, но открыты только администратору в браузере. Ключу они отвечают 403 — не потому, что папка не та, а потому, что запрос не для ключей:

создать, переименовать, описать или удалить папку;
удалить из папки все файлы разом;
завести или переименовать подпапку;
всё, что лежит за пределами базы знаний.

Если что-то пошло не так

404 на папку, которая только что была в /mine. Папку удалили. Список ключа при этом не обновляется сам — попросите администратора поправить набор папок.
403 на запрос, который вчера работал. Администратор убрал папку из списка ключа; изменение действует со следующего запроса.
search ничего не находит, хотя файл на месте. Поиск идёт по имени и по краткому описанию файла. Описание появляется только после успешной обработки — у файла в состоянии pending его ещё нет.
Файл удалён, а задачи всё равно его находят. Проверьте, не лежит ли он ещё в другой папке базы знаний, привязанной к тому же типу задачи.

На этой странице