API-Verhalten und Konfigurationsregeln

Alle Pfade dieser Referenz sind relativ zu /api/external/v1. Jeder Aufruf benötigt einen passenden Bearer-Zugang mit Scopes. Die Rechte des Benutzers und der gebundene Workspace werden zusätzlich geprüft.

Endpunkte und Scopes

Methoden	Pfad	Scopes in Methodenreihenfolge
GET	/connection	connection:verify
GET / POST	/agents	agents:read / agents:write
GET / PUT	/agents/{id}	agents:configuration:read / agents:write
GET	/agents/{id}/configuration	agents:configuration:read
GET	/agent-catalog	agents:configuration:read
GET	/agent-catalog/voices	agents:configuration:read
GET / POST	/flows	flows:read / flows:write
GET / PUT / DELETE	/flows/{id}	flows:read / flows:write / flows:write
GET	/flow-catalog	flows:read
GET / POST	/agents/{agentId}/tools	tools:read / tools:write
GET / PUT / DELETE	/agents/{agentId}/tools/{id}	tools:read / tools:write / tools:write
GET	/tool-catalog	tools:read
GET	/tool-catalog/credentials	tools:read
GET	/tool-catalog/oauth-configurations	tools:read
GET	/tool-catalog/mcp-tools	tools:read
GET / POST	/knowledge-bases	knowledge-bases:read / knowledge-bases:write
GET / PUT / DELETE	/knowledge-bases/{id}	knowledge-bases:read / knowledge-bases:write / knowledge-bases:write
GET	/knowledge-bases/{id}/deletion-checklist	knowledge-bases:write
GET / POST	/knowledge-bases/{id}/documents	documents:read / documents:write
GET / DELETE	/knowledge-bases/{id}/documents/{documentId}	documents:read / documents:write
GET / POST	/pre-processing/profiles	pre-processing:read / pre-processing:write
GET / PUT / DELETE	/pre-processing/profiles/{id}	pre-processing:read / pre-processing:write / pre-processing:write
GET	/pre-processing/variables	pre-processing:read
GET / POST	/post-processing/profiles	post-processing:read / post-processing:write
GET / PUT / DELETE	/post-processing/profiles/{id}	post-processing:read / post-processing:write / post-processing:write
GET	/post-processing/variables	post-processing:read
GET	/phone-numbers	phone-numbers:read
GET	/phone-numbers/{id}	phone-numbers:read
PUT / DELETE	/phone-numbers/{id}/assignment	phone-numbers:write / phone-numbers:write
GET	/call-summaries	call-summaries:read

Listen und Statuscodes

Listen liefern items, page, size, totalElements und totalPages. page beginnt bei 0 und reicht bis 100000. size ist standardmäßig 25, erlaubt sind 1–100. Werte außerhalb der Grenzen ergeben 400. Kleine Auswahlkataloge und einzelne Detailressourcen sind nicht paginiert.

Agents, Flows, Rufnummern, Knowledge Bases, Dokumente und Profile sind nach ID sortiert. Stimmen sind nach Name und ID sortiert. Zusammenfassungen sind nach Anrufbeginn absteigend und danach ID absteigend sortiert. Rufe alle Seiten ab, wenn du eine vollständige Auswertung brauchst; Listen sind kein eingefrorener Snapshot.

Erstellen liefert 201 mit Location, Lesen und Ändern 200, erfolgreiches Löschen 204. JSON-Eingaben verwenden Content-Type: application/json; Datei-Uploads verwenden Multipart. Erfolgreiche Datenantworten tragen Cache-Control: no-store.

Agents und Auswahlkataloge

POST /agents und PUT /agents/{id} erwarten { "agent": { ... }, "options": { ... } }. Die Antwort enthält id, revision, agent und options. Core und Options werden gemeinsam gespeichert; scheitert ein Bereich, wird die gesamte Änderung verworfen. Fehlendes oder null gesetztes agent.enabled bedeutet false.

Bereich	Zentrale Felder
agent	agentType: "VOICE", title, agentName, sttLanguages, voiceId, drei Begrüßungstexte, initialSilenceTimeoutMs, segmentationSilenceTimeoutMs
Weitere Agent-Einstellungen	description, persona, timezone, phraseList, voiceConfiguration, sttProvider, anbieterspezifische STT-Werte
options	model, systemPrompt, conversationHistoryLimit, knowledgeBaseId, RAG-, Temperatur-, Output- und Query-Transformer-Einstellungen

GET /agent-catalog liefert erlaubte Modelle mit Reasoning-Auswahl, Temperaturvorgabe und Outputlimit, Sprachen, Provider, TTS-Modi und Prompt-Variablen. Verwende daraus auswählbare Werte. Nicht jede angebotene Konfigurationsfamilie bedeutet, dass ein Dienst bereits für deinen Workspace eingerichtet ist.

GET /agent-catalog/voices unterstützt die optionalen Filter provider (AZURE, KUGEL), language, gender (FEMALE, MALE, NEUTRAL) und search sowie Pagination. language=de trifft regionale Varianten; language=de-DE nur ausdrücklich so ausgewiesene Stimmen. Unbekannte, leere oder doppelte Filter werden abgewiesen.

Stimmen liefern id, provider, name, description, languages, gender, styles und capabilities. Übernimm id unverändert als agent.voiceId; erfinde keine IDs. Eine unbekannte Fähigkeit wird als null geliefert. Bei Katalogstörungen kann 503 mit VOICE_CATALOG_UNAVAILABLE auftreten.

Zum Ändern zuerst GET /agents/{id} lesen. Bearbeite die vollständigen Bereiche agent und options und sende deren aktuellen ETag. voiceConfiguration: null entfernt Stimmparameter. Der ältere reine Lesepfad /agents/{id}/configuration ist für einen Bearbeitungsablauf ungeeignet. Ein vollständiges Erstellungsbeispiel zeigt die Pflichtangaben und sichere Ausgangswerte.

Agentic Flows

POST und PUT eines Flows erwarten das Konfigurationsobjekt selbst. Die Antwort enthält id, revision, configuration. Zentrale Eingabefelder sind title, description, persona, routingPrompt, model, conversationHistoryLimit, temperature, maxTokens, intentAgentMapping, routingMode und gegebenenfalls decisionRouting.

intentAgentMapping braucht DEFAULT mit einer vorhandenen Agent-ID dieses Workspaces. Weitere Intents ordnen Fachagenten zu. Der Flow-Katalog liefert verfügbare Modelle, Modi und Routing-Variablen. Decision Routing setzt die Verfügbarkeit dieser Funktion sowie Regeln und Beschreibungen für alle aktiven Intents voraus.

PUT und DELETE benötigen den aktuellen ETag. Löschungen können an Abhängigkeiten scheitern; zugeordnete Agents werden durch das Löschen eines Flows nicht gelöscht. Flow-Rufnummernzuweisungen und Zeitregeln bearbeitest du in der Oberfläche.

Agent-Tools

POST und PUT verwenden toolType und configuration, beispielsweise den Typ API_REQUEST_TOOL. Lies zuerst /tool-catalog: Er liefert unterstützte Tooltypen, passende Agenttypen und Konfigurationsfelder. Die Antwort enthält zusätzlich id und revision. Typ und besitzender Agent sind nach der Erstellung unveränderlich.

Die Credential- und OAuth-Kataloge liefern sichere Referenzen mit IDs und Namen, keine Secrets. Zusätzlich zum Tool-Scope sind aktuelle Leserechte für Zugangsdaten nötig. /tool-catalog/mcp-tools liefert nur bereits freigegebene verfügbare externe Tools einschließlich inputSchema. Eine Zuweisung nutzt deren mcpToolId; die API richtet keine externen MCP-Verbindungen ein und gibt keine Tools frei.

Knowledge Bases und Dokumente

Knowledge Bases verwenden für POST/PUT { "title": "Servicewissen" }. Antworten enthalten id, title, version. Zum Löschen zuerst die deletion-checklist lesen: Sie liefert canDelete, blockingReferences, assessmentToken und den für DELETE benötigten ETag. Verwende diesen Checklist-ETag, nicht den normalen Versions-ETag. Löse blockierende Agent-Zuordnungen zuerst.

Dokument-Upload erwartet Multipart-Felder title und file. Die Verarbeitung muss erfolgreich abgeschlossen sein, bevor die API Erfolg meldet. Dokumentantworten enthalten id, title, documentType, version; sie liefern keine Quelldateiinhalte. Dokument-DELETE benötigt den ETag des Metadaten-GETs. Unterstützte Formate und Inhaltsprüfung entsprechen dem Datei-Upload.

Pre- und Post-Processing-Profile

POST/PUT erwarten profile und configuration. profile enthält name, defaultProfile, scope und assignments; in Antworten zusätzlich id und version.

Profil-Scope	Bedeutung
UNASSIGNED	Keine explizite Zuordnung
ALL	Workspaceweite Geltung gemäß den bestehenden Profilregeln
SELECTED	assignments mit ownerType (AGENT oder FLOW) und ownerId

Zum Übernehmen bestehender Zuordnungen aus anderen Profilen ist transferFromProfileIds ausdrücklich nötig. Die Profilregeln gelten weiterhin. PUT ersetzt die vollständige Konfiguration; bearbeite die GET-Antwort, um versehentliche Rücksetzungen zu vermeiden. PUT/DELETE benötigen den aktuellen ETag.

Pre Processing unterstützt Lookup-URL, Header, Query-Parameter, Timeout, Antwortverarbeitung und Begrüßungs-Template. Post Processing unterstützt eigenen Summary-Prompt, Kontext, E-Mail, Webhook und Ausführungsbedingungen. Lookup- und Webhook-Timeouts liegen bei 1–60000 ms. Variablenkataloge liefern Namen und Beschreibungen, keine Laufzeitwerte. Ein leerer eigener Prompt bleibt leer; geerbte Plattform-Standardprompts werden nicht ausgegeben.

Header und gespeicherte Secrets

Tool- und Processing-Antworten zeigen bei gespeicherten Headern name und configured. value ist ausschließlich ein Schreibfeld. Bei gleichem Ziel hält ein Header ohne value den vorhandenen Wert; Weglassen aus der vollständigen Liste entfernt den Header. Sende keine Maskierungszeichen wie **** als Secret-Ersatz.

API-Tools können alternativ vorhandene credentialId-Referenzen mit prefix oder eine oauthConfigId nutzen. Processing zeigt bestehendes OAuth über oauthConfigured; clearAuthentication: true entfernt dort die OAuth-Verknüpfung. Bei Änderung der Ziel-URL musst du verborgene Authentifizierung ausdrücklich entfernen oder neue Werte/Referenzen setzen. Vorhandene Secrets dürfen nicht unbemerkt an ein neues Ziel gelangen.

Rufnummernzuweisungen

Rufnummernantworten enthalten id, number, country, routingTimezone, maxAiCallDurationSeconds, defaultRoute und revision. defaultRoute ist leer oder enthält type (AGENT oder AGENTIC_FLOW) und id.

Für eine Zuweisung sende PUT /phone-numbers/{id}/assignment mit { "agentId": "AGENT_ID" } und aktuellem ETag. DELETE mit ETag entfernt nur die Standardzuweisung; die Nummer bleibt beim Workspace.

Aktive Zeitregeln (ACTIVE_ROUTING_OVERRIDES), eine Flow-Standardroute (DEFAULT_ROUTE_IS_FLOW) oder ein Agent mit anderer Nummer (AGENT_ALREADY_ASSIGNED) können mit 409 blockieren. Diese API kauft oder kündigt keine Nummern und ändert keine Zeitpläne.

Zusammenfassungen im Zeitraum

GET /call-summaries benötigt from und to als ISO-8601-Zeitstempel mit Z oder explizitem UTC-Offset. Auswahl: Anrufbeginn ab from einschließlich bis to ausschließlich. Fehlende, gleiche, vertauschte oder zeitzonenlose Grenzen ergeben 400.

Ein Eintrag enthält callRecordId, summary, fromNumber, toNumber, startTime, endTime, durationSeconds, direction, purpose, isForwarded, isConferenceCall, excludedFromBilling und piiRedacted. Ende und Dauer können bei noch nicht beendeten Anrufen leer sein. Rufnummern sind gespeicherte Anrufwerte, keine aufgelösten Kontaktnamen.

Zurückgegeben werden gespeicherte nicht leere Zusammenfassungen und ausdrücklich geschwärzte Anrufeinträge. Bei geschwärzten Einträgen sind Rufnummern und Zusammenfassung null. Gelöschte Datensätze sind ausgeschlossen. Der Aufruf erzeugt keine fehlenden Zusammenfassungen und liefert keine Transkripte. Eine leere Antwort beweist daher nicht, dass es keine Anrufe gab. Das Tagesbeispiel berücksichtigt die lokale Zeitzone und Pagination.

Konflikte, Fehler und Limits

Status	Bedeutung und Reaktion
400	Eingabe, Format, Katalogwert oder Zeitraum prüfen.
401	Zugang fehlt, ist abgelaufen oder ungültig; erneuern oder erneut verbinden.
403	Scope oder aktuelle Benutzerrechte fehlen.
404	Ressource im gebundenen Workspace nicht verfügbar.
409	ETag fehlt/ist veraltet, Abhängigkeit oder Routing-Konflikt; neu lesen und abgleichen.
429	EXTERNAL_API_RATE_LIMITED; Retry-After in Sekunden abwarten.
503	Dienst vorübergehend nicht verfügbar; Ergebnis unklarer Schreibvorgänge zuerst prüfen.

Bei vorhandenen Ressourcen ist für die beschriebenen PUT-/DELETE-Operationen If-Match nötig. Übernimm den ETag einschließlich Anführungszeichen. Authentifizierungsfehler können ohne JSON-Body kommen; verlasse dich zuerst auf den HTTP-Status.

Das Ausgangsbudget beträgt 120 Anfragen pro Minute und Workspace, davon höchstens 30 schreibende. REST, MCP und alle Zugänge dieses Workspaces teilen es; tatsächliche Limits können abweichen. Auch authentifizierte fehlgeschlagene Anfragen zählen. Nutze Retry-After; wiederhole einen unklaren POST nicht automatisch.

Dieser Vertrag umfasst die aufgeführten externen Routen. Credential-Verwaltung, Dokumentdownloads, Website-Import/Synchronisierung, Tool-Ausführung, Debugging, Anrufstarts und Kampagnen steuerst du nicht über diese Konfigurations-API.