Integrace přes API

Na této stránce si vytvoříte API klíč a ověříte první volání. Potřebujete k tomu aktivní licenci CODEXIS AI Agent a adresu své instance.

Přes Codexis AI agent API napojíte agenta do vlastního programu. Zeptáte se z automatizační platformy, ze skriptu nebo z interní aplikace a odpověď si vyzvednete zpátky. Stačí k tomu jeden API klíč vložený do nástroje, ze kterého chcete agenta volat.

K čemu to je

Integrace se hodí, když chcete agenta zapojit do procesu, který už běží:

• Automatizační platformy jako Make.com nebo Zapier. Scénář pošle agentovi e-mail se smlouvou a odpověď zapíše do tabulky.
• Vlastní skript. Jednou týdně proženete dávku dokumentů a výstup si necháte uložit.
• Interní aplikace. Do svého systému spisové služby nebo CRM přidáte tlačítko „Posoudit dokument“.

Agent pracuje se stejnou znalostí práva, se stejnými dovednostmi a nad stejnými soubory jako v chatu. Konverzace založené přes API vidíte v aplikaci v historii a můžete v nich pokračovat ručně.

Než začnete

Potřebujete aktivní licenci CODEXIS AI Agent. Bez ní klíč nevytvoříte a existující klíče přestanou fungovat.

Dál potřebujete adresu své instance, tedy adresu, na které máte CODEXIS AI otevřený v prohlížeči. V dokumentaci i v ukázce na kartě Použití klíče v aplikaci ji nahrazuje placeholder https://<vaše-instance>.

Každý dotaz poslaný přes API spotřebuje kredity stejně jako dotaz napsaný v chatu, a to z účtu toho, komu klíč patří.

Vytvoření klíče

1. Otevřete Nastavení a přejděte na Komunikační kanály.
2. Přepněte se na záložku API.
3. Nemáte-li ještě žádný klíč, uvidíte žlutě zvýrazněnou kartu s textem „Zatím nemáš žádné API klíče.“ Klikněte na ni, nebo na tlačítko Vytvořit klíč.
4. Klíč pojmenujte podle nástroje, ze kterého ho budete používat, třeba integrace Make.com. Podle jména poznáte, který klíč odebrat, když jeden z nástrojů vyřadíte.
5. Potvrďte tlačítkem Vytvořit klíč.

Klíč se objeví v seznamu a hned pod ním je vypsaný celý. Začíná předponou api-.

Vložte klíč rovnou do nástroje, pro který jste ho vytvořili, ideálně do jeho úložiště tajemství nebo do proměnné prostředí. Do zdrojového kódu ani do sdíleného dokumentu nepatří.

Platnost klíče

U každého klíče v seznamu vidíte, kdy vznikl a do kdy platí, například „Vytvořen 30. 7. 2026 · platí do 31. 12. 2026“.

Platnost se odvozuje od vaší licence CODEXIS AI Agent. Klíč funguje přesně tak dlouho jako licence:

• Když licenci prodloužíte, posune se sama i platnost klíčů. Původní klíče platí dál.
• Když licence skončí, klíče přestanou fungovat a volání dostane odpověď 401.

Autentizace

Klíč se posílá v hlavičce X-Api-Key. To je celá autentizace.

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

Odpoví stav vašeho virtuálního počítače:

{ "status": "RUNNING" }

Tímto voláním si nejjednodušeji ověříte, že klíč funguje. Dotazy zpracovává agent na virtuálním počítači, takže vrátí-li stav STOPPED, nastartujte ho voláním POST /api/v1/vm/start a chvíli počkejte, než přejde do stavu RUNNING.

Zacházení s chybami

Chybová odpověď má vždy stejný tvar, kód pro váš program a zprávu pro člověka:

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

• 400, požadavek nejde přečíst. Chybí input, je prázdný soubor, nebo je vadný JSON. Opravte tělo požadavku, opakování nepomůže.
• 401, klíč chybí, je opsaný špatně, byl odebraný, nebo mu skončila platnost s licencí. Zkontrolujte hlavičku X-Api-Key a platnost klíče v Nastavení → Komunikační kanály → API.
• 404, konverzace nebo zpráva s tímto identifikátorem neexistuje, nebo nepatří vám. Zkontrolujte chatId a messageId z předchozí odpovědi.
• 409, agent zadání odmítl. Typicky ještě odpovídá na předchozí dotaz, počkejte na dokončení a zkuste to znovu. Stejný kód vrátí i start nebo vypnutí virtuálního počítače, pokud pro váš účet žádný neexistuje.
• 500, chyba na straně agenta. Zkuste to znovu později, a opakuje-li se to, ozvěte se podpoře.

U odpovědi 401 přichází i hlavička WWW-Authenticate: ApiKey a tělo je prázdné. Je to odmítnutí ještě před vstupem do aplikace.

Bezpečnostní zásady

Klíč zastupuje vás. Kdo ho má, může se ptát vaším jménem, čte vaše soubory a spotřebovává vaše kredity. Zacházejte s ním jako s heslem.

Jeden nástroj, jeden klíč. Nepoužívejte jeden klíč na tři různé integrace. Když jeden nástroj vyřadíte nebo jeho klíč unikne, odeberete přesně ten jeden a ostatní běží dál.

Pojmenujte klíč podle nástroje. Jméno je jediné, podle čeho klíč v seznamu poznáte. Celý klíč už nikdy neuvidíte a předpona vám sama nic neřekne.

Neposílejte klíč v adrese. Patří do hlavičky X-Api-Key. V parametrech URL by skončil v logu serverů i proxy.

Nedávejte klíč do prohlížeče. Volání z webové stránky nebo mobilní aplikace znamená, že klíč dostane každý uživatel. Volejte API ze svého serveru.

Odebrání klíče

Klíč zrušíte tam, kde jste ho vytvořili. V Nastavení → Komunikační kanály → API najeďte na řádek klíče a klikněte na ikonu koše (Odebrat).

Odebrání platí okamžitě, každé další volání s tímto klíčem skončí s odpovědí 401. Ostatní klíče i běžná práce v aplikaci zůstávají nedotčené.

Jak jednotlivá volání vypadají, popisuje Přehled endpointů.