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.
Endpoint
Section titled “Endpoint”POST /api/v1/queryAuthorization: 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).
Odpoveď
Section titled “Odpoveď”{ "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.
Meranie a limity
Section titled “Meranie a limity”- 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_exceededdo 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 429usage_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. |
Príklad (curl)
Section titled “Príklad (curl)”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"}'