API behavior and configuration rules

All paths in this reference are relative to /api/external/v1. Each call needs a suitable Bearer credential with scopes. Current user permissions and the bound workspace are checked as well.

Endpoints and scopes

Methods	Path	Scopes in method order
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

Lists and status codes

Lists return items, page, size, totalElements and totalPages. page starts at 0 and allows up to 100000. size defaults to 25 and allows 1–100. Out-of-range values return 400. Small selection catalogs and individual detail resources are not paginated.

Agents, Flows, phone numbers, knowledge bases, documents and profiles are ordered by ID. Voices are ordered by name and ID. Summaries are ordered by call start descending, then ID descending. Fetch all pages for a complete analysis; lists are not frozen snapshots.

Creation returns 201 with Location, reads and updates 200, successful deletion 204. JSON requests use Content-Type: application/json; file uploads use multipart. Successful data responses use Cache-Control: no-store.

Agents and selection catalogs

POST /agents and PUT /agents/{id} expect { "agent": { ... }, "options": { ... } }. Responses contain id, revision, agent and options. Core and options save together; failure in either rolls back the entire change. Omitted or null agent.enabled means false.

Area	Main fields
agent	agentType: "VOICE", title, agentName, sttLanguages, voiceId, three greeting texts, initialSilenceTimeoutMs, segmentationSilenceTimeoutMs
Additional Agent settings	description, persona, timezone, phraseList, voiceConfiguration, sttProvider, provider-specific STT settings
options	model, systemPrompt, conversationHistoryLimit, knowledgeBaseId, RAG, temperature, output and query-transformer settings

GET /agent-catalog returns permitted models with reasoning choices, temperature rules and output limits, languages, providers, TTS modes and prompt variables. Use selectable values from this catalog. An offered configuration family does not guarantee that a service is already configured for your workspace.

GET /agent-catalog/voices supports optional provider (AZURE, KUGEL), language, gender (FEMALE, MALE, NEUTRAL) and search filters plus pagination. language=de matches regional variants; language=de-DE matches only voices explicitly listed that way. Unknown, empty or duplicate filters are rejected.

Voices return id, provider, name, description, languages, gender, styles and capabilities. Copy id unchanged into agent.voiceId; do not invent IDs. Unknown capabilities are null. Catalog failures can return 503 with VOICE_CATALOG_UNAVAILABLE.

Before updating, read GET /agents/{id}. Edit the complete agent and options objects and send their current ETag. voiceConfiguration: null removes voice parameters. The older read-only /agents/{id}/configuration path is unsuitable for an editing workflow. A complete creation example shows required fields and safe starting values.

Agentic Flows

Flow POST and PUT expect the configuration object itself. Responses contain id, revision, configuration. Main input fields are title, description, persona, routingPrompt, model, conversationHistoryLimit, temperature, maxTokens, intentAgentMapping, routingMode and, where needed, decisionRouting.

intentAgentMapping requires DEFAULT with an existing Agent ID in this workspace. Additional intents map specialist Agents. The Flow catalog provides available models, modes and routing variables. Decision routing requires the feature to be available, plus rules and descriptions for all active intents.

PUT and DELETE need the current ETag. Dependencies may block deletion; deleting a Flow does not delete its assigned Agents. Manage Flow phone-number assignments and schedules in the interface.

Agent tools

POST and PUT use toolType and configuration, for example type API_REQUEST_TOOL. Read /tool-catalog first: it provides supported tool types, compatible Agent types and configuration fields. Responses additionally include id and revision. Type and owning Agent cannot change after creation.

Credential and OAuth catalogs return safe references with IDs and names, never secrets. Current credential-read permission is required in addition to the tool scope. /tool-catalog/mcp-tools returns only already-approved available external tools including inputSchema. Assignment uses their mcpToolId; the API does not configure external MCP connections or approve tools.

Knowledge bases and documents

Knowledge-base POST/PUT use { "title": "Service knowledge" }. Responses contain id, title, version. Before deletion, read deletion-checklist: it returns canDelete, blockingReferences, assessmentToken and the ETag needed for DELETE. Use this checklist ETag, rather than the normal version ETag. Remove blocking Agent assignments first.

Document upload expects multipart fields title and file. Processing must finish successfully before the API reports success. Document responses contain id, title, documentType, version; they do not return source file contents. Document DELETE needs the metadata GET's ETag. Supported formats and content validation follow the file upload workflow.

Pre- and post-processing profiles

POST/PUT expect profile and configuration. profile contains name, defaultProfile, scope and assignments; responses also include id and version.

Profile scope	Meaning
UNASSIGNED	No explicit assignment
ALL	Workspace-wide applicability under existing profile rules
SELECTED	assignments with ownerType (AGENT or FLOW) and ownerId

Transferring assignments from other profiles requires explicit transferFromProfileIds. Existing profile rules still apply. PUT replaces full configuration; edit the GET response to avoid unintended resets. PUT/DELETE need the current ETag.

Pre Processing supports lookup URL, headers, query parameters, timeout, response processing and greeting template. Post Processing supports a custom summary prompt, context, email, webhook and execution conditions. Lookup and webhook timeouts allow 1–60000 ms. Variable catalogs provide names and descriptions, not runtime values. An empty custom prompt stays empty; inherited platform default prompts are not returned.

Headers and stored secrets

Tool and processing responses show name and configured for stored headers. value is write-only. At the same target, a header without value preserves the existing value; omitting it from the full list removes the header. Never send masks such as **** as replacement secrets.

API tools can alternatively reference existing credentialId values with prefix, or an oauthConfigId. Processing indicates existing OAuth through oauthConfigured; clearAuthentication: true removes that OAuth link. Changing a target URL requires explicitly removing hidden authentication or supplying new values/references. Existing secrets cannot silently travel to a new target.

Phone-number assignments

Phone-number responses contain id, number, country, routingTimezone, maxAiCallDurationSeconds, defaultRoute and revision. defaultRoute is empty or contains type (AGENT or AGENTIC_FLOW) and id.

Assign a number using PUT /phone-numbers/{id}/assignment with { "agentId": "AGENT_ID" } and its current ETag. DELETE with an ETag removes only the default assignment; the number stays in the workspace.

Active schedules (ACTIVE_ROUTING_OVERRIDES), a Flow default route (DEFAULT_ROUTE_IS_FLOW) or an Agent with another number (AGENT_ALREADY_ASSIGNED) can block with 409. This API does not purchase or release numbers or edit schedules.

Summaries within a time range

GET /call-summaries requires from and to as ISO-8601 timestamps with Z or an explicit UTC offset. Selection is based on call start: from inclusive to to exclusive. Missing, equal, reversed or timezone-less bounds return 400.

Each entry contains callRecordId, summary, fromNumber, toNumber, startTime, endTime, durationSeconds, direction, purpose, isForwarded, isConferenceCall, excludedFromBilling and piiRedacted. End and duration can be null for calls that have not ended. Numbers are stored call values, not resolved contact names.

Results include stored nonblank summaries and explicitly redacted call records. Redacted records have null phone numbers and summary. Deleted records are excluded. The request does not generate missing summaries or return transcripts. An empty response therefore does not prove there were no calls. The daily example accounts for local timezone and pagination.

Conflicts, errors and limits

Status	Meaning and action
400	Check input, format, catalog value or time range.
401	Credential missing, expired or invalid; renew or reconnect.
403	Missing scope or current user permission.
404	Resource unavailable in the bound workspace.
409	Missing/stale ETag, dependency or routing conflict; read again and reconcile.
429	EXTERNAL_API_RATE_LIMITED; wait for Retry-After seconds.
503	Service temporarily unavailable; check uncertain write results first.

For existing resources, the described PUT/DELETE operations require If-Match. Copy the ETag including quotes. Authentication failures may have no JSON body; rely on HTTP status first.

The starting budget is 120 requests per minute per workspace, including at most 30 writes. REST, MCP and all workspace credentials share it; actual limits may differ. Authenticated failed requests count too. Honor Retry-After; do not automatically repeat an uncertain POST.

This contract covers the listed external routes. Credential administration, document downloads, website import/sync, tool execution, debugging, call starts and campaigns are not controlled through this configuration API.