API-Einführung

Mit der Famulor-REST-API verwaltest du dieselben Kundenressourcen wie im Dashboard, darunter Assistenten, Anrufe, Kampagnen, Transkripte, Wissen und Workspace-Einstellungen.

Für einen mehrstufigen Geschäftsprozess – einen Lead anreichern, dann anrufen, dann ein CRM aktualisieren, dann einen Kanal benachrichtigen – ist eine Automatisierung oft weniger Code, um sie am Laufen zu halten, als die Schritte selbst zu verdrahten. Greif direkt zur API, wenn du einfache, sofortige, programmatische Kontrolle brauchst, etwa um einen einzelnen Anruf aus deiner eigenen App auszulösen.

Basis-URL

https://app.famulor.io/api/v1

Bei einer White-Label-Domain ersetzt du app.famulor.io durch diese Domain. Die Pfade bleiben gleich.

API Access

REST-Anfragen benötigen API Access über den Workspace-Plan oder ein wiederkehrendes Add-on. Wird der Zugriff entfernt, bleiben bestehende API-Keys und OAuth-Zugangsdaten für Workspace-Administratoren zur Prüfung und zum Widerruf verfügbar; reguläre /api/v1-Anfragen liefern jedoch 403 api_access_required. Nach einer fehlgeschlagenen Planzahlung bleiben POST /api/v1/billing/invoice-payment und POST /api/v1/billing/portal mit gültigen Zugangsdaten erreichbar, damit ein Owner die Abrechnung wiederherstellen kann. Authentifizierungs-, Rollen- und Scope-Prüfungen gelten weiterhin.

Authentifizierung

Sende ein Bearer-Token im Authorization-Header:

curl https://app.famulor.io/api/v1/assistants \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"

Zwei Arten von Credentials werden unterstützt:

Workspace API keys (fam_...) – erstelle sie unter Settings → API & MCP für Server-zu-Server-Integrationen. Der vollständige Key wird einmal angezeigt. Das Dashboard hat keine Scope-Auswahl, daher trägt ein dort erstellter Key immer alle Scopes. Um einen eingeschränkteren Key zu erzeugen, rufe POST /api/v1/api-keys oder POST /api/v1/workspaces/{workspace_id}/api-keys mit einem expliziten scopes-Array auf – die Scopes des neuen Keys müssen eine Teilmenge der Zugangsdaten sein, die ihn erstellen.
OAuth 2.0 access tokens (fam_at_...) – verwende Authorization Code mit PKCE-S256 für Anwendungen, die im Namen eines angemeldeten Nutzers handeln.

Durch Nutzer autorisierter Zugriff folgt immer der aktuellen Workspace-Mitgliedschaft und Rolle. Workspace-API-Keys folgen ihrem eigenen Status und ihren Scopes, bis ein berechtigter Workspace-Admin sie widerruft.

Behandle API-Keys wie Passwörter. Bette sie niemals in Browser- oder Mobile-App-Code ein; verwende OAuth für nutzerseitige Anwendungen.

Umgang mit Keys

Speichere Keys in Umgebungsvariablen oder einem Secrets-Manager, nie in der Versionskontrolle.
Beschränke jeden Key auf das, was die Integration wirklich braucht – ein Key, der nur Anrufe liest, sollte nicht zusätzlich assistants:write haben. Im Dashboard erstellte Keys haben immer vollen Zugriff; nutze den API-Weg von oben, um einen eingeschränkten Key zu erzeugen.
Rotiere Keys regelmäßig und sofort, sobald jemand mit Zugriff auf einen Key das Team verlässt.
Das Widerrufen eines Keys unter Settings → API & MCP wirkt sofort; bereits laufende Anfragen können trotzdem noch abgeschlossen werden.

Anforderungen an OAuth-Clients

Ein selbst gebauter Client steuert die Authorization- und Token-Endpunkte direkt an:

https://app.famulor.io/api/oauth/authorize
https://app.famulor.io/api/oauth/token

Verwende HTTPS-Redirect-URLs. Native Anwendungen dürfen zusätzlich literale HTTP-Loopback-Adressen wie 127.0.0.1 verwenden. OAuth-Anfragen müssen PKCE-S256 nutzen und dürfen nur für den Client registrierte Scopes anfordern. Bei einer Ratenbegrenzung wartest du die in der Antwort angegebene Zeit und versuchst es erneut. Der Client verwendet entweder für deinen Workspace vorab genehmigte Zugangsdaten oder registriert sich dynamisch selbst über POST /api/oauth/register – gib dabei zwischen 1 und 10 eindeutige redirect_uris an. Endpunkte, unterstützte Scopes und Grant-Typen lassen sich unter /.well-known/oauth-authorization-server ermitteln. Ein dynamisch registrierter Client, den der Nutzer noch nicht freigegeben hat, erhält keine Fehler an seiner Redirect-URL: Eine ungültige Autorisierungsanfrage wird stattdessen direkt auf der Autorisierungsseite beantwortet. Nach der Freigabe erhalten spätere Anmeldungen nur die Tool-Gruppen, die der Nutzer ausgewählt hat; fordert der Client mehr an, erscheint der Zustimmungsbildschirm erneut. Access-Tokens werden über den refresh_token-Grant erneuert. Refresh-Tokens rotieren bei jeder Verwendung: Das Anfordern eines neuen Access-Tokens stellt auch ein neues Refresh-Token aus und macht das gesendete sofort ungültig.

Antwortformat

Erfolgreiche Antworten enthalten das Ergebnis in data und optional meta:

{
  "data": [{ "id": "…", "name": "Support Agent" }],
  "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } }
}

Antworten enthalten ausschließlich kundenrelevante Workspace-Daten. Geheimnisse werden nach dem Speichern nie wieder ausgegeben, und sensible Werte werden bei Bedarf maskiert. Aufzeichnungen stehen über temporäre Links bereit. Nutzung und Abrechnung werden in den Minuten und Credits deines Kontos angezeigt.

Pagination

Listen-Endpunkte verwenden limit und offset:

Parameter	Standard	Maximum	Beschreibung
`limit`	`50`	`200`	Anzahl der zurückgegebenen Einträge
`offset`	`0`	–	Anzahl der übersprungenen Einträge

Mit meta.pagination.total erkennst du, ob weitere Seiten verfügbar sind.

Fehler

Fehlschläge liefern einen stabilen Code und eine lesbare Meldung:

{
  "error": {
    "code": "invalid_request",
    "message": "A destination phone number is required."
  }
}

Status	Code	Bedeutung
`400`	`invalid_request`	Ungültiger Request-Body oder ungültige Parameter
`401`	`unauthorized`	Credential fehlt, ist ungültig, abgelaufen oder widerrufen
`403`	`forbidden`	Scope, Rolle oder Plan erlauben die Aktion nicht
`403`	`api_access_required`	API Access ist für diesen Workspace nicht verfügbar
`404`	`not_found`	Ressource nicht gefunden oder für diesen Workspace nicht sichtbar
`409`	`conflict`	Die Ressource befindet sich in einem widersprüchlichen Zustand
`429`	`rate_limited`	Zu viele Anfragen; warten und erneut versuchen
`500`	`internal_error`	Unerwarteter Fehler

White-Label-Kundenverwaltung

Berechtigte Reseller können über die platform-Endpunkte ihre eigenen Endkunden verwalten, Kunden-API-Tokens ausstellen und widerrufen, Credits übertragen und ihre Custom Domain verwalten. Diese Endpunkte benötigen die Scopes platform:read oder platform:write; Custom-Domain-Aktionen verwenden den entsprechenden Settings-Scope.

Endpunkt	Zweck
`GET /api/v1/platform/users`	Eigene Endkunden auflisten
`POST /api/v1/platform/users`	Einen Endkunden registrieren
`GET /api/v1/platform/users/{user_id}`	Kontoübersicht eines Endkunden lesen
`POST /api/v1/platform/users/{user_id}/token`	Ein API-Token für diesen Endkunden ausstellen
`POST /api/v1/platform/users/login`	Einen Endkunden authentifizieren
`POST /api/v1/platform/users/{user_id}/logout`	Die API-Tokens dieses Endkunden widerrufen
`POST /api/v1/platform/users/{user_id}/balance`	Credits zwischen deinem Reseller-Guthaben und dem Endkunden übertragen
`GET /api/v1/custom-domain`	Custom-Domain-Status lesen
`POST /api/v1/custom-domain`	Eine Custom Domain hinzufügen und die benötigten DNS-Einträge erhalten
`POST /api/v1/custom-domain/verify`	DNS prüfen und eine fertig eingerichtete Domain aktivieren
`DELETE /api/v1/custom-domain`	Die Custom Domain entfernen

Beispiele findest du im Leitfaden zur White-Label-API.

CLI

Jede API-Operation ist auch ein Befehl in der Famulor CLI. Dein API-Key wird dabei im Schlüsselbund deines Systems gespeichert:

npm install --global famulor
famulor auth login
famulor list-assistants --output table

Die CLI verwendet dieselben API-Keys, Scopes und Anfragelimits sowie denselben API Access wie die REST-API.

MCP

Dieselben kundenseitigen Funktionen stehen als KI-Tools über den MCP-Endpunkt bereit:

https://app.famulor.io/mcp

MCP verwendet dieselben API-Keys, dieselbe OAuth-Zustimmung, dieselben Scopes und denselben Workspace-Zugriff. Die Verfügbarkeit wird separat über Connect AI / MCP gesteuert, nicht über API Access.

Realtime-Varianten und Gesprächsstimmen

Erstelle oder aktualisiere einen Assistenten mit mode: "realtime" und realtime_variant: "full_duplex", um die Variante bei entsprechendem Workspace-Zugriff zu aktivieren. Ohne Variante bleibt bei neuen Assistenten Standard aktiv; bei Updates bleibt die vorhandene Variante erhalten. Das Denkmodell wird zentral verwaltet. Gespeicherte Pipeline-Modellpräferenzen des Assistenten überschreiben es nicht. Mit GET /api/v1/voices?mode=realtime&realtime_variant=full_duplex findest du kompatible Stimmen. Übergib die zurückgegebene Stimmen-id als realtime_voice; Full Duplex verwendet sie auch für Begrüßungen, Einwilligung und Tool-Ansagen. Behalte tts_voice als gespeicherte Pipeline-Ausweichstimme. Hochgeladene Begrüßungen behalten ihre aufgenommene Stimme. Stimmenkennungen sind undurchsichtig; leite daraus keinen Anbieter ab. Nicht verfügbare Stimmen oder Varianten werden abgelehnt. Für TTS-Stimmen verwende GET /api/v1/voices?mode=tts&language=de ohne realtime_variant. mode=tts zusammen mit einer Realtime-Variante ergibt 400. CLI: famulor list-voices --mode tts --language de; für Full Duplex: famulor list-voices --mode realtime --realtime-variant full_duplex --language de. Wenn eine native Hörprobe verfügbar ist, enthält preview_url einen relativen API-Pfad. Ergänze deine API-Domain und lade die Datei mit demselben Bearer-Token und dem Scope voices:read. GET /api/v1/voices/{id}/preview?realtime_variant=full_duplex liefert WAV-Audio, ohne eine neue Hörprobe zu generieren. Der MCP-Stimmenkatalog enthält denselben Vorschau-Verweis. Gespeicherte TTS-Hörproben erhältst du über GET /api/v1/voices/{id}/preview?mode=tts oder per CLI mit famulor get-voice-preview --id <voice-id> --mode tts. Verwende die zurückgegebene preview_url; bei fehlender Hörprobe steht dort null. Der Download erzeugt kein neues Audio. Für Standard Realtime verwende realtime_variant=standard mit dem zurückgegebenen Vorschau-Link oder famulor get-voice-preview --id <voice-id> --realtime-variant standard. Gespeichertes Audio kann MP3 oder WAV sein. Mit Zugriff auf die Modellauswahl enthält der Standard-Katalog die Stimmen aller aktivierten, mit der Workspace-Region kompatiblen Modelle. Beim Wechsel zu einer Stimme eines anderen Modells wählst du im selben Assistant-Update ein kompatibles Modell. Wenn dein Plan die Modellauswahl erlaubt, listet GET /api/v1/models?type=realtime&realtime_variant=full_duplex kompatible Sprachmodelle auf. Eine Auswahl des Denkmodells wird dadurch nicht freigeschaltet. Die Usage-Antwort enthält aktuelle Credit-Preise. Bei gemeinsamer Nutzung fallen die Aufpreise für Full Duplex und Avatar zusammen an. Regionale Verfügbarkeit: Full Duplex richtet sich nach den freigeschalteten Modellen der gewählten Workspace-Region, einschließlich EU, US und Global. Voraussetzung sind Beta-Zugriff, Realtime-Zugriff im Plan sowie passende Sprach- und Denkmodelle. Editor, API und MCP verwenden dieselben Verfügbarkeitsregeln. MCP verwendet dieselben Assistentenfelder. Das Tool get_voices akzeptiert mode und realtime_variant; get_models akzeptiert realtime_variant. Unterstützte Einstellungen und Einschränkungen findest du unter Engine-Modi.

Anfragelimits

REST-Anfragen teilen sich über alle Endpunkte hinweg ein festes Minutenbudget: standardmäßig 120 Anfragen pro API-Key oder OAuth-Zugriffstoken und 600 Anfragen pro Workspace. Dein Plan kann andere Limits vorsehen. Zusätzliche Keys oder ein Domainwechsel erhöhen das Workspace-Budget nicht. Ein separates Limit von 1.800 Anfragen pro Minute und IP-Adresse schützt die Prüfung der Zugangsdaten; Integrationen hinter derselben IP teilen sich dieses Limit. Ist ein Budget aufgebraucht, antwortet die API mit 429, error.code: "rate_limited" und dem Header Retry-After mit der Wartezeit in Sekunden. Pausiere Anfragen entsprechend und verwende für Wiederholungen zunehmende Wartezeiten mit einer kleinen Zufallsverzögerung. Vermeide ständiges Polling und nutze nach Möglichkeit Webhooks. Ist der Anfrageschutz vorübergehend nicht verfügbar, antwortet die API mit 503 und einer Wartezeit. Für Dashboard und MCP gelten eigene Zugriffs- und Anfrageregeln.

​Basis-URL

​API Access

​Authentifizierung

​Umgang mit Keys

​Anforderungen an OAuth-Clients

​Antwortformat

​Pagination

​Fehler

​White-Label-Kundenverwaltung

​CLI

​MCP

​Realtime-Varianten und Gesprächsstimmen

​Anfragelimits

Basis-URL

API Access

Authentifizierung

Umgang mit Keys

Anforderungen an OAuth-Clients

Antwortformat

Pagination

Fehler

White-Label-Kundenverwaltung

CLI

MCP

Realtime-Varianten und Gesprächsstimmen

Anfragelimits