API-Einführung

OurAiCalling stellt eine REST-API unter deiner Plattform-Domain bereit. Alles, was du im Dashboard machen kannst – Assistenten verwalten, Anrufe starten, Kampagnen steuern, Transkripte lesen – ist auch programmatisch verfügbar.

Basis-URL

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

app.famulor.io ist die gehostete Plattform. Meldest du dich über eine White-Label-Mandantendomain an, nutze stattdessen diese Domain – die API läuft dort mit dem Branding des Mandanten, es gelten dieselben Pfade.

Authentifizierung

Alle Anfragen erfordern ein Bearer-Token im Authorization-Header. Zwei Token-Typen werden akzeptiert:

API-Schlüssel (fam_...) – erstelle sie unter Einstellungen → API-Schlüssel. Der vollständige Schlüssel wird bei der Erstellung nur einmal angezeigt, gespeichert wird ausschließlich ein Hash. Schlüssel lassen sich optional auf Scopes beschränken (z. B. assistants:read, calls:write, campaigns:write, dashboards:read, dashboards:write, leads:write, phone_numbers:write, sip_trunks:write, knowledge:write, voices:read, billing:read) und mit einem Ablaufdatum versehen. Ohne Scope-Einschränkung hat ein Schlüssel vollen Zugriff; ein *:write-Scope schließt das passende *:read automatisch mit ein. Ideal für Server-zu-Server-Integrationen. Dashboard-Endpunkte akzeptieren zusätzlich calls:read/write, sodass OAuth-Clients mit den vier Standard-Scopes kompatibel bleiben.
OAuth-2.0-Access-Tokens (fam_at_...) – ausgestellt über den OAuth-Flow der Plattform (Authorization Code + PKCE, dynamische Client-Registrierung). Scoped und kurzlebig (1 Stunde, mit Refresh-Tokens). Ideal für Drittanbieter-Apps, die im Auftrag eines Nutzers handeln.

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

Behandle API-Schlüssel wie Passwörter. Bette sie niemals in Client-seitigen Code ein – nutze für Browser-Anwendungsfälle stattdessen den OAuth-Flow.

Response-Envelope

Jeder Endpunkt antwortet mit einer einheitlichen JSON-Struktur. Bei Erfolg steckt die Payload in data (plus optionalem meta):

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

Was die API zurückgibt – und was nicht

REST-API und MCP-Endpoint liefern denselben, bewusst kuratierten Blick auf deine Workspace-Daten: alles, was du zum Bauen brauchst – nichts darüber, wie die Plattform intern arbeitet. In keiner Antwort enthalten:

Infrastruktur-IDs – Medien-Session-, Room-, Trunk-, Dispatch- und Carrier-IDs des darunterliegenden Telefonie-Stacks.
Interne Storage-Pfade – Aufnahmen kommen als zeitlich begrenzte signierte URL (GET /calls/{id}/recording), nie als Bucket-Pfad.
Plattform-Kosten und Abrechnungs-Interna – Provider-Kosten, Token-/Zeichen-/Sekunden-Zähler und Buchungs-Status. Dein eigener Verbrauch wird in den Einheiten ausgewiesen, in denen abgerechnet wird: Minuten und Credits (GET /balance, GET /transactions).
Modell-Interna – welches Modell einen Anruf bewertet oder die Zusammenfassung geschrieben hat. Ergebnis, Score und Zusammenfassung kommen zurück, die Engine dahinter nicht.
Secrets – Passwörter, Tokens und Carrier-Zugangsdaten sind nach dem Speichern nie wieder lesbar; höchstens ein maskierter Hinweis.
Betriebsdiagnostik – interne Call-Events (Komponenten-Fallbacks, Session-Fehler, Verbrauchsbuchungen) werden in den Events von GET /calls/{id} herausgefiltert.

Alles andere steht dir offen: Transkripte, Zusammenfassungen, Analyse-Ergebnisse, extrahierte Felder, QA-Scores, Kontakte, Kampagnen, Nummern und die komplette Assistant-Konfiguration.

Pagination

Listen-Endpunkte werden über die Query-Parameter limit und offset paginiert:

Parameter	Standard	Max	Beschreibung
`limit`	`50`	`200`	Seitengröße
`offset`	`0`	—	Zu überspringende Einträge

Das meta.pagination.total der Antwort enthält die Gesamtzahl der Treffer (unabhängig von limit/offset), sodass du blättern kannst, bis offset + limit >= total:

curl "https://app.famulor.io/api/v1/calls?limit=100&offset=200" \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"

Fehler

Bei einem Fehler bekommst du eine Fehlerstruktur mit einem stabilen, maschinenlesbaren code und einer für Menschen lesbaren message:

{
  "error": {
    "code": "invalid_request",
    "message": "\"to_number\" is required (E.164 format, e.g. +4930123456)."
  }
}

Status	Code	Bedeutung
`400`	`invalid_request`	Ungültiger Request-Body oder ungültige Parameter
`401`	`unauthorized`	Fehlendes, ungültiges, abgelaufenes oder widerrufenes Token
`403`	`forbidden`	Scope fehlt, oder dein Plan enthält dieses Feature nicht
`404`	`not_found`	Ressource nicht gefunden (oder gehört dir nicht)
`409`	`conflict`	Ressource befindet sich in einem Konfliktzustand (z. B. eine Kampagne stoppen, die gerade nicht läuft)
`429`	`rate_limited`	Rate Limit überschritten – etwas warten und erneut versuchen
`500`	`internal_error`	Unerwarteter Serverfehler

Rate Limits

Pro Account gelten Fair-Use-Rate-Limits. Überschreitest du sie, antwortet die API mit 429 Too Many Requests – warte dann und versuche es mit exponentiellem Backoff erneut. Die veröffentlichten Limits pro Plan werden hier dokumentiert.

White Label: Verwalte die Kunden deiner Plattform

Wenn dein Workspace das White-Label-Feature hat, steuerst du deine eigene Plattform über eine eigene Endpoint-Gruppe komplett programmatisch: Endkunden auflisten und registrieren, API-Tokens für sie ausstellen (mit oder ohne deren Passwort), abmelden, Credits zwischen deinem Wallet und ihren Workspaces bewegen und die Custom Domain deiner Plattform verwalten. Plattform-Admins der Haupt-Plattform nutzen dieselben Endpunkte für ihre direkten Kunden. Alle Endpunkte erfordern einen API-Schlüssel deines White-Label-Workspace mit den Scopes platform:read / platform:write (Custom Domain: settings:*):

Endpunkt	Zweck
`GET /platform/users`	Endkunden deiner Plattform auflisten (paginiert, Suche über `q`)
`POST /platform/users`	Neuen Endkunden registrieren (Einladungs-E-Mail oder gesetztes Passwort)
`GET /platform/users/{user_id}`	Kundendetail inkl. Workspaces und Guthaben
`POST /platform/users/{user_id}/token`	API-Token für einen Kunden ausstellen – ohne dessen Passwort
`POST /platform/users/login`	Kunden mit E-Mail + Passwort authentifizieren und dessen API-Token erhalten
`POST /platform/users/{user_id}/logout`	API-Tokens eines Kunden widerrufen
`POST /platform/users/{user_id}/balance`	Credits übertragen: positiv = dem Kunden aus deinem Wallet gutschreiben, negativ = zurückholen (nie unter null)
`GET /custom-domain`	Custom-Domain-Status deiner Plattform
`POST /custom-domain`	Custom Domain verbinden (Antwort enthält die zu setzenden DNS-Records)
`POST /custom-domain/verify`	DNS erneut prüfen und Domain aktivieren
`DELETE /custom-domain`	Custom Domain entfernen

Schritt-für-Schritt-Rezepte (eigene Auth-Flows, Dashboards, Guthaben-Verwaltung): White-Label-API-Guide. Dieselben Funktionen gibt es als MCP-Tools über das platform-Toolset (https://<deine-domain>/mcp?toolsets=platform).

MCP – Verwende die API als KI-Tools

Alles aus dieser Referenz steht auch über den MCP-Endpunkt der Plattform zur Verfügung (Model Context Protocol, Streamable HTTP):

https://app.famulor.io/mcp

Verbinde Claude, ChatGPT, Cursor oder einen beliebigen MCP-Client und nutze dieselben Funktionen als KI-Tools – dieselben Services, dieselbe Validierung (Plan-Limits, Modellkatalog, DNC-Prüfungen) und dasselbe Berechtigungsmodell (API-Schlüssel oder OAuth). Erfordert das Plan-Feature Connect AI / MCP. Vollständige Einrichtungsanleitung: MCP endpoint. Schnellverbindung – Claude und ChatGPT erkennen die Authentifizierung automatisch (OAuth); andere Clients können einen API-Schlüssel als statischen Bearer-Header übergeben:

claude mcp add --transport http voice-ai https://app.famulor.io/mcp \
  --header "Authorization: Bearer fam_XXXXXXXXXXXX"

{
  "mcpServers": {
    "voice-ai": {
      "url": "https://app.famulor.io/mcp",
      "headers": { "Authorization": "Bearer fam_XXXXXXXXXXXX" }
    }
  }
}

{
  "mcpServers": {
    "voice-ai": {
      "command": "npx",
      "args": ["mcp-remote", "https://app.famulor.io/mcp"]
    }
  }
}

Verfügbare MCP-Tools

Bereich	Tools
Assistenten	`list_assistants`, `get_assistant`, `create_assistant`, `update_assistant`, `delete_assistant`
Stimmen	`get_voices`
Anrufe	`list_calls`, `get_call`, `make_call`
Verlauf	`list_history`, `get_email_history_item`
Workspace-Einstellungen	`list_email_senders`, `get_custom_domain`, `add_custom_domain`, `verify_custom_domain`, `remove_custom_domain`, `get_memory_settings`, `update_memory_settings`, `get_ai_inference_settings`, `update_ai_inference_settings`
Kampagnen	`list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `delete_campaign`, `start_campaign`, `stop_campaign`
Leads	`list_leads`, `add_lead`, `add_leads`, `remove_lead_from_campaign`, `delete_lead` (Legacy-Alias)
Telefonnummern	`list_phone_numbers`, `search_phone_numbers`, `buy_phone_number`, `release_phone_number`, `assign_phone_number`
SIP-Trunks	`list_sip_trunks`, `get_sip_trunk`, `create_sip_trunk`, `delete_sip_trunk`
Wissensdatenbanken	`list_knowledge_bases`, `get_knowledge_base`, `create_knowledge_base`, `delete_knowledge_base`, `add_document`
Konto & Abrechnung	`get_balance`, `get_me`, `get_usage_summary`
API-Schlüssel	`list_api_keys`, `create_api_key`, `revoke_api_key`
White Label	`list_platform_users`, `get_platform_user`, `register_platform_user`, `create_platform_user_token`, `logout_platform_user`, `transfer_platform_credits`

API-Referenz

Konto & Abrechnung

API-Schlüssel

Migrationen

Automatisierungen

Assistenten

Stimmen

Verlauf

Anrufe

Kampagnen

Leads

Segmente

Rufnummern

SIP-Trunks

Carrier-Verbindungen

Workspace-Einstellungen

Einwilligung & Suppression

Wissensdatenbanken

Kalender-Integrationen

Buchungen

E-Mail-Kanal

White Label

Basis-URL

Authentifizierung

Response-Envelope

Was die API zurückgibt – und was nicht

Fehler

Rate Limits

White Label: Verwalte die Kunden deiner Plattform

MCP – Verwende die API als KI-Tools

Verfügbare MCP-Tools

​Basis-URL

​Authentifizierung

​Response-Envelope

​Was die API zurückgibt – und was nicht

​Pagination

​Fehler

​Rate Limits

​White Label: Verwalte die Kunden deiner Plattform

​MCP – Verwende die API als KI-Tools

​Verfügbare MCP-Tools

Basis-URL

Authentifizierung

Response-Envelope

Was die API zurückgibt – und was nicht

Pagination

Fehler

Rate Limits

White Label: Verwalte die Kunden deiner Plattform

MCP – Verwende die API als KI-Tools

Verfügbare MCP-Tools