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. 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.

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.

​Basis-URL

​API Access

​Authentifizierung

​Umgang mit Keys

​Anforderungen an OAuth-Clients

​Antwortformat

​Pagination

​Fehler

​White-Label-Kundenverwaltung

​MCP

Basis-URL

API Access

Authentifizierung

Umgang mit Keys

Anforderungen an OAuth-Clients

Antwortformat

Pagination

Fehler

White-Label-Kundenverwaltung

MCP