API

Для интеграции с внешними системами (при необходимости), Sherpa AI Server предлагает набор инструментов для обмена данными через API.

Раздел "API" представляет собой справочник по доступным API-методам в формате Swagger. В данном разделе представлены следующие вкладки:

  1. Ключ

  2. Хранилище

  3. Лог

  4. Учетные записи

  5. ИИ Сервер

1. Ключ (API Key)

В этом разделе пользователь может увидеть свой уникальный ключ доступа к API в поле Ключ. Также при изменении данного поля необходимо подтвердить действие нажатием одной из кнопок:

(Assignment) - Назначить новый ключ;

(Refresh) - Обновить текущий ключ.

Ниже расположено информационное поле "Authorization", которое используется для предоставления токена доступа, подтверждающего, что Пользователь имеет право на выполнение запрашиваемого действия.

Пример:

“Bearer” — тип токена,

“Y2Y5M2U3OGUtMDk1ZC00MGNjLTkwNWUtZTYyNjUwM_______” — сам токен, который сервер будет использовать для идентификации Пользователя.

Запросы к API осуществляются с обязательной передачей API Key, который хранится в настройках Учетной записи. Подробные примеры запросов приведены в разделе по каждому блоку отдельно.

Коды ответов:

2. Хранилище

Позволяет управлять Хранилищем. Пользователь может создавать новые папки и файлы, получать информацию о папках и файлах, обновлять информацию о папках и файлах, а также удалять папки и файлы.

На данной странице располагаются вкладки с методами:

По клику на иконку справа от нужного метода, раскрывается соответствующая страница:

1. Создание новой папки

  • Эндпоинт: /api/folders/create

  • Метод: POST;

  • Авторизация: обязательна;

  • Параметры:

    • Name: Название новой папки;

    • Description: Описание для новой папки.

  • Пример:

Запрос

Ответ

```json

{

"Name": "New Folder 1",

}

```

[

"guid": "16f94238-ede9-435b-a001-1489b32e7dc2",

]

2. Получение информации о папке по GUID

  • Эндпоинт: /api/folders/read/{guid}

  • Метод: GET;

  • Авторизация: обязательна;

  • Параметры:

    • Guid (обязательно): Guid новой папки.

  • Пример:

Запрос

Ответ

/api/folders/read/4dd6abf4-daa3-45d0-9347-6780c2b46b0c

```json

{

"id": 1,

"guid": "4dd6abf4-daa3-45d0-9347-6780c2b46b0c",

"name": "Test Folder 1",

"description": "My new test Folder",

"created": "2023-01-29 10:29:25",

"updated": "2023-01-29 10:44:09",

"is_deleted": 0,

"account_id": 1,

}

```

3. Получение списка папок, связанных с GUID

  • Эндпоинт: /api/folders/list

  • Метод: GET;

  • Авторизация: обязательна;

  • Параметры: нет;

  • Пример:

Запрос

Ответ

/api/folders/list

```json

[

{

"id": 1,

"guid": "4dd6abf4-daa3-45d0-9347-6780c2b46b0c",

"name": "Test Folder 1",

"description": "My new test Folder",

"created": "2023-01-29 10:29:25",

"updated": "2023-01-29 10:44:09",

"is_deleted": 0,

"account_id": 1,

},

{

"id": 2,

"guid": "4dd6abf4-daa3-45d0-9347-6780c2b46a3c",

"name": "Test Folder 2",

"description": "My another new test Folder",

"created": "2023-10-05 10:59:41",

"updated": "2023-10-05 10:59:41",

"is_deleted": 0,

"account_id": 1,

}

]

```

4. Обновление информации о папке по GUID

  • Эндпоинт: /api/folders/update

  • Метод: PUT;

  • Авторизация: обязательна;

  • Параметры:

    • Guid (обязательно): Guid папки;

    • Name: Название нового папки;

    • Description: Описание для новой папки.

  • Пример:

Запрос

Ответ

```json

{

"Guid": "554ab883-1f82-48e1-bb12-5049002e7d70",

"Name": "New Folder Name",

}

```

[]

5. Создание нового файла

  • Эндпоинт: /api/files/create

  • Метод: POST;

  • Авторизация: обязательна;

  • Параметры:

    • name (обязательно): Имя файла;

    • name_new (обязательно): Новое имя файла;

    • description (обязательно): Описание файла;

    • folder_id (обязательно): GUID или путь к папке, в которую будет добавлен файл;

    • Metadata (обязательно): Метаданные файла;

    • file (обязательно): Файл в бинарном формате, либо в кодировках Base16 / Base32.

  • Пример:

Запрос

Ответ

```json

{

"name": "example.txt",

"name_new": "example_new.txt",

"description": "Описание файла",

"folder_id": "123e4567-e89b-12d3-a456-426614174000",

"Metadata": {},

"file": "file_content",

}

```

[]

6. Получение информации о файле по GUID

  • Эндпоинт: /api/files/read/{guid}

  • Метод: GET;

  • Авторизация: обязательна;

  • Параметры:

    • Name (обязательно): Название нового файла.

  • Пример:

Запрос

Ответ

```json

{

"Name": "example.txt",

}

```

[]

7. Обновление информации о файле по GUID

  • Эндпоинт: /api/files/update

  • Метод: PUT;

  • Авторизация: обязательна;

  • Параметры:

    • Name (обязательно): Название нового файла;

    • folder_guid: ID папки, в которую необходимо добавить файл;

    • file: Файл в бинарном формате, либо в кодировках Base16 / Base32;

  • Пример:

Запрос

Ответ

```json

{

"Name": "example.txt",

}

```

[]

8. Удаление файла/папки

  • Эндпоинт: /api/files/delete

  • Метод: DELETE;

  • Авторизация: обязательна;

  • Параметры:

    • file_folder_guid (обязательно): GUID или путь к файлу или папке;

    • type_processing (обязательно): Тип обработки. Возможные значения: 0 = Auto, 1 = File, 2 = Directory.

  • Пример:

Запрос

Ответ

```json

{

"file_folder_guid": "123e4567-e89b-12d3-a456-426614174000",

"type_processing": 0,

}

```

[]

9. Загрузка файла

  • Эндпоинт: /api/files/uploadfile

  • Метод: POST;

  • Авторизация: обязательна;

  • Параметры:

    • file (обязательно): Файл для загрузки;

    • folder_id: ID папки, в которую необходимо добавить файл;

    • metadata: Метаданные файла.

  • Пример:

Запрос

Ответ

```json

[

"file": "@/path/to/Document.pdf",

"folder_id=4b5f2f2e-1c8a-4d3c-9b2a-b0f7d9a0a123",

"metadata":

{

"source": "kb",

"tags": ["policy","2025"]

} ]

```

```json

{

"id": 123,

"object": "file",

"purpose": "assistants",

"filename": "Document.pdf",

"bytes": 1048576,

"created_at": 1726742400,

"status": "processed",

"status_details": "Indexed",

"tools_type": "retrieval"

} ```

10. Скачивание файла по GUID

  • Эндпоинт: /api/files/download/{guid}

  • Метод: GET;

  • Авторизация: обязательна;

  • Параметры:

    • filename (обязательно): Имя файла.

  • Пример:

Запрос

Ответ

```json

{ "filename": "example.txt", } ```

```json

{

"result": "0"

}

```

3. Лог

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

В верхней части страницы располагается таблица со всеми уровнями Логирования:

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

По клику на иконку справа от нужного метода, раскрывается соответствующая страница:

1. Создание Лога

  • Эндпоинт: /api/log/create

  • Метод: POST;

  • Авторизация: обязательна;

  • Параметры:

    • RobotGUID: GUID Робота;

    • ProcessVersionGUID: GUID версии Процесса;

    • JobGUID: GUID Работы;

    • Level: уровень Логирования;

Message (обязательно): текст Лога.

  • Пример:

Запрос

Ответ

```json

{

"RobotGUID": "16f94238-ede9-435b-a001-1489b32e7dc2",

"ProcessVersionGUID": "c39713ea-d8b9-4669-976e-5ff39677dc64",

"JobGUID": "70ce211b-3c9a-48f6-8e71-11088b41b825",

"Level": 1,

"Message": "no message",

}

```

[]

2. Получение информации о Логе по GUID

  • Эндпоинт: /api/log/read/{guid}

  • Метод: GET;

  • Авторизация: обязательна;

  • Параметры:

    • Guid (обязательно): Guid Лога.

  • Пример:

Запрос

Ответ

/api/log/read/c39713ea-d8b9-4669-976e-5ff39677dc64

```json

{

"id": "1",

"guid": "16f94238-ede9-435b-a001-1489b32e7dc2",

"robot_id": "16",

"process_version_id": "39",

"job_id": "70",

"Level": 1,

"Message": "no message",

"created_at": "2023-09-17 15:39:06",

"updated_at": "2023-09-17 16:39:06",

}

```

3. Получение списка файлов, связанных с GUID

  • Эндпоинт: /api/log/list

  • Метод: POST;

  • Авторизация: обязательна;

  • Параметры: нет.

  • Пример:

Запрос

Ответ

/api/log/list

[]

4. Удаление Логов, принадлежащих текущей учетной записи и созданных до выбранного времени

  • Эндпоинт: /api/log/purge

  • Метод: DELETE;

  • Авторизация: обязательна;

  • Параметры:

    • Time (обязательно): временная метка в формате Unix (Unix timestamp);

  • Пример:

Запрос

Ответ

```json

{

"Time": "1590481487",

}

```

[]

4. Учетные записи

Позволяет управлять Учетными записями. Пользователь может создавать новую Учетную запись, получить информацию об Учетной записи, обновить информацию об Учетной записи, а также удалить Учетную запись.

На данной странице располагаются вкладки с методами:

По клику на иконку справа от нужного метода, раскрывается соответствующая страница:

  • Эндпоинт: /api/account/create

  • Метод: POST;

  • Авторизация: обязательна;

  • Параметры:

    • Login (обязательно) — Логин для новой Учетной записи;

    • Password (обязательно) — Пароль для новой Учетной записи;

    • FirstName — Имя для новой Учетной записи;

    • LastName — Фамилия для новой Учетной записи;

    • Email — E-mail для новой Учетной записи;

    • Phone — Телефон для новой Учетной записи;

    • Company — Компания для новой Учетной записи;

    • Department — Отдел для новой Учетной записи.

  • Пример:

Запрос

Ответ

```json

{

"Login": "New Test Account",

"Password": "newPassword123",

}

```

["guid": "c39713ea-d8b9-4669-976e-5ff39677dc64"]

2. Получение информации об Учетной записи по GUID

  • Эндпоинт: /api/account/read/{guid}

  • Метод: GET;

  • Авторизация: обязательна;

  • Параметры:

    • GUID (обязательно): GUID Учетной записи.

  • Пример:

Запрос

Ответ

/api/account/read/c39713ea-d8b9-4669-976e-5ff39677dc64

```json

{

"id": "5",

"guid": "554ab883-1f82-48e1-bb12-5049002e7d70",

"login": "new Account",

"password": "123455678",

"first name": "Vasya",

"last name": "Ivanov",

}

```

3. Обновление информации об Учетной записи по GUID

  • Эндпоинт: /api/account/update

  • Метод: PUT;

  • Авторизация: обязательна;

  • Параметры:

    • Guid (обязательно) — GUID Учетной записи для обновления;

    • Login — Логин Учетной записи для обновления;

    • Password — Пароль Учетной записи для обновления;

    • FirstName — Имя в Аккаунте для обновления;

    • LastName — Фамилия Учетной записи для обновления;

    • Email — E-mail Учетной записи для обновления;

    • Phone — Телефон в Аккаунте для обновления;

    • Company — Компания Учетной записи для обновления;

    • Department — Отдел Учетной записи для обновления.

  • Пример:

Запрос

Ответ

```json

{

"Guid": "554ab883-1f82-48e1-bb12-5049002e7d70",

"Login": "Test Account",

}

```

[]

4. Удаление Учетной записи по GUID

  • Эндпоинт: /api/account/delete/{guid}

  • Метод: DELETE;

  • Авторизация: обязательна;

  • Параметры:

    • Guid (обязательно): Guid Учетной записи;

  • Пример:

Запрос

Ответ

/api/account/delete/554ab883-1f82-48e1-bb12-5049002e7d70

[]

5. ИИ Сервер

Позволяет управлять нейросетями. Пользователь может принять JSON-объект и вернуть ответ от нейросети, получить информацию о текущей используемой модели, получить ответ от Ассистента или отправить сообщение в чат.

По клику на иконку справа от нужного метода, раскрывается соответствующая страница:

1. Добавление текстовых чанков к существующему файлу

  • Эндпоинт: /api/files/addchunk

  • Метод: POST;

  • Авторизация: обязательна;

  • Параметры:

    • text_chunk (обязательно): Текстовый чанк;

    • guid_file (обязательно): GUID файла или путь к файлу;

    • metadata (обязательно): Метаданные чанка.

  • Пример:

Запрос

Ответ

```json

{

"text_chunk": "Текстовый чанк",

"guid_file": "123e4567-e89b-12d3-a456-426614174000",

"metadata": {},

}

```

[]

2. Нахождение эмбеддингов по заданному тексту

  • Эндпоинт: /api/files/search

  • Метод: GET;

  • Авторизация: обязательна;

  • Параметры:

    • text_for_search (обязательно): Текст для поиска;

    • n_top (обязательно): Количество топовых результатов;

    • files_ids (обязательно): JSON строка со списком GUID или путей к файлам;

    • folder_ids (обязательно): JSON строка со списком GUID или путей к папкам;

    • enable_subfolders (обязательно): Включение подпапок. Возможные значения: 0 = False, 1 = True.

  • Пример:

Запрос

Ответ

```json

{

"text_for_search": "пример текста",

"n_top": 5,

"files_ids": "[\"123e4567-e89b-12d3-a456-426614174000\", \"123e4567-e89b-12d3-a456-426614174001\"]",

"folder_ids": "[\"123e4567-e89b-12d3-a456-426614174002\", \"123e4567-e89b-12d3-a456-426614174003\"]",

"enable_subfolders": 1

}

```

[]

3. Получение ответа от нейросети

  • Эндпоинт: /api/threads/message

  • Метод: POST;

  • Авторизация: обязательна;

  • Параметры:

    • messages (обязательно): Массив объектов, каждый из которых представляет сообщение;

    • content: Текст сообщения;

    • role: Роль отправителя сообщения. Возможные значения: system, user;

    • name: Имя отправителя сообщения;

    • temperature: Число с плавающей точкой, определяющее степень случайности в ответах нейросети. Значение по умолчанию: 0.7;

    • model (обязательно): Строка, указывающая путь к модели, например, /model-store/meta-llama/Meta-Llama-3-8B-Instruct;

    • assistant_id: Идентификатор ассистента;

    • thread_id: Идентификатор чата;

    • info: Системная информация.

  • Пример:

Запрос

Ответ

```json

{

"messages": [

{

"content": "Привет, как дела?",

"role": "user",

"name": "Иван"

},

{

"content": "Все хорошо, спасибо!",

"role": "system",

"name": "Система"

}

]

"model": "/model-store/meta-llama/Meta-Llama-3-8B-Instruct",

"temperature": 0.7,

"assistant_id": "123e4567-e89b-12d3-a456-426614174000",

"thread_id": 200

}

```

[]

4. Получение информации о текущей используемой модели

  • Эндпоинт: /api/threads/models

  • Метод: GET;

  • Авторизация: обязательна;

  • Параметры: нет.

  • Пример:

Запрос

Ответ

/api/threads/models

```json

{

"object": "list",

"data": [

{

"id": "/model-store/meta-llama/Meta-Llama-3-8B-Instruct",

"object": "model",

"created": 1735113788,

"owned_by": "vllm",

"root": "/model-store/meta-llama/Meta-Llama-3-8B-Instruct",

"parent": null,

"permission": [

{

"id": "modelperm-d7ddf889e9aa423b9949d1cdc551ff21",

"object": "model_permission",

"created": 1735113788,

"allow_create_engine": false,

"allow_sampling": true,

"allow_logprobs": true,

"allow_search_indices": false,

"allow_view": true,

"allow_fine_tuning": false,

"organization": "*",

"group": null,

"is_blocking": false

}

]

}

]

}

```

5. Получение сообщения от Ассистента

  • Эндпоинт: /api/threads/getUpdates

  • Метод: GET;

  • Авторизация: обязательна;

  • Параметры:

    • assistant_id (обязательно): Идентификатор ассистента;

    • offset: Идентификатор сообщения, с которого необходимо получить список сообщений;

    • thread_id (обязательно): Идентификатор чата.

  • Пример:

Запрос

Ответ

/api/threads/getUpdates?assistant_id=123e4567-e89b-12d3-a456-426614174000&offset=0&thread_id=221

```json

{

"error": "Licensing error: license is absent, expired, not activated or limits are reached"

}

или

{

"result": 1,

"data": [

{

"id": "1195",

"content": "{\"type\":\"text\",\"text\":{\"value\":\"привет\",\"annotations\":[]}}",

"account_id": "1",

"is_deleted": "0",

"role": "user",

"thread_id": "221",

"created": "2024-09-11 09:08:48",

"updated": "2024-09-11 09:08:48",

"assistant_id":"123e4567-e89b-12d3-a456-426614174000",

"info": "{\"TestPrm\":\"TestData\"}",

"folder_id": "[]",

"file_id": "[]",

"update_id": null

},

{

"id": "1196",

"thread_id": "221",

"created": "2024-09-11 09:08:49",

"updated": "2024-09-11 09:08:49",

"content": "{\"type\":\"text\",\"text\":{\"value\":\"Привет! Рад видеть вас! Как я могу помочь вам сегодня?\",\"annotations\":[]}}",

"role": "assistant",

"account_id": "1",

"is_deleted": "0",

"folder_id": null,

"file_id": null,

"update_id": null

}

]

}

```

6. Отправка сообщения в чат

  • Эндпоинт: /api/threads/chat

  • Метод: POST;

  • Авторизация: обязательна;

  • Параметры:

    • thread_id (обязательно): Идентификатор чата;

    • role (обязательно): Роль отправителя сообщения (например, assistant);

    • content (обязательно): Текст сообщения;

    • assistant_id: Идентификатор ассистента;

    • model_id: Идентификатор группы моделей;

    • temperature: Число с плавающей точкой, определяющее степень случайности в ответах нейросети. Значение по умолчанию: 0.7;

    • prompt: Начальный контекст или инструкция для модели;

    • title: Заголовок чата;

    • file_id: Список ID файлов, прикрепляемых к сообщению (JSON-массив);

    • folder_id: Список ID папок (или объектов с id), прикрепляемых к сообщению (JSON-массив),

    • info: Системная информация.

  • Пример:

Запрос

Ответ

```json

{ "thread_id": 200, "role": "assistant", "content": "Привет! Как я могу помочь вам сегодня?", "file_id": [101, 102], "folder_id": [201, 202],

"info": "" } ```

```json

[

"result": 1, "data": { "message_id": 1234,

"thread_id": 200, "file_id": [101, 102], "folder_id": [201, 202],

"info": "" }

]

```

PreviousЛицензииNextРабота Sherpa AI Server в связке с Sherpa Designer

Last updated