Dokumentace

API reference

Dokumentace

REST API Aitelier umožňuje programově spouštět odchozí hovory, běhat batch kampaně, číst sessions a prohlížet webhook subscriptions. Tato stránka je rychlá reference — interaktivní, vždy aktuální reference s úplnými schématy request/response slouží API samotné na /v1/docs a OpenAPI dokument na /v1/openapi.json.

Base URL

https://public-api.beta.aitelier.org/v1

Všechny endpointy vyžadují HTTPS.

Autentizace

Každý request potřebuje project-scoped API klíč:

Authorization: Bearer avp_live_…

(Funguje i X-API-Key: avp_live_….)

API klíče se vydávají v záložce projektu API keys, jsou scoped per klíč a kdykoli odvolatelné. Při vytvoření se klíč zobrazí jednou; at rest ho hashujeme a plaintext nelze obnovit. UI identifikuje klíče podle prefixu.

Dostupné scopes:

  • outbound:trigger — spouštět odchozí hovory a dávky
  • sessions:read — číst metadata session, outcomes, hodnoty slotů
  • webhooks:read — prohlížet webhook subscriptions a odesílat testovací doručení

Scopes, které udělíte, se stanou jedinými operacemi, které klíč může provádět. Přihlášení do dashboardu (e-mailový kód + JWT) je oddělené; API klíče jsou jediný způsob, jak s API mluvit z vlastního kódu.

Idempotence

POST /v1/calls přijímá header Idempotency-Key. Identické klíče deduplikujeme 24 hodin od prvního přijetí: retry se stejným klíčem vrátí původní odpověď a znovupoužití klíče s jiným body vrátí 409. Použijte pro bezpečné retry při síťových selháních.

Rate limity

Výchozí na API klíč, za minutu:

  • 100 requestů pro mutace (POST/PUT/PATCH/DELETE)
  • 1000 requestů pro čtení (GET)

Každá odpověď nese stav limitu:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Window: 60

Když narazíte na limit, dostanete 429 Too Many Requests a header Retry-After. Udělejte backoff a zkuste znovu.

Endpointy

Odchozí hovory

  • POST /v1/calls — spustit jeden odchozí hovor. Úplné schéma body viz Outbound.

Odchozí dávky

  • POST /v1/calls/bulk — spustit dávku (multipart: scenarioId, volitelné callerIdNumber, CSV soubor).
  • GET /v1/calls/batches — seznam dávek.
  • GET /v1/calls/batches/{id} — stav dávky a počty per stav.
  • POST /v1/calls/batches/{id}/cancel — zrušit zbývající řádky.

Sessions

  • GET /v1/sessions — seznam s filtry scenarioId, status, from, to plus paginace limit/cursor.
  • GET /v1/sessions/{id} — úplný detail session: status, outcome, hodnoty slotů, dosažení cíle.

Statusy session: pending, live, completed, failed, abandoned.

Webhooks

  • GET /v1/webhooks — seznam subscriptions projektu.
  • GET /v1/webhooks/{id} — jedna subscription.
  • POST /v1/webhooks/{id}/test — odeslat testovací doručení na váš endpoint.

Subscriptions se vytvářejí a editují ve webovém UI — viz Webhooks.

Formát chyb

Každá chybová odpověď je JSON:

{
  "error": {
    "code": "VALIDATION",
    "message": "phone must be a valid E.164 number",
    "details": { … }
  }
}

Běžné HTTP kódy:

  • 400 — neplatný vstup (VALIDATION; message má detaily)
  • 401 — chybějící / neplatná autentizace (UNAUTHENTICATED)
  • 402 — zůstatek peněženky nebo kreditní limit hovor nepokrývá (PAYMENT_REQUIRED)
  • 403 — auth OK, ale chybí scope (FORBIDDEN)
  • 404 — resource neexistuje nebo ho nevidíte (NOT_FOUND)
  • 409 — konflikt, např. znovupoužití idempotency-key s jiným body (CONFLICT)
  • 429 — dosažen rate limit (RATE_LIMIT)
  • 500 — bug platformy (INTERNAL); na tyhle dostáváme alert

Verzování

Aktuální verze je v1. Aditivní změny — nová pole, nové endpointy — se dodávají bez upozornění a konvencí jsou non-breaking: pole, která nerozpoznáte, ignorujte. Breaking změny dostanou novou major verzi se sunset oknem oznámeným každému aktivnímu integrátorovi.