Preskočiť na obsah

API: otázky asistentovi (REST)

Tento endpoint umožní externému systému položiť otázku jednému AI asistentovi a dostať odpoveď opretú o vaše dáta, spolu s citáciami. Je to „headless” jadro produktu: odpovede zapojíte do vlastnej aplikácie alebo workflow bez prehliadača.

POST /api/v1/query
Authorization: Bearer kw_live_…
Content-Type: application/json
{
"question": "Aká je cena pre zákazníka Novák?",
"language": "sk" // voliteľné: sk | cs | en
}
  • Autentifikácia: API kľúč typu „otázky”, viazaný na jeden asistent. Cieľový asistent sa určí z kľúča.
  • question (povinné): otázka v bežnej reči, max 8000 znakov.
  • language (voliteľné): jazyk odpovede (sk, cs, en).
{
"answer": "Podľa zmluvy má zákazník Novák zľavu 8 % …",
"citations": [
{ "id": 1, "source": "Zmluva Novák", "blurb": "… zľava 8 % pri odbere nad …", "cited": true },
{ "id": 2, "source": "Cenník 2026", "blurb": "…", "cited": false }
],
"assistant": { "key": "obchodny", "name": "Obchodný asistent" }
}

Odpoveď je vždy opretá o dokumenty asistenta (grounded); zdroje vracia v citations, každý dokument raz:

  • najprv dokumenty, na ktoré sa odpoveď priamo odvoláva ("cited": true), v poradí citácií,
  • potom ďalšie, ktoré vyhľadávanie našlo, ale odpoveď z nich nečerpá ("cited": false).

Ak zobrazujete zdroje používateľom, ukážte prednostne tie s "cited": true.

  • Každá otázka sa počíta ako jedna odpoveď z mesačného balíka odpovedí vašej inštancie (rovnako, ako otázka vo webovom rozhraní).
  • Rate limit: 30 požiadaviek / minútu na kľúč. Pri prekročení 429 rate_limited.
  • Po vyčerpaní mesačného balíka odpovedí (s vypnutým automatickým navýšením plánu) vráti 429 quota_exceeded do začiatku ďalšieho mesiaca alebo do rozšírenia plánu; administrátor dostane e-mail. Pri prekročení bezpečnostného stropu využitia vráti 429 usage_ceiling.
  • Cez tento endpoint asistent odpovedá z dokumentov, analýzu dát nespúšťa (tie sú dostupné vo webovom rozhraní).
Status Kód / dôvod
401 Chýbajúci, neplatný, zneplatnený alebo expirovaný kľúč.
403 Kľúč nie je typu „otázky”, alebo balík neobsahuje API otázky (od Business).
400 Neplatné telo alebo prázdna question.
413 Otázka je dlhšia ako 8000 znakov.
429 rate_limited (limit na kľúč), quota_exceeded (mesačný balík vyčerpaný) alebo usage_ceiling (strop využitia).
502 Generovanie odpovede zlyhalo, skúste znova.
Terminal window
curl -X POST https://<vasa-instancia>/api/v1/query \
-H "Authorization: Bearer kw_live_…" \
-H "Content-Type: application/json" \
-d '{"question":"Aká je cena pre zákazníka Novák?","language":"sk"}'