Felo APIs

SuperAgent API

Twórz konwersacje, korzystaj ze strumieni SSE, zadawaj kolejne pytania i przeglądaj metadane konwersacji.

POST/v2/conversations

Uwierzytelnianie

Bearer API key

Typ zawartości

application/json and text/event-stream

Uwagi o limitach

Connect to stream immediately. Use offset for reconnects.

LiveDoc API Chat API

API SuperAgent zapewnia możliwości konwersacji oparte na AI z przesyłaniem strumieniowym w czasie rzeczywistym i integracją z LiveDoc. Typowy przepływ pracy to:

Utwórz konwersację — otrzymaj stream_key, thread_short_id i live_doc_short_id
Odbieraj strumień SSE — połącz się z endpointem strumienia za pomocą stream_key
Zadaj pytanie uzupełniające — zadawaj pytania uzupełniające w tej samej konwersacji i otrzymuj nowy stream_key
Sprawdź szczegóły konwersacji — użyj thread_short_id, aby pobrać metadane konwersacji
Zarządzaj LiveDocami — pełne operacje CRUD i zarządzanie zasobami znajdziesz w API LiveDoc

Uwierzytelnianie

Wszystkie żądania wymagają klucza API w nagłówku Authorization:

Authorization: Bearer YOUR_API_KEY

Użycie z agentami AI

Zainstaluj kompletny pakiet felo-ai, aby dać agentowi przepływy SuperAgent i każdy inny dostępny Felo Skill. Instalator dynamicznie wykrywa każdy katalog pakietu zawierający SKILL.md, w tym przyszłe dodatki do pakietu. Zainstaluj wszystkie wykryte Skills w Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills lub Hermes Agent ~/.hermes/skills. Podręcznik konfiguracji agenta AI wyjaśnia bezpieczny proces instalacji i konfigurację dla poszczególnych platform.

1. Tworzenie konwersacji

Endpoint

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

Nagłówki żądania

Nagłówek	Wymagany	Opis
`Authorization`	Tak	`Bearer YOUR_API_KEY`
`Content-Type`	Tak	`application/json`

Treść żądania

Parametr	Typ	Wymagany	Opis
`query`	string	Tak	Zapytanie użytkownika, od 1 do 2000 znaków
`live_doc_short_id`	string	Nie	Użyj ponownie istniejącego LiveDoc; pomiń, aby utworzyć nowy
`selected_resource_ids`	array of strings	Nie	Identyfikatory zasobów do uwzględnienia w kontekście
`skill_id`	string	Nie	Identyfikator Skill do użycia w tej konwersacji
`accept_language`	string	Nie	Preferencja językowa, np. `en`
`device_id`	string	Nie	Identyfikator urządzenia
`extra`	object	Nie	Dodatkowe parametry przekazywane do SuperAgent
`ext`	object	Nie	Parametry rozszerzenia (np. `style_id`, `theme`)

Przykład

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"}
  }'

Odpowiedź sukcesu (200)

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

Pola odpowiedzi

Pole	Typ	Opis
`stream_key`	string	Klucz używany do odbierania strumienia SSE (zobacz sekcję 2)
`thread_short_id`	string	Identyfikator konwersacji, używany do sprawdzania szczegółów konwersacji
`live_doc_short_id`	string	Powiązany identyfikator LiveDoc

2. Odbieranie strumienia SSE

Po utworzeniu konwersacji połącz się z endpointem strumienia za pomocą stream_key, aby otrzymywać dane wyjściowe w czasie rzeczywistym.

Endpoint

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

Parametry zapytania

Parametr	Typ	Wymagany	Opis
`offset`	integer	Nie	Wznów przesyłanie strumieniowe od tej pozycji. Użyj przy ponownym połączeniu po rozłączeniu.

Przykład

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

Ponowne połączenie z przesunięciem:

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

Odpowiedź

Odpowiedź to standardowy strumień Server-Sent Events (SSE) z Content-Type: text/event-stream.

Każde zdarzenie ma format SSE:

event: <event_type>
data: <json_payload>

Przykładowe zdarzenia:

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

event: done
data: {}

Przy błędzie upstream:

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

Uwagi

Połącz się natychmiast po utworzeniu konwersacji — stream_key ma ograniczone okno ważności.
Użyj klienta obsługującego SSE (np. EventSource w przeglądarkach lub curl -N w terminalu).
Strumień kończy się po otrzymaniu zdarzenia done lub zamknięciu połączenia przez serwer.

3. Pytanie uzupełniające w konwersacji

Zadaj pytanie uzupełniające w istniejącej konwersacji. Zwraca nowy stream_key do odbierania strumienia odpowiedzi.

Endpoint

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

Nagłówki żądania

Nagłówek	Wymagany	Opis
`Authorization`	Tak	`Bearer YOUR_API_KEY`
`Content-Type`	Tak	`application/json`

Treść żądania

Parametr	Typ	Wymagany	Opis
`query`	string	Tak	Pytanie uzupełniające, od 1 do 2000 znaków

Przykład

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?"
  }'

Odpowiedź sukcesu (200)

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

Pola odpowiedzi

Pole	Typ	Opis
`stream_key`	string	Klucz używany do odbierania strumienia SSE dla tego pytania uzupełniającego
`thread_short_id`	string	Ten sam identyfikator konwersacji co w żądaniu
`live_doc_short_id`	string	Powiązany identyfikator LiveDoc

4. Sprawdzanie szczegółów konwersacji

Endpoint

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

Przykład

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

Odpowiedź sukcesu (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"
  }
}

Pola odpowiedzi

Pole	Typ	Opis
`thread_short_id`	string	Identyfikator konwersacji
`title`	string	Tytuł konwersacji (wyprowadzony z zapytania)
`created_at`	string	Znacznik czasu utworzenia (ISO 8601)
`updated_at`	string	Znacznik czasu ostatniej aktualizacji (ISO 8601)
`live_doc_short_id`	string	Powiązany identyfikator LiveDoc

Kody błędów

Kod	Status HTTP	Opis
`UNAUTHORIZED`	401	Klucz API jest nieprawidłowy lub unieważniony
`SUPER_AGENT_CONVERSATION_CREATE_FAILED`	502	Nie udało się utworzyć konwersacji (błąd podrzędny)
`SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED`	502	Nie udało się zadać pytania uzupełniającego (błąd podrzędny)
`SUPER_AGENT_CONVERSATION_QUERY_FAILED`	502	Nie udało się sprawdzić szczegółów konwersacji (błąd podrzędny)

Typowy przepływ integracji

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

Informacje o zarządzaniu LiveDocami (CRUD, przesyłanie zasobów, import adresów URL, wyszukiwanie) znajdziesz w API LiveDoc.