API-Referenz

Die Schnittstelle ansehen, authentifizieren und die häufigsten Aufgaben umsetzen.

Geschrieben von Thomas Seidl

Zuletzt aktualisiert Vor etwa 1 Monat

Wo du sie findest

Im Studio unter API-Referenz. Die Schnittstelle ist dort vollständig dokumentiert, nach Fähigkeiten gruppiert, und du kannst Aufrufe direkt auf der Seite ausprobieren.

Die API deckt dieselben Fähigkeiten ab wie die Oberfläche: Agenten bereitstellen, Anrufe führen und entgegennehmen, Auswertungen und Nutzungsdaten lesen. Damit lässt sich Lane One in dein eigenes Produkt oder deine Back-Office-Werkzeuge einbetten.

Authentifizierung

Der Schlüssel geht als Header bei jedem Aufruf mit:

Ocp-Apim-Subscription-Key: <dein-api-schlüssel>

Das ist kein Authorization: Bearer-Header. Wer aus Gewohnheit Bearer verwendet, bekommt einen Fehler, der nicht sofort nach einem Header-Problem aussieht — das ist der häufigste Einstiegsfehler.

Schlüssel legst du unter Einstellungen → API-Schlüssel an. Halte sie serverseitig: niemals in Browser- oder App-Code ausliefern.

Zum Prüfen: GET /core/chains/me. Kommt eine 200 mit deinem Konto zurück, funktioniert der Schlüssel.

Scopes

Jeder Schlüssel trägt Scopes, die entscheiden, welche Endpunkte er aufrufen darf — etwa agents:read, agents:write, analytics:read, integrations:write, workflow:read. Ein Aufruf außerhalb der Scopes endet mit 403.

Bekommst du unerwartet eine 403, prüfe zuerst die Scopes des Schlüssels — nicht den Endpunkt.

Ein Sonderfall: recordings:read ist bewusst von analytics:read getrennt. Aufzeichnungen enthalten das rohe Gespräch, nicht nur Kennzahlen und Transkript-Metadaten. Vergib den Scope nur, wenn die anbindende Anwendung Audio wirklich braucht.

Die wichtigsten Begriffe

  • Dein Konto ist eine Chain — ein Schlüssel gehört zu genau einer, und jeder Aufruf liest und schreibt deren Daten.
  • Ein Template ist der wiederverwendbare Bauplan, den du in der Oberfläche entwirfst. Ein Agent ist die daraus bereitgestellte, laufende Instanz. Ein Template kann viele Agenten tragen.
  • Eine Integration wird als Vorlage deklariert und beim Bereitstellen mit Konfiguration zu einer laufenden Instanz.

Typische Aufgaben

Agenten bereitstellen

GET /builder/templates/released listet die bereitstellbaren Templates. GET /builder/templates/released/<templateID>/wizard-config sagt dir, welche Version und welche Konfigurationsfelder gebraucht werden. Mit POST /builder/deployments stellst du bereit; die ID des laufenden Agenten steht in der Antwort unter artifacts.voiceagent.id.

Danach eine Rufnummer zuweisen: GET /conversational-ai/phone-numbers/mine und PATCH /conversational-ai/phone-numbers/mine/<nummer>/assign.

Ausgehende Anrufe auslösen

POST /conversational-ai/calls mit Agent-ID und Zielrufnummer. Über parameters gibst du dem Gespräch Kontext mit — Name, Buchungsreferenz, was der Agent nennen soll. Beenden per DELETE /conversational-ai/calls/<sessionId>.

Auswertungen und Aufzeichnungen abholen

GET /evaluation-service/analytics/calls listet Anrufe mit Filtern und Seitenzahl. GET /evaluation-service/analytics/calls/<callId> liefert Transkript und Ergebnis. Die Audiodatei kommt über GET /evaluation-service/recordings/<callId>.

Verbrauchsdaten fürs Controlling

GET /billing/usage/customers/daily mit startDate und endDate liefert den Verbrauch je Tag.

Konventionen, die du kennen solltest

  • Fehler — normale HTTP-Statuscodes; der Body hat die Form { "success": false, "error": "..." }.
  • IDs — Agenten- und Template-IDs sind mit einem Präfix versehen (s2s_…). Gib sie unverändert weiter.
  • Datumsangaben — YYYY-MM-DD.
  • KPI-Zeitraum — auf 30 Tage begrenzt. Längere Auswertungen musst du in Abschnitte teilen.
  • Seitenzahl — Listen nehmen page/pageSize oder einen cursor; der genaue Weg steht am jeweiligen Endpunkt.

Wenn ein Analyse-Filter zu weit ist

Zwei Fälle sind ausdrücklich begrenzt:

  • Trifft ein Filter insgesamt mehr als 20.000 Anrufe, kommt ANALYTICS_FILTER_TOO_BROAD zurück — setze weitere Filter.
  • Enthält das gefilterte Zeitfenster mehr als 20.000 Anrufe, bekommst du die Liste mit "kpis": null und einem Vorschlag unter kpisMeta.suggestedFrom. Wiederhole den Aufruf mit diesem from, um die Kennzahlen zu erhalten.

Beides sind bewusste Grenzen, keine Fehler. Behandle sie in deiner Anwendung, statt sie als Ausfall zu werten.

Bevor du gegen die Schnittstelle baust

Probier den Aufruf zuerst in der Referenz aus und sieh dir die echte Antwort an. Das ist schneller als eine Implementierung gegen eine vermutete Struktur — und du erkennst sofort, ob dein Schlüssel den nötigen Scope hat.