SIHUB DOKUMENTATION

REST API und Authentifizierung

Die aktuelle, maschinenlesbare Spezifikation liegt unter /api/openapi.json. Ressourcen gehören immer zum Arbeitsbereich des Kontos bzw. API-Schlüssels. Du übergibst keine frei wählbare fremde Arbeitsbereich-ID an die Entity-Endpunkte.

API-Schlüssel

Owner/Admin legen Schlüssel mit read, write und/oder chat an. Der vollständige Token wird nur bei Erstellung zurückgegeben und anschließend ausschließlich als SHA-256-Hash gespeichert. Kopiere ihn in einen Secret Manager oder eine sichere Prozessumgebung.

curl http://127.0.0.1:5090/api/entities/agents \
  -H "Authorization: Bearer $AIHUB_API_KEY"

read erlaubt gewöhnliche Leseaktionen, write Änderungen und manuelle Tools, chat Playground, Einzelanrufe, Kampagnenstarts und Sprachendpunkte. Ein Schlüssel besitzt Editorrechte; Einstellungen, Teamverwaltung, Schlüsselverwaltung und vollständiger Arbeitsbereichexport bleiben der Owner/Admin-Sitzung vorbehalten.

Browsersitzung und CSRF

Alternativ authentifiziert das Sitzungscookie. GET /api/bootstrap liefert einen sitzungsgebundenen csrf-Wert. Sende diesen bei POST/PATCH/DELETE/PUT als X-CSRF-Token. Authformulare verwenden csrf_token. Bearer-Anfragen benötigen keinen zusätzlichen CSRF-Token. Öffentliche Widget- und signierte Twilio-Callbacks verwenden ihren eigenen Zugangspfad.

Daten ändern

/api/entities/{kind} unterstützt Liste und Erstellung; /api/entities/{kind}/{id} Lesen, PATCH und DELETE. Mögliche Arten: agents, knowledge, tools, channels, campaigns, contacts, tasks, reviews. Der allgemeine Body besteht aus name, optional status und einem modulabhängigen data-Objekt.

Bei PATCH wird ein angegebenes data-Objekt vollständig ersetzt, nicht rekursiv zusammengeführt. Lade vorhandene Daten deshalb zuerst, ändere benötigte Felder und sende das vollständige Objekt zurück. Feldzuordnungen wie Wissens-/Tool-/Agent-IDs werden arbeitsbereichbezogen geprüft.

{"agent_id": "AGENT_ID", "message": "Wann ist geöffnet?", "mode": "test"}

Dieser Body an POST /api/chat liefert reply, conversation_id und mode. Gib die Gesprächs-ID für weitere Nachrichten zurück. Wissenimport verwendet Multipart; Sprachtranskription das Multipartfeld audio. Die maximale Anforderung beträgt 2 MB einschließlich Multipartoverhead.

Fehler enthalten normalerweise {"error":"..."} unter /api/. Typische Statuscodes sind 400, 401, 403, 404, 409, 413, 429 und 502. Live-Anbieterfehler werden nicht durch Demoantworten ersetzt. Die Limits gelten serverseitig; erhöhe Nutzung nicht durch parallele Wiederholungen.

Realtime und Verbrauch

GET /api/voice/status liefert LiveKit-Konfigurationsstatus und gemeinsame Redis-Belegung. GET /api/voice/latency liefert gemessene Latenzen mit Quelle, Stichprobenzahl und Schätzungskennzeichnung. Die Anzeige eines Kapazitätsziels ist kein erfolgreicher Lasttest.

POST /api/voice/web-session benötigt {"channel_id":"WEBVOICE_KANAL_ID"} und den Scope chat. Es reserviert Kapazität und gibt die LiveKit-URL, einen raumgebundenen kurzlebigen Mikrofontoken, room_name und conversation_id zurück. SIP-Outbound verwendet weiterhin /api/test-call mit ausdrücklich gewähltem mode=live und bestätigter Einwilligung.

GET /api/usage?month=2026-10 liefert Monatsaggregate und bis zu 1.000 Detailzeilen. Der Zeitraum basiert auf UTC und dem letzten Ledgerupdate. total.prices_configured und total.revenue_configured kennzeichnen Kosten-/Umsatztarife getrennt. Geldbeträge werden als ganzzahlige Mikro-EUR ausgegeben (1.000.000 = 1 EUR). GET /api/usage/export?month=2026-10 exportiert alle passenden Zeilen als CSV. Es handelt sich um konfigurierte Schätzungen, keine Provider-/Kundenrechnung.

Die /internal/voice/*-Endpunkte dienen ausschließlich dem separaten Worker mit Betreiber-Bearertoken und sitzungsgebundenen Kennungen. Kunden-API-Keys berechtigen nicht zu diesem Zugriff. Sie stehen nicht im öffentlichen API-Vertrag.

Eigene kleine Python- und JavaScript-Clients

Im Repository liegen sdk/aihub.py und sdk/aihub.mjs. Sie bieten Entity-Liste, Erstellung/Aktualisierung, Veröffentlichung, Chat und Gesprächsdetails sowie einen allgemeinen REST-Aufruf. Es sind eigene kleine Clients, keine veröffentlichten Registry-Pakete und keine vollständigen TypeScript-Typdefinitionen.

Python-Beispiel vom Projektverzeichnis aus:

import os
from sdk.sihub import SIHub

client = SIHub("http://127.0.0.1:5090", os.environ["AIHUB_API_KEY"])
try:
    agents = client.entities("agents")
    result = client.chat(agents[0]["id"], "Wann ist geöffnet?", mode="test")
    print(result["reply"])
finally:
    client.close()

JavaScript-Beispiel als .mjs-Datei im Projektverzeichnis mit serverseitigem fetch:

import { SIHub } from './sdk/sihub.mjs';

const client = new SIHub({
  baseUrl: 'http://127.0.0.1:5090',
  apiKey: process.env.AIHUB_API_KEY
});
const agents = await client.entities('agents');
const result = await client.chat(agents[0].id, 'Wann ist geöffnet?', {mode: 'test'});
console.log(result.reply);

Beide Beispiele benötigen einen passenden Arbeitsbereichschlüssel, mindestens einen Agenten und die erforderlichen Scopes. Betreibe Clients mit API-Keys serverseitig; öffentliche Browserwidgets benötigen einen getrennten öffentlichen Kanal.

← Alle Artikel OpenAPI-Spezifikation ↗