> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API-Einführung
> Authentifiziere dich bei der REST-API und leg los
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
```text theme={null}
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.
```bash theme={null}
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`):
```json theme={null}
{
"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`:
```bash theme={null}
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`:
```json theme={null}
{
"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`](/api-reference/white-label/list-platform-users) | Endkunden deiner Plattform auflisten (paginiert, Suche über `q`) |
| [`POST /platform/users`](/api-reference/white-label/register-a-platform-user) | Neuen Endkunden registrieren (Einladungs-E-Mail oder gesetztes Passwort) |
| [`GET /platform/users/{user_id}`](/api-reference/white-label/get-a-platform-user) | Kundendetail inkl. Workspaces und Guthaben |
| [`POST /platform/users/{user_id}/token`](/api-reference/white-label/create-a-platform-user-token) | API-Token für einen Kunden ausstellen – ohne dessen Passwort |
| [`POST /platform/users/login`](/api-reference/white-label/log-in-a-platform-user) | Kunden mit E-Mail + Passwort authentifizieren und dessen API-Token erhalten |
| [`POST /platform/users/{user_id}/logout`](/api-reference/white-label/log-out-a-platform-user) | API-Tokens eines Kunden widerrufen |
| [`POST /platform/users/{user_id}/balance`](/api-reference/white-label/transfer-credits-to-or-from-a-platform-user) | Credits übertragen: positiv = dem Kunden aus deinem Wallet gutschreiben, negativ = zurückholen (nie unter null) |
| [`GET /custom-domain`](/api-reference/settings/get-custom-domain-status) | Custom-Domain-Status deiner Plattform |
| [`POST /custom-domain`](/api-reference/settings/add-custom-domain) | Custom Domain verbinden (Antwort enthält die zu setzenden DNS-Records) |
| [`POST /custom-domain/verify`](/api-reference/settings/check-custom-domain-dns) | DNS erneut prüfen und Domain aktivieren |
| [`DELETE /custom-domain`](/api-reference/settings/remove-custom-domain) | Custom Domain entfernen |
Schritt-für-Schritt-Rezepte (eigene Auth-Flows, Dashboards, Guthaben-Verwaltung): [White-Label-API-Guide](/de/admin/whitelabel-api). Dieselben Funktionen gibt es als MCP-Tools über das `platform`-Toolset (`https:///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):
```text theme={null}
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](/api/mcp).
**Schnellverbindung** – Claude und ChatGPT erkennen die Authentifizierung automatisch (OAuth); andere Clients können einen API-Schlüssel als statischen Bearer-Header übergeben:
```bash Claude Code theme={null}
claude mcp add --transport http voice-ai https://app.famulor.io/mcp \
--header "Authorization: Bearer fam_XXXXXXXXXXXX"
```
```json Cursor (~/.cursor/mcp.json) theme={null}
{
"mcpServers": {
"voice-ai": {
"url": "https://app.famulor.io/mcp",
"headers": { "Authorization": "Bearer fam_XXXXXXXXXXXX" }
}
}
}
```
```json mcp-remote (OAuth) theme={null}
{
"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` |