API

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

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

1. Ключ

2. Хранилище

3. Ассистенты

4. Лог

5. Аккаунт

1. Ключ (API Key)

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

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

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

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

Пример:

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

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

Запросы к 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": "Test Robot", } ```	[]

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

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

• Метод: PUT;

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

• Параметры:

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

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

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

• Пример:

Запрос	Ответ
```json { "Name": "Test Robot", } ```	[]

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

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

• Метод: POST;

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

• Параметры:

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

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

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

• Пример:

Запрос	Ответ
```json { "text_chunk": "Текстовый чанк", "guid_file": "123e4567-e89b-12d3-a456-426614174000", "metadata": {}, } ```	[]

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

• Эндпоинт: /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, } ```	[]

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

• Эндпоинт: /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. Ассистенты

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

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

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

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

• Метод: POST;

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

• Параметры:

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

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

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

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

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

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

• Пример:

Запрос	Ответ
```json { "messages": [ { "content": "Привет, как дела?", "role": "user", "name": "Иван" }, { "content": "Все хорошо, спасибо!", "role": "system", "name": "Система" } ] "model": "/model-store/meta-llama/Meta-Llama-3-8B-Instruct", "temperature": 0.7, } ```	Ответ будет в формате, который возвращает нейросеть, в зависимости от переданных параметров.

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

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

• Метод: GET;

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

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

• Пример:

Запрос

Ответ

curl -X 'GET' \ 'https://91.206.149.186:3003/v1/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 } ] } ] } ```

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

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

• Метод: GET;

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

• Параметры:

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

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

• Пример:

Запрос

Ответ

curl -X 'GET' \ 'https://91.206.149.186:3003/api/threads/getUpdates?assistant_id=1&offset=0' \ -H 'accept: application/json'

```json { "error": "Licensing error: license is absent, expired, not activated or limits are reached" } или { "result": 1, "data": [ { "id": "1195", "thread_id": "221", "created": "2024-09-11 09:08:48", "updated": "2024-09-11 09:08:48", "content": "{\"type\":\"text\",\"text\":{\"value\":\"привет\",\"annotations\":[]}}", "role": "user", "account_id": "1", "is_deleted": "0", "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 } ] } ```

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

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

• Метод: POST;

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

• Параметры:

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

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

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

• Пример:

Запрос	Ответ
curl -X 'POST' \ 'https://91.206.149.186:3003/api/threads/chat' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "thread_id": 200, "role": "assistant", "content": "Привет! Как я могу помочь вам сегодня?" }'	```json { "result": 1 } ```

4. Лог

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

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

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

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

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

• Эндпоинт: /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", } ```	[]

6. Получение информации о Логе по 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", } ```

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

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

• Метод: POST;

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

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

• Пример:

Запрос	Ответ
/api/log/list	[]

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

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

• Метод: DELETE;

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

• Параметры:

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

• Пример:

Запрос	Ответ
```json { "Time": "1590481487", } ```	[]

5. Аккаунт

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

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

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

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

• Эндпоинт: /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	[]