Přehled API

Dostupné návrhy e-mailů a chat s uloženým kontextem; další funkce a příklady jsou návrh budoucího API.

Na této stránce

Návrh budoucího API — není dostupný. Příklady pod shrnutím dostupného rozsahu níže jsou plánovaný kontrakt, ne popis běžících endpointů. Připojení Gmail/Outlook/IMAP, automatické odesílání, živé MCP zdroje, indexace, citace, konverzace a streamování zatím nejsou implementované. Příklady, limity a záruky izolace níže neplatí pro dnešní runtime.

Dostupný rozsah: `POST /api/ai/v1/chat/` vytvoří odpověď na jednotlivý dotaz z uloženého firemního kontextu. `POST /api/ai/v1/email/draft/` vytvoří návrh z ručně předané zprávy a kontextu, bez přístupu do schránky a bez odesílání. Výstupy vyžadují kontrolu člověkem. Aktuální pole a autentizaci ověřte v běžícím OpenAPI schématu; nepoužívejte plánované příklady níže jako integrační návod.

Plánovaný kontrakt (není implementovaný)

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.