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

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).

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 …" }
  ],
  "assistant": { "key": "obchodny", "name": "Obchodný asistent" }
}

Odpoveď je vždy opretá o dokumenty asistenta (grounded); ku každému tvrdeniu vracia zdroje v citations.

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.
Pri prekročení bezpečnostného stropu využitia vráti 429 usage_ceiling.
Analytickí asistenti (Code Interpreter nad nahraným súborom) nie sú cez tento endpoint dostupní; kľúč typu „otázky“ na nich nevytvoríte.

Chyby

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 (Growth+).
`400`	Neplatné telo alebo prázdna `question`.
`413`	Otázka je dlhšia ako 8000 znakov.
`429`	`rate_limited` (limit na kľúč) alebo `usage_ceiling` (strop využitia).
`502`	Generovanie odpovede zlyhalo, skúste znova.

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