С чего начать

Раздел предназначен для ботов, импортёров и скриптов синхронизации. Здесь собраны адреса запросов, заголовки и примеры кода. Работа через интерфейс описана в разделах «Пользователю» и «Администратору».

Что можно сделать

Внешняя система работает только с базой знаний и только с теми папками, которые ей разрешили. В этих папках она может:

• получить список доступных ей папок;
• посмотреть содержимое папки и список файлов в ней;
• загрузить файлы — до пятидесяти за один запрос;
• удалить файл;
• попросить портал заново обработать файлы папки.

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

Ключ не позволяет запускать задачи: он принадлежит внешней системе, а не сотруднику, и даёт доступ только к разрешённым папкам. Задачи запускают в пользовательской части портала.

Ключ

Ключ выпускает администратор портала — страница «Система» → «API-ключи», как это делается. Попросите его указать при выпуске все папки, с которыми вы будете работать: набор папок можно поменять потом, но пока папки нет в списке ключа, обращения к ней отклоняются.

Ключ выглядит так:

sk_forge_1f0a3c9d7b2e4a5680c1d2e3f4a5b6c7

Портал показывает его один раз, в момент выпуска, и больше показать не может: у себя он хранит не ключ, а его отпечаток. Потеряли — просите новый.

Адрес и заголовок

Все запросы идут на адрес администраторской части портала — тот же, по которому администратор открывает её в браузере. Спросите его у администратора; ниже он обозначен как https://portal.example.com.

Ключ передаётся в заголовке Authorization:

Authorization: Bearer sk_forge_...

Заголовок обязателен в каждом запросе. Сессионные cookie для этих запросов не нужны и не используются: портал различает вызов по ключу и вход человека в браузер, и часть запросов доступна только одной из этих сторон.

Первый запрос

Идентификаторы папок спрашивать у администратора не нужно — ключ перечисляет свои папки сам:

curl "https://portal.example.com/api/admin/library-folders/mine" \
  -H "Authorization: Bearer sk_forge_..."

Ответ 200:

{
  "data": [
    {
      "id": "6c5a1d1e-2b4f-4d9a-9f7c-8a1b2c3d4e5f",
      "name": "Договоры 2026",
      "description": "Подписанные договоры по годам",
      "type": "files",
      "fileCount": 128,
      "createdAt": "2026-02-18T10:00:00.000Z",
      "updatedAt": "2026-08-30T07:41:12.000Z"
    }
  ],
  "meta": { "total": 1 }
}

В списке — только папки этого ключа; параметра, который бы его расширил, нет. Значение data[].id и есть тот идентификатор папки, который подставляется во все остальные запросы.

Дальше: загрузка файлов, остальные запросы, коды ответов.

На странице «Готовые примеры» есть клиенты на Python и TypeScript, таблица всех восьми запросов и машиночитаемое описание для программы, в которой вы проверяете запросы.

Если ничего не отвечает

• 401 на любой запрос. Ключ не передан, передан не в том виде, отозван или истёк. Заголовок должен начинаться со слова Bearer, а сам ключ — с sk_forge_.
• 403 там, где ожидался список. Запрос дошёл, но он не для ключей: часть запросов портал принимает только от администратора в браузере.
• 403 с сообщением «Доступ к панели администратора запрещён с вашего IP». Это не про ключ: администраторская часть портала может быть настроена так, что принимает обращения только с известных адресов, и ваш запрос отклонён раньше, чем портал посмотрел на ключ. Если программа работает на другом сервере, попросите администратора добавить её адрес.
• Непонятно, дошли ли запросы. Каждое обращение по ключу видно администратору: кнопка «Логи» в строке ключа открывает журнал вызовов с кодом ответа, папкой и числом файлов по каждому запросу.