API: prehľad

KwargsAI vystavuje verejné REST API, ktorým externé systémy pracujú s vašou firemnou AI bez prehliadača: posielajú dokumenty do priečinka a kladú otázky asistentovi. Autentifikuje sa API kľúčom.

Balík Growth

API je súčasťou balíka Growth (a vyššie). Na balíku Starter vrátia volania 403.

Základ

• Base URL: vaša inštancia, napr. https://<vasa-instancia> (cesty začínajú /api/v1/…).
• Formát: JSON (Content-Type: application/json).
• Autentifikácia: API kľúč v hlavičke Authorization: Bearer kw_live_…, viď Autentifikácia. Kľúče vytvára administrátor v sekcii API kľúče.

Koncové body

Koncový bod	Popis	Kľúč
POST /api/v1/documents	Poslať dokument (upsert podľa id)	zápis dokumentov
GET /api/v1/documents	Vypísať dokumenty v priečinku	zápis dokumentov
DELETE /api/v1/documents/{id}	Zmazať dokument	zápis dokumentov
POST /api/v1/query	Položiť otázku asistentovi (Growth)	otázky
GET /api/v1/me	Overiť kľúč (rozsah, stav, platnosť)	ľubovoľný

Detaily: Dokumenty a Otázky.

Chyby

Chyby vracajú neúspešný HTTP status a JSON s kódom, napr.:

{ "error": "rate_limited" }

Bežné kódy: 401 (chýbajúci/neplatný/zneplatnený/expirovaný kľúč), 403 (nesprávny typ kľúča alebo funkcia mimo balíka), 400 (neplatný vstup), 404 (nenájdené), 413 (priveľký obsah), 429 (rate_limited alebo usage_ceiling), 502 (operácia zlyhala, skúste znova).

Obmedzenie požiadaviek (rate limiting)

Limit je na API kľúč podľa typu operácie:

Operácia	Limit
Otázky (/api/v1/query)	30 / min
Zápis a mazanie dokumentov	60 / min
Výpis a overenie (/api/v1/me)	120 / min

Pri prekročení vráti API 429 s kódom rate_limited. Otázky navyše rešpektujú mesačný balík odpovedí a bezpečnostný strop využitia (usage_ceiling).

Zdravie inštancie

GET /api/health: neautentifikovaná kontrola dostupnosti (databáza + vyhľadávacie jadro). Vracia 200 so stavom ok, alebo 503 pri degradácii. Vhodné pre monitoring a load balancer.