Felo APIs

SuperAgent API

Створюйте розмови, використовуйте потоки SSE, ставте додаткові запитання й переглядайте метадані розмови.

POST/v2/conversations

Автентифікація

Bearer API key

Тип вмісту

application/json and text/event-stream

Примітки щодо обмежень

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

SuperAgent API надає розмовні можливості на основі ШІ з потоковим виводом у реальному часі та інтеграцією з LiveDoc. Типовий робочий процес:

Створити розмову — отримати stream_key, thread_short_id і live_doc_short_id
Споживати потік SSE — підключитися до endpoint потоку за допомогою stream_key
Уточнити — поставити уточнювальні запитання в тій самій розмові й отримати новий stream_key
Отримати деталі розмови — використати thread_short_id, щоб отримати метадані розмови
Керувати LiveDoc — див. LiveDoc API, щоб дізнатися про повний набір операцій CRUD і керування ресурсами

Автентифікація

Усі запити потребують API-ключа в заголовку Authorization:

Authorization: Bearer YOUR_API_KEY

Використання з агентами ШІ

Установіть повний пакет felo-ai, щоб надати агенту робочі процеси SuperAgent та всі інші доступні Felo Skills. Інсталятор динамічно знаходить кожен каталог пакета, що містить SKILL.md, зокрема майбутні доповнення пакета. Установіть усі знайдені Skills у Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills або Hermes Agent ~/.hermes/skills. Посібник з ручного налаштування агента ШІ пояснює безпечний процес встановлення та налаштування для кожної платформи.

1. Створити розмову

Endpoint

POST https://openapi.felo.ai/v2/conversations

Заголовки запиту

Заголовок	Обов'язковий	Опис
`Authorization`	Так	`Bearer YOUR_API_KEY`
`Content-Type`	Так	`application/json`

Тіло запиту

Параметр	Тип	Обов'язковий	Опис
`query`	string	Так	Запит користувача, 1-2000 символів
`live_doc_short_id`	string	Ні	Повторно використати наявний LiveDoc; пропустіть, щоб створити новий
`selected_resource_ids`	array of strings	Ні	ID ресурсів, які потрібно включити до контексту
`skill_id`	string	Ні	ID Skill для використання в цій розмові
`accept_language`	string	Ні	Мовні уподобання, напр. `en`
`device_id`	string	Ні	Ідентифікатор пристрою
`extra`	object	Ні	Додаткові параметри, що передаються до SuperAgent
`ext`	object	Ні	Параметри розширення (напр. `style_id`, `theme`)

Приклад

curl -X POST 'https://openapi.felo.ai/v2/conversations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "What is the latest news about AI?",
    "accept_language": "en",
    "skill_id": "your-skill-id",
    "device_id": "device-001",
    "ext": {"style_id": "xxx", "theme": "dark"}
  }'

Успішна відповідь (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "stream_key": "sk_abc123xyz",
    "thread_short_id": "TvyKouzJirXjFdst4uKRK3",
    "live_doc_short_id": "PvyKouzJirXjFdst4uKRK3"
  }
}

Поля відповіді

Поле	Тип	Опис
`stream_key`	string	Ключ для споживання потоку SSE (див. розділ 2)
`thread_short_id`	string	ID розмови, що використовується для отримання деталей розмови
`live_doc_short_id`	string	Пов'язаний ID LiveDoc

2. Споживання потоку SSE

Після створення розмови підключіться до endpoint потоку за допомогою stream_key, щоб отримувати вивід у реальному часі.

Endpoint

GET https://openapi.felo.ai/v2/conversations/stream/{stream_key}

Параметри запиту

Параметр	Тип	Обов'язковий	Опис
`offset`	integer	Ні	Відновити потокову передачу з цієї позиції. Використовуйте для повторного підключення після роз'єднання.

Приклад

curl -N 'https://openapi.felo.ai/v2/conversations/stream/sk_abc123xyz' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: text/event-stream'

Повторне підключення зі зміщенням:

curl -N 'https://openapi.felo.ai/v2/conversations/stream/sk_abc123xyz?offset=42' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: text/event-stream'

Відповідь

Відповідь є стандартним потоком Server-Sent Events (SSE) із Content-Type: text/event-stream.

Кожна подія має формат SSE:

event: <event_type>
data: <json_payload>

Приклади подій:

event: message
data: {"content": "The latest AI news includes..."}

event: done
data: {}

У разі помилки вищого рівня:

event: error
data: {"message": "upstream error: 502"}

Примітки

Підключайтеся одразу після створення розмови — stream_key має обмежене вікно дійсності.
Використовуйте клієнт, здатний працювати з SSE (напр. EventSource у браузерах або curl -N у терміналі).
Потік завершується, коли отримано подію done або сервер закриває з'єднання.

3. Уточнення розмови

Поставте уточнювальне запитання в наявній розмові. Повертає новий stream_key для споживання потоку відповіді.

Endpoint

POST https://openapi.felo.ai/v2/conversations/{thread_short_id}/follow_up

Заголовки запиту

Заголовок	Обов'язковий	Опис
`Authorization`	Так	`Bearer YOUR_API_KEY`
`Content-Type`	Так	`application/json`

Тіло запиту

Параметр	Тип	Обов'язковий	Опис
`query`	string	Так	Уточнювальне запитання, 1-2000 символів

Приклад

curl -X POST 'https://openapi.felo.ai/v2/conversations/TvyKouzJirXjFdst4uKRK3/follow_up' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Can you elaborate on that?"
  }'

Успішна відповідь (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "stream_key": "sk_def456uvw",
    "thread_short_id": "TvyKouzJirXjFdst4uKRK3",
    "live_doc_short_id": "PvyKouzJirXjFdst4uKRK3"
  }
}

Поля відповіді

Поле	Тип	Опис
`stream_key`	string	Ключ для споживання потоку SSE для цього уточнення
`thread_short_id`	string	Той самий ID розмови, що й у запиті
`live_doc_short_id`	string	Пов'язаний ID LiveDoc

4. Отримання деталей розмови

Endpoint

GET https://openapi.felo.ai/v2/conversations/{thread_short_id}

Приклад

curl 'https://openapi.felo.ai/v2/conversations/TvyKouzJirXjFdst4uKRK3' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Успішна відповідь (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "thread_short_id": "TvyKouzJirXjFdst4uKRK3",
    "title": "What is the latest news about AI?",
    "created_at": "2026-03-09T10:00:00Z",
    "updated_at": "2026-03-09T10:00:30Z",
    "live_doc_short_id": "PvyKouzJirXjFdst4uKRK3"
  }
}

Поля відповіді

Поле	Тип	Опис
`thread_short_id`	string	ID розмови
`title`	string	Заголовок розмови (похідний від запиту)
`created_at`	string	Часова позначка створення (ISO 8601)
`updated_at`	string	Часова позначка останнього оновлення (ISO 8601)
`live_doc_short_id`	string	Пов'язаний ID LiveDoc

Коди помилок

Код	Статус HTTP	Опис
`UNAUTHORIZED`	401	API-ключ недійсний або відкликаний
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	Не вдалося створити розмову (помилка нижчого рівня)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	Не вдалося уточнити розмову (помилка нижчого рівня)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	Не вдалося отримати деталі розмови (помилка нижчого рівня)

Типовий процес інтеграції

1. POST /v2/conversations                              → get stream_key + thread_short_id + live_doc_short_id
2. GET  /v2/conversations/stream/{stream_key}          → consume SSE until "done"
3. POST /v2/conversations/{thread_short_id}/follow_up  → ask follow-up, get new stream_key
4. GET  /v2/conversations/stream/{new_stream_key}      → consume follow-up SSE until "done"
5. GET  /v2/conversations/{thread_short_id}            → fetch conversation metadata

Про керування LiveDoc (операції CRUD, завантаження ресурсів, імпорт за URL-адресою, отримання) див. LiveDoc API.