Přehled API

Úvod do API platformy PraktickAI — základní URL, autentizace, limity a zpracování chyb. Předběžný přístup.

Na této stránce

Předběžný přístup / preview. API PraktickAI se aktivně vyvíjí a je dostupné vývojovým partnerům. Endpointy, pole a limity se mohou před obecnou dostupností změnit. O přístup požádejte v admin konzoli.

Platforma PraktickAI dává vašemu produktu dvě AI služby s oporou ve vašich datech za jedním konzistentním API: Email API pro čtení schránky a tvorbu či automatické odesílání odpovědí a Agent API pro odpovídání na dotazy z vašich připojených znalostí. Obě sdílejí stejnou autentizaci, základní URL, formát chyb a limity popsané na této stránce.

Základní URL

Všechny požadavky směřují na jednu základní URL přes HTTPS. Požadavky přes prosté HTTP jsou odmítnuty.

https://api.praktickai.app

API je verzované v cestě. Aktuální verze je v1, např. `https://api.praktickai.app/v1/agent/messages`. Pole přidáváme zpětně kompatibilně; nekompatibilní změny vyjdou pod novým prefixem verze.

Autentizace

Každý požadavek autentizujte pomocí Bearer API klíče v hlavičce `Authorization`. Klíče vytvoříte a rotujete v admin konzoli v sekci Nastavení → API klíče. Klíče jsou vázané na jeden workspace.

curl https://api.praktickai.app/v1/agent/messages \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Jak si obnovím heslo?" }'

API klíče mají plný přístup k workspace. Držte je na serveru, nikdy je neposílejte v kódu prohlížeče či mobilní aplikace a při úniku je okamžitě rotujte. Testovací klíče mají prefix `pk_test_` a pracují jen se sandboxovými daty.

Prefix	Prostředí	Poznámky
pk_live_	Produkce	Pracuje se skutečnými schránkami a znalostními zdroji.
pk_test_	Sandbox	Izolovaná data, žádný e-mail se reálně neodešle.

Požadavky a odpovědi

Odesílejte a přijímejte JSON. U požadavků s tělem nastavte `Content-Type: application/json`. Všechny URL kolekcí zdrojů končí lomítkem. Časová razítka jsou ISO 8601 v UTC a identifikátory jsou neprůhledné řetězce citlivé na velikost písmen.

Limity požadavků

V předběžném přístupu se limity uplatňují na jeden API klíč. Každá odpověď obsahuje hlavičky s limity, abyste se mohli elegantně zpomalit.

Hlavička	Popis
X-RateLimit-Limit	Maximální počet požadavků v aktuálním okně.
X-RateLimit-Remaining	Zbývající požadavky v aktuálním okně.
X-RateLimit-Reset	Unixové časové razítko, kdy se okno resetuje.

Oblast	Výchozí limit
Zprávy agenta	60 požadavků / minutu
Návrh a odeslání e-mailu	120 požadavků / minutu
Správa znalostí a schránek	30 požadavků / minutu

Při překročení limitu API vrátí HTTP 429. Respektujte hlavičku X-RateLimit-Reset a opakujte s exponenciálním odstupem. Potřebujete vyšší limity? Napište v admin konzoli.

Formát chyb

Chyby používají standardní HTTP stavové kódy a konzistentní JSON tělo. Vždy logujte `request_id` — umožní podpoře dohledat konkrétní volání.

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_field",
    "message": "Pole 'message' je povinné.",
    "param": "message",
    "request_id": "req_8f2a1c9d4e"
  }
}

Stav	type	Význam
400	invalid_request_error	Požadavek byl chybný nebo mu chybělo povinné pole.
401	authentication_error	Chybějící nebo neplatný API klíč.
403	permission_error	Klíč je platný, ale nemá oprávnění k této akci.
404	not_found_error	Odkazovaný zdroj neexistuje.
429	rate_limit_error	Příliš mnoho požadavků — zpomalte a opakujte.
500	api_error	Chyba na naší straně. Lze bezpečně opakovat.

Kam dál

Email API — připojte schránku a tvořte nebo automaticky odesílejte odpovědi s oporou v datech.
Agent API — odešlete zprávu a získejte odpověď z vašich znalostí, včetně zdrojů.
Průvodce nastavením — připojte Notion, Slack a Google Drive přes MCP a nasaďte agenta.

Otevřete referenci Email API, referenci Agent API, nebo se řiďte průvodcem nastavením a připojte první znalostní zdroje.