Публичный API

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

Аутентификация

Все запросы к публичному API требуют аутентификации через API-ключ проекта. Ключ передается в заголовке Authorization в формате Bearer:

Authorization: Bearer lia_live_...

Создание ключа

Откройте Настройки проекта → вкладка API ключи
Нажмите Создать ключ
Укажите название, уровень доступа и (опционально) срок действия
Скопируйте ключ — он показывается только один раз

Уровни доступа (scopes)

При создании ключа выберите один из пресетов или настройте права вручную:

Пресет	Права	Описание
Только чтение	`workflows.read`, `executions.read`, `events.subscribe`	Просмотр процессов и выполнений
Выполнение	Все из «Только чтение» + `workflows.execute`, `workflows.stream`	Запуск процессов
Полный доступ	`*`	Все операции

Все доступные права

Scope	Описание
`workflows.read`	Список и детали опубликованных процессов
`workflows.execute`	Синхронное выполнение процессов
`workflows.stream`	Стриминг выполнения (SSE)
`executions.read`	Получение статуса выполнения
`executions.stop`	Остановка выполнения
`executions.approve`	Подтверждение шагов (HITL)
`executions.reject`	Отклонение шагов (HITL)
`events.subscribe`	Подписка на SSE-события выполнения
`*`	Все права

Управление ключами

Ротация: Создаёт новый ключ с теми же правами. Старый ключ продолжает работать ещё 24 часа (grace period)
Отзыв: Немедленно деактивирует ключ
Срок действия: Ключ может иметь дату истечения, после которой перестаёт работать

Безопасность

Храните API-ключ в безопасном месте
Не встраивайте его в клиентский JavaScript-код
Используйте серверную прокси-логику для вызова API из фронтенда
Выдавайте ключам минимально необходимые права
Используйте ротацию вместо ручной пересоздания ключей

Базовый URL

https://<ваш-домен>/api/v1/published

Эндпоинты

Список рабочих процессов

Получение списка всех рабочих процессов в активной публикации.

GET /api/v1/published/workflows

Ответ:

{
  "workflows": [
    {
      "id": "wf_abc123",
      "name": "Обработка заявки",
      "description": "Процесс обработки входящей заявки"
    }
  ],
  "publication_id": "pub_xyz789",
  "project_id": "prj_def456"
}

Информация о рабочем процессе

Получение деталей конкретного рабочего процесса.

GET /api/v1/published/workflows/{workflow_id}

Ответ:

{
  "id": "wf_abc123",
  "name": "Обработка заявки",
  "description": "Процесс обработки входящей заявки",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-20T14:00:00Z"
}

Выполнение рабочего процесса (блокирующее)

Запуск рабочего процесса и ожидание результата. Запрос блокируется до завершения выполнения.

POST /api/v1/published/workflows/{workflow_id}/execute

Тело запроса:

{
  "input": {
    "message": "Текст запроса пользователя",
    "custom_field": "значение"
  },
  "user_id": "external_user_123",
  "thread_id": "thread_abc",
  "initial_memory": {
    "name": "Иван",
    "phone": "+79991234567"
  },
  "callback_url": "https://example.com/webhook",
  "webhook_secret": "my_secret_key",
  "overrides": {
    "node_5": {
      "temperature": 0.3
    }
  }
}

Параметр	Тип	Обязательный	Описание
`input`	object	Нет	Входные данные для рабочего процесса. Передается в ноду «Старт»
`user_id`	string	Да	Внешний идентификатор пользователя. Используется для изоляции памяти между пользователями
`thread_id`	string	Нет	Идентификатор потока (сессии). Позволяет продолжить диалог с сохранением контекста
`initial_memory`	object	Нет	Key-value пары для предзаполнения пользовательской памяти перед выполнением
`callback_url`	string	Нет	URL вебхука для получения результата по завершении
`webhook_secret`	string	Нет	Секрет для подписи вебхука (HMAC-SHA256)
`overrides`	object	Нет	Переопределение параметров нод: `{node_id: {param: value}}`

Ответ:

{
  "execution_id": "exec_abc123",
  "thread_id": "thread_abc",
  "status": "completed",
  "output": "Ответ агента на запрос пользователя",
  "error": null,
  "elapsed_time": 2.451,
  "total_steps": 3,
  "created_at": "2025-01-20T14:00:00Z",
  "finished_at": "2025-01-20T14:00:02Z"
}

Поле	Описание
`execution_id`	Уникальный ID выполнения
`thread_id`	ID потока (может быть сгенерирован автоматически)
`status`	Статус: `completed`, `failed`, `interrupted`
`output`	Результат выполнения (текст ответа или структурированные данные)
`error`	Описание ошибки (если `status` = `failed`)
`elapsed_time`	Время выполнения в секундах
`total_steps`	Количество выполненных шагов (нод)
`created_at`	Время начала выполнения
`finished_at`	Время завершения

Стриминг рабочего процесса (SSE)

Запуск рабочего процесса с потоковой передачей результатов через Server-Sent Events.

POST /api/v1/published/workflows/{workflow_id}/stream

Тело запроса аналогично эндпоинту /execute.

Заголовки ответа:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

Типы событий:

Событие	Описание
`start`	Начало выполнения
`token`	Токен текста от языковой модели (для потоковой генерации)
`tool_call`	Вызов инструмента (функции или MCP-инструмента)
`agent_handoff`	Передача управления другому агенту
`node_update`	Обновление статуса ноды
`image`	Сгенерированное изображение
`error`	Ошибка выполнения
`complete`	Завершение выполнения

Формат события:

event: token
data: {"content": "Здравст"}

event: token
data: {"content": "вуйте!"}

event: complete
data: {"output": "Здравствуйте!", "execution_id": "exec_abc123", "status": "completed"}

Статус выполнения

Получение статуса и результата выполнения по ID (polling).

GET /api/v1/published/executions/{execution_id}

Ответ:

{
  "execution_id": "exec_abc123",
  "workflow_id": "wf_abc123",
  "thread_id": "thread_abc",
  "status": "completed",
  "output": "Ответ агента",
  "error": null,
  "elapsed_time": 2.451,
  "total_steps": 3,
  "created_at": "2025-01-20T14:00:00Z",
  "finished_at": "2025-01-20T14:00:02Z",
  "pending_approval": null
}

Если процесс остановлен на шаге подтверждения (Human-in-the-loop), поле pending_approval содержит:

{
  "pending_approval": {
    "approval_id": "apr_abc123",
    "message": "Подтвердите отправку заявки",
    "node_id": "node_7"
  }
}

Подписка на события выполнения (SSE)

Подписка на обновления жизненного цикла выполнения (статус, подтверждение, завершение).

GET /api/v1/published/executions/{execution_id}/events

Использует паттерн Subscribe-then-Fetch: если выполнение уже завершено, возвращает текущий статус и закрывает соединение.

Остановка выполнения

POST /api/v1/published/executions/{execution_id}/stop

Останавливает выполнение и помечает его как cancelled. Можно остановить только выполнения со статусом queued или running.

Ответ:

{
  "execution_id": "exec_abc123",
  "status": "cancelled"
}

Подтверждение шага (Human-in-the-loop)

Если рабочий процесс содержит ноду «Подтверждение», выполнение может быть приостановлено в ожидании одобрения.

Одобрить:

POST /api/v1/published/executions/{execution_id}/approve

{
  "feedback": "Одобрено, отправляйте"
}

Отклонить:

POST /api/v1/published/executions/{execution_id}/reject

{
  "feedback": "Неверные данные клиента"
}

Вебхуки

Если при запуске рабочего процесса указан callback_url, платформа отправит POST-запрос с результатом на этот URL после завершения выполнения.

При указании webhook_secret тело запроса подписывается HMAC-SHA256, и подпись передается в заголовках для верификации.

Коды ошибок

Код	Описание
`401`	Невалидный, отозванный или истёкший API-ключ, либо отсутствует заголовок Authorization
`403`	API-ключ не имеет необходимых прав (scope) для данного эндпоинта
`400`	У проекта нет активной публикации
`404`	Рабочий процесс или выполнение не найдены
`429`	Превышен лимит запросов (rate limit)
`503`	Сервис выполнения недоступен
`500`	Внутренняя ошибка выполнения

Примеры

cURL

# Список рабочих процессов
curl -X GET "https://example.com/api/v1/published/workflows" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Выполнение рабочего процесса
curl -X POST "https://example.com/api/v1/published/workflows/wf_abc123/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {"message": "Привет, запиши меня на стрижку на завтра"},
    "user_id": "client_456",
    "thread_id": "session_789"
  }'

# Стриминг
curl -X POST "https://example.com/api/v1/published/workflows/wf_abc123/stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "input": {"message": "Какие услуги доступны?"},
    "user_id": "client_456"
  }'

Python

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://example.com/api/v1/published"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# Блокирующее выполнение
response = requests.post(
    f"{BASE_URL}/workflows/wf_abc123/execute",
    headers=HEADERS,
    json={
        "input": {"message": "Привет!"},
        "user_id": "client_456",
        "thread_id": "session_789",
    },
)

result = response.json()
print(result["output"])
print(f"Выполнено за {result['elapsed_time']} сек.")

import requests

# SSE-стриминг
response = requests.post(
    f"{BASE_URL}/workflows/wf_abc123/stream",
    headers=HEADERS,
    json={
        "input": {"message": "Расскажи о компании"},
        "user_id": "client_456",
    },
    stream=True,
)

for line in response.iter_lines():
    if line:
        decoded = line.decode("utf-8")
        if decoded.startswith("data: "):
            print(decoded[6:])

# Потоки (диалог с сохранением контекста)
thread_id = "conversation_001"

# Первое сообщение
r1 = requests.post(
    f"{BASE_URL}/workflows/wf_abc123/execute",
    headers=HEADERS,
    json={
        "input": {"message": "Меня зовут Анна"},
        "user_id": "client_456",
        "thread_id": thread_id,
    },
)
print(r1.json()["output"])

# Второе сообщение (агент помнит имя)
r2 = requests.post(
    f"{BASE_URL}/workflows/wf_abc123/execute",
    headers=HEADERS,
    json={
        "input": {"message": "Как меня зовут?"},
        "user_id": "client_456",
        "thread_id": thread_id,
    },
)
print(r2.json()["output"])  # "Вас зовут Анна"

JavaScript (Node.js)

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://example.com/api/v1/published";

// Блокирующее выполнение
async function executeWorkflow(workflowId, input, userId, threadId) {
  const response = await fetch(
    `${BASE_URL}/workflows/${workflowId}/execute`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        input,
        user_id: userId,
        thread_id: threadId,
      }),
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.detail || "Execution failed");
  }

  return response.json();
}

// Использование
const result = await executeWorkflow(
  "wf_abc123",
  { message: "Привет!" },
  "client_456",
  "session_789"
);

console.log(result.output);

// SSE-стриминг (браузер или Node.js с fetch)
async function streamWorkflow(workflowId, input, userId) {
  const response = await fetch(
    `${BASE_URL}/workflows/${workflowId}/stream`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        input,
        user_id: userId,
      }),
    }
  );

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split("\n");

    for (const line of lines) {
      if (line.startsWith("data: ")) {
        const data = JSON.parse(line.slice(6));
        console.log(data);
      }
    }
  }
}

Подробнее

Для управления контекстом диалога между запросами используйте thread_id. Все запросы с одинаковым thread_id и user_id разделяют историю разговора и пользовательскую память.

Через initial_memory можно предзаполнить пользовательскую память перед первым вызовом -- например, передать имя и контактные данные клиента.

Аутентификация​

Создание ключа​

Уровни доступа (scopes)​

Управление ключами​

Базовый URL​

Эндпоинты​

Список рабочих процессов​

Информация о рабочем процессе​

Выполнение рабочего процесса (блокирующее)​

Стриминг рабочего процесса (SSE)​

Статус выполнения​

Подписка на события выполнения (SSE)​

Остановка выполнения​

Подтверждение шага (Human-in-the-loop)​

Вебхуки​

Коды ошибок​

Примеры​

cURL​

Python​

JavaScript (Node.js)​

Аутентификация

Создание ключа

Уровни доступа (scopes)

Управление ключами

Базовый URL

Эндпоинты

Список рабочих процессов

Информация о рабочем процессе

Выполнение рабочего процесса (блокирующее)

Стриминг рабочего процесса (SSE)

Статус выполнения

Подписка на события выполнения (SSE)

Остановка выполнения

Подтверждение шага (Human-in-the-loop)

Вебхуки

Коды ошибок

Примеры

cURL

Python

JavaScript (Node.js)