Přeskočit na hlavní obsah

Začínáme

REST API Siesta AI umožňuje vašemu backendu vytvářet, číst a aktualizovat vybrané zdroje Siesta AI z vašich vlastních systémů. Použijte jej pro serverové integrace, administrativní pracovní postupy, reportování a funkce aplikací, které potřebují stabilní HTTP kontrakt.

REST API je příchozí: váš systém volá Siesta AI. To se liší od připojení REST API, které je odchozí a umožňuje Siesta AI volat jiné HTTP API.

Běžné integrace:

  • Odeslat otázku uživatele agentovi a uložit vrácené conversationId.
  • Zřídit nebo vypsat agenty z administrativního backendu nebo zákaznického portálu.
  • Nahrát dočasný soubor a předat jej agentovi jako kontext.
  • Vytvářet nebo aktualizovat úkoly z CRM, systému pro správu tiketů nebo workflow enginu.
  • Zahájit relaci hlasu v reálném čase nebo streamování s agentem.
  • Exportovat záznamy auditního logu pro dodržování předpisů nebo operační monitorování.

Základní URL​

Použijte základní URL produkčního API:

https://api.siesta.ai

Cesty koncových bodů v referenci zahrnují předponu /api/v1. Kombinujte základní URL s cestou zobrazenou u každého koncového bodu.

První požadavek​

Začněte s koncovým bodem pouze pro čtení, jako je výpis agentů nebo úkolů. Uchovávejte API přihlašovací údaje na vašem backendu a posílejte požadované hlavičky s každým požadavkem.

curl -X GET "https://api.siesta.ai/api/v1/Agent?Limit=10" \
  -H "X-Api-Key: <api-key>" \
  -H "X-Org-Id: <organization-id>"

Použijte referenci REST API pro přesné cesty, parametry dotazu, těla požadavků, schémata odpovědí a příklady generované z aktuálního OpenAPI kontraktu.

Stránkování a chyby​

Koncové body seznamu běžně přijímají parametry stránkování jako Offset a Limit, pokud jsou přítomny v OpenAPI kontraktu. Odpovědi a tvary chyb jsou dokumentovány pro každý koncový bod v referenci.

Zpracovávejte tyto skupiny stavů konzistentně:

  • 2xx: požadavek byl úspěšný.
  • 4xx: požadavek byl odmítnut kvůli vstupu, autentizaci, autorizaci, limitu rychlosti nebo chybějícímu zdroji.
  • 5xx: Siesta AI nemohla dokončit požadavek.

Autentizace​

Každý požadavek REST API musí obsahovat obě hlavičky:

X-Api-Key: <api-key>
X-Org-Id: <organization-id>

X-Api-Key identifikuje volající integraci. X-Org-Id omezuje požadavek na jednu organizaci Siesta AI. Platný klíč bez odpovídajícího kontextu organizace stále selže pro zdroje mimo tento rozsah.

Spravujte API klíče v aplikaci Siesta AI pod Organization → API Keys. Použijte samostatný klíč pro každou integraci a prostředí a odstraňte klíče, které již nejsou používány.

Interaktivní reference používá zástupné symboly ve vzorcích kódu. Nahraďte je ve vašem backendu nebo lokálním testovacím nástroji. Nezveřejňujte produkční API klíče ve frontendovém kódu.

Pouze důvěryhodné provedení​

Používejte API klíče pouze z důvěryhodného serverového kódu:

  • obslužné rutiny backendových tras;
  • plánované úlohy;
  • interní integrační služby;
  • lokální vývojové nástroje.

Neumisťujte API klíče do:

  • prohlížečových balíčků nebo statických stránek;
  • mobilních aplikací distribuovaných koncovým uživatelům;
  • snímků obrazovky, tiketů nebo sdílených chatových zpráv;
  • logů, analytických událostí nebo klientského hlášení chyb;
  • veřejných repozitářů nebo zapsaných konfiguračních souborů.

Pokud potřebujete chování založené na prohlížeči, odešlete požadavek přes váš vlastní backend a tam vložte přihlašovací údaje Siesta AI.

Ukládání a rotace klíčů​

Uložte API klíč v tajném správci nebo proměnné prostředí řízené nasazením vašeho backendu. Uchovávejte X-Org-Id spolu s konfiguračním nastavením integrace, aby každé prostředí ukazovalo na správnou organizaci.

Doporučené nastavení:

  1. Udržujte produkční a neprodukční klíče oddělené.
  2. Použijte jednu identitu integrace na prostředí nebo povrch aplikace, pokud je to možné.
  3. Rotujte klíče aktualizací tajného backendu nejprve, poté znovu testujte koncový bod pouze pro čtení.
  4. Odstraňte nepoužívané klíče, když je integrace vyřazena.

Testování z dokumentace​

Referenční API obsahuje sekci Try request pro rychlé testování. Hodnoty zadané tam jsou uchovávány v relaci prohlížeče a nejsou uloženy do repozitáře dokumentace ani umístěny do URL stránky.

Použijte tento režim pouze pro kontrolovanou lokální validaci. Pokud politika prohlížeče, pravidla firemní sítě nebo nastavení CORS brání odeslání požadavku z domény dokumentace, použijte místo toho vygenerovaný příkaz curl.

Běžné stavové kódy​

  • 400 Bad Request: neplatný vstup, nepodporovaná kombinace parametrů nebo nesprávně formátovaný payload.
  • 401 Unauthorized: chybějící, vypršelý nebo neplatný API klíč.
  • 403 Forbidden: klíč je platný, ale nemá přístup ke zdroji nebo organizaci.
  • 404 Not Found: zdroj neexistuje nebo není viditelný pro aktuální organizaci.
  • 429 Too Many Requests: klient odesílá požadavky příliš rychle.
  • 500 Internal Server Error: neočekávané selhání na straně serveru. Zobrazte záložní zprávu a uchovejte dostatek lokálního kontextu pro bezpečné opakování.

Prohlédněte si sekci odpovědí pro každý koncový bod v referenci REST API pro přesné dokumentované tvary odpovědí.

Doporučený pracovní postup​

  1. Přečtěte si koncový bod v referenci.
  2. Zkopírujte vzorek curl a nahraďte zástupné symboly.
  3. Otestujte s požadavkem pouze pro čtení.
  4. Generujte typizované pomocníky z dokumentu OpenAPI, pokud je vaše integrace rozsáhlá.

Bezpečnost a správa​

Aplikujte stejnou správu na API integrace jako na použití v produktu:

  • Omezte každou integraci na minimální pracovní postup, který potřebuje.
  • Preferujte samostatné agenty pro různé kontexty integrace.
  • Použijte správu připojení pro nástroje, které čtou citlivá data nebo upravují externí systémy.
  • Vyžadujte schválení pro akce, které mění obchodní data.
  • Povolit nastavení bezpečnosti obsahu a ochrany výzev pro veřejné nebo zákaznicky orientované integrace.
  • Monitorujte používání agentů, provádění nástrojů a auditní logy po nasazení.
  • Před povolením automatizace s vysokým objemem zkontrolujte limity tokenů a nákladové kontroly.
Naposledy aktualizováno