Endpunkte

Welche Bereiche die öffentliche API abdeckt — und wo die vollständige Referenz liegt.

Diese Seite gibt den Überblick, was die API kann. Feldnamen, Beispielantworten und die Möglichkeit, Aufrufe direkt auszuprobieren, findest du in der interaktiven API-Dokumentation — die ist die verbindliche Quelle und immer aktuell.

Alle Pfade unten sind relativ zur Basis-URL https://app.scaletalk.ai/api/public/v1.

Konto

Methode	Pfad	Zweck
`GET`	`/me`	Das eigene Konto — der beste Test, ob der Schlüssel funktioniert
`GET`	`/usage`	Verbrauchte Minuten im aktuellen Abrechnungszeitraum
`GET`	`/voices`	Verfügbare Stimmen
`GET`	`/prompt_templates`	Die Prompt-Vorlagen deines Kontos

Agenten

Methode	Pfad	Zweck
`GET` `POST`	`/agents`	Agenten auflisten, neuen Agenten anlegen
`GET` `PATCH` `DELETE`	`/agents/{id}`	Einzelnen Agenten lesen, ändern, löschen
`POST`	`/agents/{id}/duplicate`	Agenten kopieren
`POST`	`/agents/{id}/generate_prompt`	Prompt generieren lassen
`GET` `PUT`	`/agents/{id}/caller_lookup`	Anruferkontext lesen und setzen
`GET` `PUT`	`/agents/{id}/post_processing`	Nachbereitung lesen und setzen
`GET` `POST`	`/agents/{id}/tools`	Fähigkeiten auflisten und anlegen
`PATCH` `DELETE`	`/agents/{id}/tools/{toolId}`	Einzelne Fähigkeit ändern oder entfernen
`GET` `POST`	`/agents/{id}/knowledge`	Wissensdokumente des Agenten
`DELETE`	`/agents/{id}/knowledge/{docId}`	Dokument vom Agenten lösen
`GET` `POST`	`/agents/{id}/dictionary`	Aussprache-Wörterbuch
`PATCH` `DELETE`	`/agents/{id}/dictionary/{termId}`	Einzelnen Eintrag ändern oder löschen
`GET` `POST`	`/agents/{id}/keyterms`	STT-Schlüsselbegriffe
`PATCH` `DELETE`	`/agents/{id}/keyterms/{termId}`	Einzelnen Begriff ändern oder löschen
`POST`	`/agents/{id}/dial_out`	Einen einzelnen ausgehenden Anruf auslösen

Anrufe

Methode	Pfad	Zweck
`GET`	`/calls`	Anrufe auflisten und filtern
`GET`	`/calls/{id}`	Einzelnen Anruf mit erfassten Variablen
`GET`	`/calls/{id}/transcript`	Vollständiges Transkript
`GET`	`/calls/{id}/recording`	Aufzeichnung, sofern vorhanden

Kampagnen

Methode	Pfad	Zweck
`GET` `POST`	`/campaigns`	Kampagnen auflisten und anlegen
`GET` `PATCH` `DELETE`	`/campaigns/{id}`	Einzelne Kampagne lesen, ändern, löschen
`GET` `POST`	`/campaigns/{id}/leads`	Kontakte auflisten und einzeln hinzufügen
`POST`	`/campaigns/{id}/leads/csv`	Kontaktliste als CSV hochladen
`POST`	`/campaigns/{id}/start`	Kampagne starten
`POST`	`/campaigns/{id}/pause`	Pausieren
`POST`	`/campaigns/{id}/resume`	Fortsetzen
`POST`	`/campaigns/{id}/stop`	Endgültig beenden

Telefonnummern

Methode	Pfad	Zweck
`GET`	`/phone_numbers`	Eigene Rufnummern auflisten
`POST`	`/phone_numbers/search`	Verfügbare Nummern suchen
`POST`	`/phone_numbers/purchase`	Nummer kaufen
`POST`	`/phone_numbers/import_byo`	Eigene SIP-Nummer importieren
`GET` `PATCH` `DELETE`	`/phone_numbers/{id}`	Einzelne Nummer lesen, zuweisen, freigeben

Wissensdatenbank

Methode	Pfad	Zweck
`GET` `POST`	`/knowledge_documents`	Dokumente auflisten und hochladen
`GET` `DELETE`	`/knowledge_documents/{id}`	Einzelnes Dokument lesen oder löschen

Berechtigungen beachten

Jeder Endpunkt verlangt die passende Berechtigung auf dem Schlüssel. Fehlt sie, kommt 403 zurück — nicht 401. Die Zuordnung ist geradlinig: Lesende Aufrufe brauchen …:read, schreibende …:write.

Drei Endpunkte kosten Geld oder lösen echte Anrufe aus und haben deshalb eigene Berechtigungen:

Endpunkt	Berechtigung
`POST /phone_numbers/purchase`	`phone_numbers:purchase`
`POST /campaigns/{id}/start`	`campaigns:execute`
`POST /agents/{id}/dial_out`	`dial_out:execute`

Mehr dazu unter API-Schlüssel verwalten.

Fehler

Fehler kommen als JSON mit einem sprechenden Code:

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is missing required fields"
  }
}

Code	Bedeutung
`invalid_request`	Die Anfrage ist unvollständig oder falsch aufgebaut
`unauthorized`	Schlüssel fehlt oder ist ungültig
`forbidden`	Schlüssel gültig, aber ohne die nötige Berechtigung
`not_found`	Die Ressource gibt es nicht
`rate_limited`	Zu viele Anfragen
`internal_error`	Fehler auf unserer Seite

Bei 429 liefert die Antwort einen Retry-After-Header mit, wie lange du warten sollst.

Idempotenz bei schreibenden Aufrufen

Alle schreibenden Endpunkte nehmen einen Idempotency-Key-Header entgegen. Setz ihn überall dort, wo ein doppelter Aufruf wehtut — beim Nummernkauf, beim Auslösen eines Anrufs, beim Hochladen einer Kontaktliste. Läuft die Anfrage in ein Timeout und du wiederholst sie mit demselben Schlüssel, wird sie nicht ein zweites Mal ausgeführt.

Inhaltsverzeichnis