Integrácia cez API

Na tejto stránke si vytvoríte API kľúč a overíte prvé volanie. Potrebujete na to aktívnu licenciu CODEXIS AI Agent a adresu svojej instancie.

Cez Codexis AI agent API napojíte agenta do vlastného programu. Spýtate sa z automatizačnej platformy, zo skriptu alebo z internej aplikácie a odpoveď si vyzdvihnete späť. Stačí na to jeden API kľúč vložený do nástroja, z ktorého chcete agenta volať.

Na čo to je

Integrácia sa hodí, keď chcete agenta zapojiť do procesu, ktorý už beží:

• Automatizačné platformy ako Make.com alebo Zapier. Scenár pošle agentovi e-mail so zmluvou a odpoveď zapíše do tabuľky.
• Vlastný skript. Raz týždenne prejdete dávku dokumentov a výstup si necháte uložiť.
• Interné aplikácie. Do svojho systému správy dokumentov alebo CRM pridáte tlačidlo „Posúdiť dokument“.

Agent pracuje s tou istou znalosťou práva, s tými istými schopnosťami a nad tými istými súbormi ako v chate. Konverzácie začaté cez API vidíte v aplikácii v histórii a môžete v nich pokračovať ručne.

Než začnete

Potrebujete aktívnu licenciu CODEXIS AI Agent. Bez nej kľúč nevytvoríte a existujúce kľúče prestanú fungovať.

Ďalej potrebujete adresu svojej instancie, teda adresu, na ktorej máte CODEXIS AI otvorený v prehliadači. V dokumentácii aj v ukážke na karte Použitie kľúča v aplikácii ju nahrádza placeholder https://<vaša-instancia>.

Každá otázka poslaná cez API spotrebuje kredity rovnako ako otázka napísaná v chate, a to z účtu toho, komu kľúč patrí.

Vytvorenie kľúča

1. Otvorte Nastavenia a prejdite na Komunikačné kanály.
2. Prepnite sa na záložku API.
3. Ak ešte nemáte žiadny kľúč, uvidíte žlto zvýraznenú kartu s textom „Zatiaľ nemáš žiadne API kľúče.“ Kliknite na ňu, alebo na tlačidlo Vytvoriť kľúč.
4. Kľúč pomenujte podľa nástroja, z ktorého ho budete používať, napríklad integrácia Make.com. Podľa mena poznáte, ktorý kľúč odobrať, keď jeden z nástrojov vyradíte.
5. Potvrďte tlačidlom Vytvoriť kľúč.

Kľúč sa objaví v zozname a hneď pod ním je vypísaný celý. Začína predponou api-.

Vložte kľúč rovno do nástroja, pre ktorý ste ho vytvorili, ideálne do jeho úložiska tajomstiev alebo do premennej prostredia. Do zdrojového kódu ani do zdieľaného dokumentu nepatrí.

Platnosť kľúča

U každého kľúča v zozname vidíte, kedy vznikol a dokedy platí, napríklad „Vytvorený 30. 7. 2026 · platí do 31. 12. 2026“.

Platnosť sa odvodzuje od vašej licencie CODEXIS AI Agent. Kľúč funguje presne tak dlho ako licencia:

• Keď licenciu predĺžite, posunie sa sama aj platnosť kľúčov. Pôvodné kľúče platia ďalej.
• Keď licencia skončí, kľúče prestanú fungovať a volanie dostane odpoveď 401.

Autentizácia

Kľúč sa posiela v hlavičke X-Api-Key. To je celá autentizácia.

curl -H "X-Api-Key: api-…" https://<vaša-instancia>/api/v1/vm

Odpovie stav vášho virtuálneho počítača:

{ "status": "RUNNING" }

Týmto volaním si najjednoduchšie overíte, že kľúč funguje. Otázky spracúva agent na virtuálnom počítači, takže ak vráti stav STOPPED, naštartujte ho volaním POST /api/v1/vm/start a chvíľu počkajte, kým prejde do stavu RUNNING.

Zaobchádzanie s chybami

Chybová odpoveď má vždy rovnaký tvar, kód pre váš program a správu pre človeka:

{ "code": "NOT_FOUND", "message": "Chat not found: 6f1c…" }

• 400, požiadavka sa nedá prečítať. Chýba input, je prázdny súbor, alebo je chybný JSON. Opravte telo požiadavky, opakovanie nepomôže.
• 401, kľúč chýba, je odpísaný zle, bol odobraný, alebo mu skončila platnosť s licenciou. Skontrolujte hlavičku X-Api-Key a platnosť kľúča v Nastavenia → Komunikačné kanály → API.
• 404, konverzácia alebo správa s týmto identifikátorom neexistuje, alebo nepatrí vám. Skontrolujte chatId a messageId z predchádzajúcej odpovede.
• 409, agent zadanie odmietol. Typicky ešte odpovedá na predchádzajúcu otázku, počkajte na dokončenie a skúste to znovu. Rovnaký kód vráti aj štart alebo vypnutie virtuálneho počítača, ak pre váš účet žiadny neexistuje.
• 500, chyba na strane agenta. Skúste to znovu neskôr, a ak sa to opakuje, ozvite sa podpore.

Pri odpovedi 401 prichádza aj hlavička WWW-Authenticate: ApiKey a telo je prázdne. Je to odmietnutie ešte pred vstupom do aplikácie.

Bezpečnostné zásady

Kľúč zastupuje vás. Kto ho má, môže sa pýtať vaším menom, číta vaše súbory a spotrebúva vaše kredity. Zaobchádzajte s ním ako s heslom.

Jeden nástroj, jeden kľúč. Nepoužívajte jeden kľúč na tri rôzne integrácie. Keď jeden nástroj vyradíte alebo jeho kľúč unikne, odoberiete presne ten jeden a ostatné bežia ďalej.

Pomenujte kľúč podľa nástroja. Meno je jediné, podľa čoho kľúč v zozname poznáte. Celý kľúč už nikdy neuvidíte a predpona vám sama nič nepovie.

Neposielajte kľúč v adrese. Patrí do hlavičky X-Api-Key. V parametroch URL by skončil v logu serverov aj proxy.

Nedávajte kľúč do prehliadača. Volanie z webovej stránky alebo mobilnej aplikácie znamená, že kľúč dostane každý používateľ. Volajte API zo svojho servera.

Odobranie kľúča

Kľúč zrušíte tam, kde ste ho vytvorili. V Nastavenia → Komunikačné kanály → API nabehnite na riadok kľúča a kliknite na ikonu koša (Odobrať).

Odobranie platí okamžite, každé ďalšie volanie s týmto kľúčom skončí s odpoveďou 401. Ostatné kľúče aj bežná práca v aplikácii zostávajú nedotknuté.

Ako jednotlivé volania vyzerajú, popisuje Prehľad endpointov.