API#

Экран API представляет собой справочник по доступным API-методам в формате Swagger.

На экране API теперь доступны три вкладки:

1. Swagger
   В этом подразделе открывается интерактивная документация API. Пользователь может посмотреть доступные запросы, их параметры, структуру ответа и использовать Swagger как справочник для проверки интеграций.

Документация также доступна по ссылке:

2. ReDoc
   В этом подразделе открывается альтернативное представление API-документации.

ReDoc удобен для чтения: в нем проще просматривать описание методов, схемы данных и обязательные поля запросов.

3. Токен
   Подраздел Токен предназначен для управления токенами доступа к API в Sherpa AI Server.

   На экране API токены отображается таблица со списком созданных API-токенов.

Для каждого токена в списке показаны:

В каждой строке справа доступны следующие действия с токеном:

• обновить / перевыпустить токен;
• редактировать токен;
• удалить токен.

При перевыпуске токена прежний секрет сразу перестает работать. Новый секрет показывается один раз. Важно скопировать его и обновить все интеграции, которые используют этот токен. Если новое значение не сохранено, токен нужно перевыпустить еще раз.

Над таблицей расположены кнопки:

• Создать — открывает всплывающее окно для создания нового API токена.

В окне нужно указать название API токена и выбрать Роли из выпадающего списка. Оба поля являются обязательными.

Также можно настроить срок действия токена. Если отметить чекбокс "Бессрочно", токен будет создан без даты окончания действия. Если чекбокс не выбран, в поле "Срок действия" указывается дата и время, до которых токен будет активен. Для выбора даты доступна иконка календаря.

Внизу окна расположены две кнопки: "Отмена" закрывает окно без сохранения, а "Создание" создает новый API токен. Кнопка создания становится доступной после заполнения обязательных полей.

После создания необходимо сохранить показанное значение токена в защищенном месте и можно использовать его только в интеграциях с назначенными ему Ролями.

• Обновить — перезагружает список токенов на экране API токены.

Запросы Swagger без параметров в теле#

Для выполнения запросов необходим действующий API-токен с правами Роли на выбранное действие или авторизованная сессия. Запросы выполняются в пределах текущего Аккаунта. Поле account_guid указывать не требуется: сервер определяет Аккаунт по токену или сессии.

До выполнения запроса необходимо проверить его условия. Асинхронный запуск требует статуса waiting и ответа Модели. Запуски с внешним ответом выполняются через API-клиент по отдельному жизненному циклу. Удаление следует проверять только на созданных для этой проверки объектах в отдельном Аккаунте. Папку объектов с подпапками удалить нельзя.

Для выполнения запроса через Swagger необходимо выполнить следующие действия:

1. Можно открыть вкладку "Swagger". Для API-токена необходимо нажать на кнопку "Authorize" и необходимо указать его значение. При работе через сессию необходимо войти в Sherpa AI Server.

2. Необходимо выбрать метод и необходимо нажать на кнопку "Try it out". Необходимо указать GUID существующих объектов в параметрах пути.

3. Для POST /api/v1/threads/{thread_guid}/runs/{run_guid}/execute_async необходимо оставить в поле "Request body" пустой JSON-объект:

   Копировать

   {}
   

   Для этого запроса необходим заголовок Content-Type: application/json.

4. Для следующих методов удаления тело запроса необязательно. Можно отправить запрос без тела и без заголовка Content-Type:

   • DELETE /api/v1/folders/{folder_guid}/files/{file_guid};
   • DELETE /api/v1/folders/{folder_guid};
   • DELETE /api/v1/object_folders/{object_folder_guid}.

   Прежние JSON-запросы, включая {}, также поддерживаются. Для JSON-тела необходимо указать заголовок Content-Type: application/json.

5. Необходимо нажать на кнопку "Execute" и необходимо проверить код ответа.

При успешном асинхронном запуске сервер возвращает 200 и статус in_progress. Завершение генерации происходит позже. Для удаления успешный ответ — 204 без тела. Удаление следует проверять на тестовых объектах.

При ответе 403 необходимо проверить авторизацию и права Роли. При ответе 404 необходимо проверить GUID и принадлежность объектов текущему Аккаунту. У запуска должен быть статус waiting. Запуск с внешним ответом завершается через API-клиент. Папку объектов с подпапками удалить нельзя.

При ответе 422 необходимо проверить наличие реквизитов авторизации, формат отправленного JSON-тела и заголовок Content-Type.