API-Dokumentation

Authentifizierung

Alle Session-Endpunkte werden mit Ihrem Tenant-API-Key als Bearer-Token authentifiziert:

Authorization: Bearer <API_KEY>

Widget einbinden

Der einfachste Weg auf die eigene Website: ein Script-Tag, das die gehostete Widget-Runtime lädt. Fertig konfigurierte Branchen-Vorlagen inklusive Ihres API-Keys erzeugt der Deploy-Tab im Dashboard – das Format sieht so aus:

<!-- KI-Assistent von bitpull.ai – einfach so lassen, wie er ist.
     Hilfe: support@bitpull.ai -->
<script src="https://bitpull.ai/widget/template.js"
        data-key="IHR_API_KEY"
        data-lang="de"
        data-modes="both"
        data-color="#2962ff"
        data-label="KI-Assistent"
        data-title="Schön, dass Sie da sind!"
        data-teasers="Was kann der Assistent?|Öffnungszeiten"
        defer></script>

• data-key – Ihr Tenant-API-Key
• data-lang – de oder en
• data-modes – verfügbare Modi: voice, chat oder both
• data-color, data-label, data-title, data-teasers – Optik und Texte (Teaser mit | getrennt)

Das Snippet vor der schließenden </body>-Zeile Ihrer Website einfügen. Der Assistent kennzeichnet sich gegenüber Ihren Besuchern transparent als KI.

REST-Endpunkte

Referenz der öffentlichen Endpunkte. Alle Requests gehen an https://api.bitpull.ai; außer /health erwarten alle den API-Key als Bearer-Token.

curl https://api.bitpull.ai/health

const res = await fetch('https://api.bitpull.ai/health');
const data = await res.json();
console.log(data.status);

curl https://api.bitpull.ai/api/sessions/languages \
  -H "Authorization: Bearer <API_KEY>"

const res = await fetch('https://api.bitpull.ai/api/sessions/languages', {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const { languages, defaultLanguage } = await res.json();

curl -X POST https://api.bitpull.ai/api/sessions \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"language": "de", "interactionMode": "VOICE"}'

const res = await fetch('https://api.bitpull.ai/api/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ language: 'de', interactionMode: 'VOICE' }),
});
const { sessionId, wsUrl, token } = await res.json();

curl https://api.bitpull.ai/api/sessions/<SESSION_ID> \
  -H "Authorization: Bearer <API_KEY>"

const res = await fetch(`https://api.bitpull.ai/api/sessions/${sessionId}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const session = await res.json();

curl -X POST https://api.bitpull.ai/api/sessions/<SESSION_ID>/end \
  -H "Authorization: Bearer <API_KEY>"

await fetch(`https://api.bitpull.ai/api/sessions/${sessionId}/end`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${API_KEY}` },
});

Verbindung per LiveKit

Das eigentliche Gespräch läuft über LiveKit: POST /api/sessions liefert wsUrl und token, mit denen Sie im Browser oder Backend einen LiveKit-Room verbinden – z. B. mit dem npm-Paket livekit-client.

import { Room } from 'livekit-client';

// 1. Session serverseitig anlegen (siehe POST /api/sessions)
const session = await createSession(); // { sessionId, wsUrl, token }

// 2. Mit wsUrl + token den LiveKit-Room verbinden
const room = new Room();
await room.connect(session.wsUrl, session.token);

// Audio des Agenten abspielen, eigenes Mikrofon freigeben (VOICE-Modus)
room.on('trackSubscribed', (track) => track.attach());
await room.localParticipant.setMicrophoneEnabled(true);

Im TEXT-Modus senden Sie Nachrichten als Text-Streams über den Room und empfangen die Antworten des Agenten als Transkript-Streams – ganz ohne Mikrofon.

Gute Praxis

• Sitzungen sauber beenden: Rufen Sie nach Gesprächsende POST /api/sessions/:id/end auf, statt die Verbindung nur clientseitig zu trennen.
• Rate Limits beachten: Die API begrenzt die Anzahl der Requests pro Zeitfenster. Cachen Sie selten wechselnde Antworten (etwa die Sprachliste) und wiederholen Sie Requests nach einem 429-Status nicht sofort, sondern mit Wartezeit.
• Keys rotieren: API-Keys lassen sich im Dashboard unter API-Zugang neu erzeugen. Rotieren Sie Keys regelmäßig und sofort, falls ein Key versehentlich öffentlich geworden ist.
• Fehler abfangen: Behandeln Sie Fehlerantworten (z. B. ungültiger Key, nicht konfigurierte Sprache) mit einem verständlichen Hinweis statt eines stummen Abbruchs.