Preskočiť na obsah

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.

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

Sekcia API kľúče v administrácii, kde administrátor vytvorí kľúč

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 (od Business) otázky
GET /api/v1/audit-events Čítať záznamy z Aktivít (Enterprise) audit
GET /api/v1/me Overiť kľúč (rozsah, stav, platnosť) ľubovoľný

Detaily: Dokumenty, Otázky a Audit Logs.

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, quota_exceeded alebo usage_ceiling), 502 (operácia zlyhala, skúste znova).

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, overenie a Audit Logs (/api/v1/me, /api/v1/audit-events) 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í: po jeho vyčerpaní (s vypnutým automatickým navýšením plánu) vráti API 429 quota_exceeded do začiatku ďalšieho mesiaca alebo do rozšírenia plánu. Bezpečnostný strop využitia vysoko nad balíkom vráti usage_ceiling.

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.