Skip to content

Agents

Use an API key or REST OAuth access token. Scopes and your current workspace permissions apply together. All examples are illustrative.

Create Agent

POST /api/external/v1/agents

Scope: agents:write

Saves configuration directly; no call, tool test or message delivery is executed.

Request body · application/json

Field Type Required Description
agent object Yes Conversation, speech recognition and voice settings.
options object Yes Model, prompt and knowledge-search settings.
agent — fields
Field Type Required Description
enabled boolean No Enable the Agent. Omission or null means false.
agentType string Yes VOICE handles voice calls; AGENTIC is a specialist in an Agentic Flow.
Values: AGENTIC, VOICE
title string Yes Display name of the resource.
Rules: up to 255 characters
Example: "Demo"
description string No Description of this resource's purpose.
Rules: up to 10000 characters; null allowed
agentName string Yes Name the Agent uses when speaking to callers.
Rules: up to 255 characters
Example: "Demo Assistant"
persona string No Personality and speaking style for the Agent.
Rules: up to 10000 characters; null allowed
sttLanguages List of string Yes Languages Azure should recognize. Values stay stored when another speech provider is selected.
Rules: at least 1 entry; no duplicates
Example: ["de-DE"]
Show all 85 allowed values

de-DE, de-AT, de-CH, en-US, en-GB, en-AU, en-CA, en-IE, en-IN, es-ES, es-MX, fr-FR, fr-CA, nl-NL, nl-BE, pt-BR, pt-PT, ja-JP, zh-CN, zh-HK, it-IT, pl-PL, cs-CZ, da-DK, sv-SE, fi-FI, el-GR, ru-RU, tr-TR, ar-EG, af-ZA, am-ET, hy-AM, az-AZ, bn-IN, bs-BA, bg-BG, ca-ES, hr-HR, et-EE, fa-IR, fil-PH, ka-GE, gl-ES, gu-IN, he-IL, hi-IN, hu-HU, is-IS, id-ID, jv-ID, kn-IN, kk-KZ, km-KH, ko-KR, lo-LA, lt-LT, lv-LV, mk-MK, ms-MY, mt-MT, mn-MN, nb-NO, ne-NP, pa-IN, ps-AF, sw-KE, ta-IN, te-IN, th-TH, uk-UA, ur-PK, uz-UZ, vi-VN, sr-RS, sq-AL, so-SO, sl-SI, sk-SK, si-LK, ro-RO, my-MM, ml-IN, ga-IE, cy-GB
voiceId string Yes Exact ID from the voice catalog, including its provider prefix.
Rules: up to 255 characters
voiceConfiguration object No Parameters supported by the selected voice. Null removes these parameters on Agent updates.
greetingMorningText string Yes Morning greeting, using the Agent's timezone.
Rules: up to 4000 characters
greetingAfternoonText string Yes Afternoon greeting, using the Agent's timezone.
Rules: up to 4000 characters
greetingEveningText string Yes Evening greeting, using the Agent's timezone.
Rules: up to 4000 characters
importantNote string No Additional instructions for the Agent.
Rules: up to 10000 characters; null allowed
initialSilenceTimeoutMs integer (int32) Yes How long Azure waits for the caller to start speaking, in milliseconds.
Rules: 0–60000
Example: 1500
segmentationSilenceTimeoutMs integer (int32) Yes Silence after which Azure separates recognized speech into segments, in milliseconds.
Rules: 100–5000
Example: 500
phraseList List of string No Words or phrases to help speech recognition, such as product names. Send separate list entries, not comma-separated text.
Rules: up to 500 entries; null allowed
Example: ["Nuvoca"]
Each entry: up to 500 characters
timezone string No IANA timezone used for time-dependent Agent behavior, such as Europe/Berlin.
Rules: up to 100 characters; null allowed
Example: "Europe/Berlin"
greetingNonInterruptible boolean No Prevent the caller from interrupting the greeting.
Rules: null allowed
greetingTimeoutSeconds integer (int32) No Greeting time limit, in seconds.
Rules: 5–300; null allowed
Example: 30
sttProvider string No Speech-recognition provider from the Agent catalog.
Rules: null allowed
Values: AZURE, DEEPGRAM, KUGEL
deepgramEotThreshold number No Confidence required for Deepgram to consider the caller's turn complete.
Rules: 0.5–0.9; null allowed
deepgramEotTimeoutMs integer (int32) No Deepgram timeout for detecting the end of a turn, in milliseconds.
Rules: 500–10000; null allowed
deepgramLanguageHints List of string No Language hints from the Agent catalog. They guide Deepgram without restricting its supported languages.
Rules: no duplicates; null allowed
Show all 10 allowed values

de, en, es, fr, hi, it, ja, nl, pt, ru
preferPreProcessingGreeting boolean No Use the greeting from pre-processing when one is available.
Rules: null allowed
kugelLanguages List of string No Ordered Kugel language codes from the Agent catalog. The first is the expected starting language. Defaults to German on creation; omission on update keeps the current list.
Rules: 1–9 entries; null allowed
kugelTurnDetectionLevel string No RESPONSIVE reacts quickly; CONSERVATIVE waits longer during pauses. Applies to new calls; omission on update keeps the current setting.
Rules: null allowed
Values: RESPONSIVE, CONSERVATIVE
voiceConfiguration — fields
Field Type Required Description
temperature number (double) No Voice sampling temperature. Lower values produce more consistent speech.
Rules: 0.3–1; null allowed
topP number (double) No Top-p sampling setting, if supported by the voice.
Rules: 0.3–1; null allowed
topK integer (int32) No Top-k sampling setting, if supported by the voice.
Rules: 1–50; null allowed
cfgScale number (double) No Guidance strength for voices that support this parameter.
Rules: 1–2; null allowed
telecomEffectEnabled boolean No Apply telephone-style audio for supported Azure HD voices. Null uses the platform default.
enhancePronunciationEnabled boolean No Enable pronunciation enhancement for supported Azure HD voices. Null uses the platform default.
xmlLang string No Language or accent code supported by the selected voice.
Rules: up to 10 characters; null allowed
Example: "de-AT"
style string No Speaking style supported by the selected voice.
Rules: up to 50 characters; null allowed
options — fields
Field Type Required Description
model string Yes Agent model from the Agent catalog. Check its reasoning, temperature and output limits.
Show all 19 allowed values

GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
reasoningEffort string No Reasoning effort supported by the selected model in the Agent catalog.
Values: NONE, MINIMAL, LOW
systemPrompt string Yes Complete Agent instructions, including behavior, knowledge boundaries and error handling.
Rules: up to 100000 characters
conversationHistoryLimit integer (int32) Yes Maximum number of conversation-history entries supplied to the model.
Rules: 1–100
Example: 20
knowledgeBaseId string (uuid) No ID of the assigned Knowledge Base. Null removes the assignment.
ragTopK integer (int32) Yes Maximum knowledge chunks retrieved per search.
Rules: 1–50
Example: 5
ragSimilarityThreshold number (double) No Minimum similarity a knowledge chunk must have to be included.
Rules: 0–1
Example: 0.5
temperature number (double) No Response variation. Respect any fixed temperature in the selected model's catalog entry.
Rules: 0–2
Example: 0.3
maxTokens integer (int32) Yes Maximum output-token budget. Also respect the selected model's limit in the catalog.
Rules: 10–25000
Example: 1000
ttsStreamingMode string No Speech-output mode selected from the Agent catalog.
Values: QUALITY_SSML, LOW_LATENCY_TEXT_STREAM
queryTransformEnabled boolean No Rewrite knowledge-search queries before retrieval. Omission or null means false.
queryTransformHistoryLimit integer (int32) Yes Maximum conversation-history entries used for query rewriting.
Rules: 1–100
Example: 5
queryTransformPrompt string No Query-rewrite prompt for LLM mode. DECISION mode uses decisionQueryTransform.
Rules: up to 20000 characters
queryTransformConfidenceThreshold number (double) No Confidence required for the query transformer.
Rules: 0–1
Example: 0.8
queryTransformMode string No Use an LLM rewrite or a separate search decision and rewrite.
Values: LLM, DECISION
decisionQueryTransform object No Search-decision and query-rewrite settings. Requires availability in the Agent catalog.
decisionQueryTransform — fields
Field Type Required Description
rewriteModel string No Model used for query rewriting. Select a catalog model with supportsQueryRewrite=true.
Show all 19 allowed values

GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
parallel boolean No Run the search decision and query rewrite at the same time.
decisionPrompt string No Instructions for deciding whether to search the Knowledge Base: SEARCH or SKIP.
rewritePrompt string No Instructions for rewriting the knowledge-search query. 
{
  "agent": {
    "enabled": false,
    "agentType": "VOICE",
    "title": "NuvoCar reception draft",
    "agentName": "NuvoCar Assistant",
    "sttProvider": "AZURE",
    "sttLanguages": [
      "en-US"
    ],
    "voiceId": "azure:FLORIAN_HD",
    "timezone": "Europe/Berlin",
    "greetingMorningText": "Good morning, this is NuvoCar's digital assistant. How can I help?",
    "greetingAfternoonText": "Hello, this is NuvoCar's digital assistant. How can I help?",
    "greetingEveningText": "Good evening, this is NuvoCar's digital assistant. How can I help?",
    "initialSilenceTimeoutMs": 1500,
    "segmentationSilenceTimeoutMs": 500,
    "phraseList": [
      "NuvoCar"
    ]
  },
  "options": {
    "model": "GPT_4_1_MINI",
    "systemPrompt": "You are NuvoCar's digital receptionist. Ask about the caller's request. Never invent prices or appointments. Explain when information is unavailable. Never claim storage or transfer without a successful configured action.",
    "conversationHistoryLimit": 20,
    "knowledgeBaseId": null,
    "ragTopK": 5,
    "ragSimilarityThreshold": 0.5,
    "temperature": 0.3,
    "maxTokens": 1000,
    "ttsStreamingMode": "QUALITY_SSML",
    "queryTransformEnabled": false,
    "queryTransformHistoryLimit": 5,
    "queryTransformConfidenceThreshold": 0.8,
    "queryTransformMode": "LLM"
  }
}

Response 201

Created.

Header Type Description
Cache-Control string The response must not be cached.
Example: no-store
Location string Path of the created resource.
ETag string Current revision. Send unchanged, including quotes, as If-Match when required.
Example: "revision-from-get"

application/json

Field Type Description
id string (uuid) Resource ID in your workspace.
revision string Current resource revision. Use the response ETag for If-Match when updating.
agent object Conversation, speech recognition and voice settings.
options object Model, prompt and knowledge-search settings.
agent — fields
Field Type Description
enabled boolean Enable the Agent. Omission or null means false.
agentType string VOICE handles voice calls; AGENTIC is a specialist in an Agentic Flow.
Values: AGENTIC, VOICE
title string Display name of the resource.
Rules: up to 255 characters
Example: "Demo"
description string Description of this resource's purpose.
Rules: up to 10000 characters; null allowed
agentName string Name the Agent uses when speaking to callers.
Rules: up to 255 characters
Example: "Demo Assistant"
persona string Personality and speaking style for the Agent.
Rules: up to 10000 characters; null allowed
sttLanguages List of string Languages Azure should recognize. Values stay stored when another speech provider is selected.
Rules: at least 1 entry; no duplicates
Example: ["de-DE"]
Show all 85 allowed values

de-DE, de-AT, de-CH, en-US, en-GB, en-AU, en-CA, en-IE, en-IN, es-ES, es-MX, fr-FR, fr-CA, nl-NL, nl-BE, pt-BR, pt-PT, ja-JP, zh-CN, zh-HK, it-IT, pl-PL, cs-CZ, da-DK, sv-SE, fi-FI, el-GR, ru-RU, tr-TR, ar-EG, af-ZA, am-ET, hy-AM, az-AZ, bn-IN, bs-BA, bg-BG, ca-ES, hr-HR, et-EE, fa-IR, fil-PH, ka-GE, gl-ES, gu-IN, he-IL, hi-IN, hu-HU, is-IS, id-ID, jv-ID, kn-IN, kk-KZ, km-KH, ko-KR, lo-LA, lt-LT, lv-LV, mk-MK, ms-MY, mt-MT, mn-MN, nb-NO, ne-NP, pa-IN, ps-AF, sw-KE, ta-IN, te-IN, th-TH, uk-UA, ur-PK, uz-UZ, vi-VN, sr-RS, sq-AL, so-SO, sl-SI, sk-SK, si-LK, ro-RO, my-MM, ml-IN, ga-IE, cy-GB
voiceId string Exact ID from the voice catalog, including its provider prefix.
Rules: up to 255 characters
voiceConfiguration object Parameters supported by the selected voice. Null removes these parameters on Agent updates.
greetingMorningText string Morning greeting, using the Agent's timezone.
Rules: up to 4000 characters
greetingAfternoonText string Afternoon greeting, using the Agent's timezone.
Rules: up to 4000 characters
greetingEveningText string Evening greeting, using the Agent's timezone.
Rules: up to 4000 characters
importantNote string Additional instructions for the Agent.
Rules: up to 10000 characters; null allowed
initialSilenceTimeoutMs integer (int32) How long Azure waits for the caller to start speaking, in milliseconds.
Rules: 0–60000
Example: 1500
segmentationSilenceTimeoutMs integer (int32) Silence after which Azure separates recognized speech into segments, in milliseconds.
Rules: 100–5000
Example: 500
phraseList List of string Words or phrases to help speech recognition, such as product names. Send separate list entries, not comma-separated text.
Rules: up to 500 entries; null allowed
Example: ["Nuvoca"]
Each entry: up to 500 characters
timezone string IANA timezone used for time-dependent Agent behavior, such as Europe/Berlin.
Rules: up to 100 characters; null allowed
Example: "Europe/Berlin"
greetingNonInterruptible boolean Prevent the caller from interrupting the greeting.
Rules: null allowed
greetingTimeoutSeconds integer (int32) Greeting time limit, in seconds.
Rules: 5–300; null allowed
Example: 30
sttProvider string Speech-recognition provider from the Agent catalog.
Rules: null allowed
Values: AZURE, DEEPGRAM, KUGEL
deepgramEotThreshold number Confidence required for Deepgram to consider the caller's turn complete.
Rules: 0.5–0.9; null allowed
deepgramEotTimeoutMs integer (int32) Deepgram timeout for detecting the end of a turn, in milliseconds.
Rules: 500–10000; null allowed
deepgramLanguageHints List of string Language hints from the Agent catalog. They guide Deepgram without restricting its supported languages.
Rules: no duplicates; null allowed
Show all 10 allowed values

de, en, es, fr, hi, it, ja, nl, pt, ru
preferPreProcessingGreeting boolean Use the greeting from pre-processing when one is available.
Rules: null allowed
kugelLanguages List of string Ordered Kugel language codes from the Agent catalog. The first is the expected starting language. Defaults to German on creation; omission on update keeps the current list.
Rules: 1–9 entries; null allowed
kugelTurnDetectionLevel string RESPONSIVE reacts quickly; CONSERVATIVE waits longer during pauses. Applies to new calls; omission on update keeps the current setting.
Rules: null allowed
Values: RESPONSIVE, CONSERVATIVE
voiceConfiguration — fields
Field Type Description
temperature number (double) Voice sampling temperature. Lower values produce more consistent speech.
Rules: 0.3–1; null allowed
topP number (double) Top-p sampling setting, if supported by the voice.
Rules: 0.3–1; null allowed
topK integer (int32) Top-k sampling setting, if supported by the voice.
Rules: 1–50; null allowed
cfgScale number (double) Guidance strength for voices that support this parameter.
Rules: 1–2; null allowed
telecomEffectEnabled boolean Apply telephone-style audio for supported Azure HD voices. Null uses the platform default.
enhancePronunciationEnabled boolean Enable pronunciation enhancement for supported Azure HD voices. Null uses the platform default.
xmlLang string Language or accent code supported by the selected voice.
Rules: up to 10 characters; null allowed
Example: "de-AT"
style string Speaking style supported by the selected voice.
Rules: up to 50 characters; null allowed
options — fields
Field Type Description
model string Agent model from the Agent catalog. Check its reasoning, temperature and output limits.
Show all 19 allowed values

GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
reasoningEffort string Reasoning effort supported by the selected model in the Agent catalog.
Values: NONE, MINIMAL, LOW
systemPrompt string Complete Agent instructions, including behavior, knowledge boundaries and error handling.
Rules: up to 100000 characters
conversationHistoryLimit integer (int32) Maximum number of conversation-history entries supplied to the model.
Rules: 1–100
Example: 20
knowledgeBaseId string (uuid) ID of the assigned Knowledge Base. Null removes the assignment.
ragTopK integer (int32) Maximum knowledge chunks retrieved per search.
Rules: 1–50
Example: 5
ragSimilarityThreshold number (double) Minimum similarity a knowledge chunk must have to be included.
Rules: 0–1
Example: 0.5
temperature number (double) Response variation. Respect any fixed temperature in the selected model's catalog entry.
Rules: 0–2
Example: 0.3
maxTokens integer (int32) Maximum output-token budget. Also respect the selected model's limit in the catalog.
Rules: 10–25000
Example: 1000
ttsStreamingMode string Speech-output mode selected from the Agent catalog.
Values: QUALITY_SSML, LOW_LATENCY_TEXT_STREAM
queryTransformEnabled boolean Rewrite knowledge-search queries before retrieval. Omission or null means false.
queryTransformHistoryLimit integer (int32) Maximum conversation-history entries used for query rewriting.
Rules: 1–100
Example: 5
queryTransformPrompt string Query-rewrite prompt for LLM mode. DECISION mode uses decisionQueryTransform.
Rules: up to 20000 characters
queryTransformConfidenceThreshold number (double) Confidence required for the query transformer.
Rules: 0–1
Example: 0.8
queryTransformMode string Use an LLM rewrite or a separate search decision and rewrite.
Values: LLM, DECISION
decisionQueryTransform object Search-decision and query-rewrite settings. Requires availability in the Agent catalog.
decisionQueryTransform — fields
Field Type Description
rewriteModel string Model used for query rewriting. Select a catalog model with supportsQueryRewrite=true.
Show all 19 allowed values

GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
parallel boolean Run the search decision and query rewrite at the same time.
decisionPrompt string Instructions for deciding whether to search the Knowledge Base: SEARCH or SKIP.
rewritePrompt string Instructions for rewriting the knowledge-search query. 
{
  "id": "00000000-0000-0000-0000-000000000001",
  "revision": "revision-from-get",
  "agent": {
    "enabled": false,
    "agentType": "VOICE",
    "title": "Demo",
    "description": "string",
    "agentName": "Demo Assistant",
    "persona": "string",
    "sttLanguages": [
      "de-DE"
    ],
    "voiceId": "azure:FLORIAN_HD",
    "voiceConfiguration": {
      "temperature": 0.3,
      "topP": 0.3,
      "topK": 1,
      "cfgScale": 1,
      "telecomEffectEnabled": false,
      "enhancePronunciationEnabled": false,
      "xmlLang": "de-AT",
      "style": "string"
    },
    "greetingMorningText": "string",
    "greetingAfternoonText": "string",
    "greetingEveningText": "string",
    "importantNote": "string",
    "initialSilenceTimeoutMs": 1500,
    "segmentationSilenceTimeoutMs": 500,
    "phraseList": [
      "Nuvoca"
    ],
    "timezone": "Europe/Berlin",
    "greetingNonInterruptible": false,
    "greetingTimeoutSeconds": 30,
    "sttProvider": "AZURE",
    "deepgramEotThreshold": 0.5,
    "deepgramEotTimeoutMs": 500,
    "deepgramLanguageHints": [],
    "preferPreProcessingGreeting": false,
    "kugelLanguages": [
      "string"
    ],
    "kugelTurnDetectionLevel": "RESPONSIVE"
  },
  "options": {
    "model": "GPT_4_1_MINI",
    "reasoningEffort": "NONE",
    "systemPrompt": "string",
    "conversationHistoryLimit": 20,
    "knowledgeBaseId": "00000000-0000-0000-0000-000000000001",
    "ragTopK": 5,
    "ragSimilarityThreshold": 0.5,
    "temperature": 0.3,
    "maxTokens": 1000,
    "ttsStreamingMode": "QUALITY_SSML",
    "queryTransformEnabled": false,
    "queryTransformHistoryLimit": 5,
    "queryTransformPrompt": "string",
    "queryTransformConfidenceThreshold": 0.8,
    "queryTransformMode": "LLM",
    "decisionQueryTransform": {
      "rewriteModel": "GPT_4_1_MINI",
      "parallel": false,
      "decisionPrompt": "string",
      "rewritePrompt": "string"
    }
  }
}
Error responses
Status Meaning
400 Invalid input, unsupported selection or time range.
401 Missing, expired or invalid credential. The body may be empty.
403 Required scope or current user permission missing. The body may be empty.
409 Missing/stale revision or dependency/routing conflict. Read again before retrying.
429 Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
503 Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field Type Description
status integer HTTP status code.
error string Description of the error.
details any Additional error details, when available.
Rules: null allowed
code string Machine-readable error code.
params object Additional values associated with the error code.
fieldErrors object Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

List Agents

GET /api/external/v1/agents

Scope: agents:read

Parameters

Name Location Type Required Description
page Query integer (int32) No Page index, starting at 0.
Rules: 0–100000
Default: 0
size Query integer (int32) No Results per page.
Rules: 1–100
Default: 25

Response 200

Success.

Header Type Description
Cache-Control string The response must not be cached.
Example: no-store

application/json

Field Type Description
items List of object Results on this page.
page integer (int32) Current page index, starting at 0.
size integer (int32) Number of results requested per page.
totalElements integer (int64) Total number of matching results.
totalPages integer (int32) Total number of result pages.
items — fields
Field Type Description
agentId string (uuid) ID of the Agent.
tenantId string (uuid) ID of the workspace bound to the credential.
enabled boolean Whether this resource is enabled.
agentType string VOICE handles voice calls; AGENTIC is a specialist in an Agentic Flow.
Values: AGENTIC, VOICE
title string Display name of the resource.
description string Description of this resource's purpose.
agentName string Name the Agent uses when speaking to callers. 
{
  "items": [
    {
      "agentId": "00000000-0000-0000-0000-000000000001",
      "tenantId": "00000000-0000-0000-0000-000000000001",
      "enabled": false,
      "agentType": "VOICE",
      "title": "NuvoCar service",
      "description": "string",
      "agentName": "string"
    }
  ],
  "page": 0,
  "size": 25,
  "totalElements": 1,
  "totalPages": 1
}
Error responses
Status Meaning
400 Invalid input, unsupported selection or time range.
401 Missing, expired or invalid credential. The body may be empty.
403 Required scope or current user permission missing. The body may be empty.
429 Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
503 Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field Type Description
status integer HTTP status code.
error string Description of the error.
details any Additional error details, when available.
Rules: null allowed
code string Machine-readable error code.
params object Additional values associated with the error code.
fieldErrors object Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Read Agent

GET /api/external/v1/agents/{id}

Scope: agents:configuration:read

Parameters

Name Location Type Required Description
id Path string (uuid) Yes Resource identifier in the bound workspace.

Response 200

Success.

Header Type Description
Cache-Control string The response must not be cached.
Example: no-store
ETag string Current revision. Send unchanged, including quotes, as If-Match when required.
Example: "revision-from-get"

application/json

Field Type Description
id string (uuid) Resource ID in your workspace.
revision string Current resource revision. Use the response ETag for If-Match when updating.
agent object Conversation, speech recognition and voice settings.
options object Model, prompt and knowledge-search settings.
agent — fields
Field Type Description
enabled boolean Enable the Agent. Omission or null means false.
agentType string VOICE handles voice calls; AGENTIC is a specialist in an Agentic Flow.
Values: AGENTIC, VOICE
title string Display name of the resource.
Rules: up to 255 characters
Example: "Demo"
description string Description of this resource's purpose.
Rules: up to 10000 characters; null allowed
agentName string Name the Agent uses when speaking to callers.
Rules: up to 255 characters
Example: "Demo Assistant"
persona string Personality and speaking style for the Agent.
Rules: up to 10000 characters; null allowed
sttLanguages List of string Languages Azure should recognize. Values stay stored when another speech provider is selected.
Rules: at least 1 entry; no duplicates
Example: ["de-DE"]
Show all 85 allowed values

de-DE, de-AT, de-CH, en-US, en-GB, en-AU, en-CA, en-IE, en-IN, es-ES, es-MX, fr-FR, fr-CA, nl-NL, nl-BE, pt-BR, pt-PT, ja-JP, zh-CN, zh-HK, it-IT, pl-PL, cs-CZ, da-DK, sv-SE, fi-FI, el-GR, ru-RU, tr-TR, ar-EG, af-ZA, am-ET, hy-AM, az-AZ, bn-IN, bs-BA, bg-BG, ca-ES, hr-HR, et-EE, fa-IR, fil-PH, ka-GE, gl-ES, gu-IN, he-IL, hi-IN, hu-HU, is-IS, id-ID, jv-ID, kn-IN, kk-KZ, km-KH, ko-KR, lo-LA, lt-LT, lv-LV, mk-MK, ms-MY, mt-MT, mn-MN, nb-NO, ne-NP, pa-IN, ps-AF, sw-KE, ta-IN, te-IN, th-TH, uk-UA, ur-PK, uz-UZ, vi-VN, sr-RS, sq-AL, so-SO, sl-SI, sk-SK, si-LK, ro-RO, my-MM, ml-IN, ga-IE, cy-GB
voiceId string Exact ID from the voice catalog, including its provider prefix.
Rules: up to 255 characters
voiceConfiguration object Parameters supported by the selected voice. Null removes these parameters on Agent updates.
greetingMorningText string Morning greeting, using the Agent's timezone.
Rules: up to 4000 characters
greetingAfternoonText string Afternoon greeting, using the Agent's timezone.
Rules: up to 4000 characters
greetingEveningText string Evening greeting, using the Agent's timezone.
Rules: up to 4000 characters
importantNote string Additional instructions for the Agent.
Rules: up to 10000 characters; null allowed
initialSilenceTimeoutMs integer (int32) How long Azure waits for the caller to start speaking, in milliseconds.
Rules: 0–60000
Example: 1500
segmentationSilenceTimeoutMs integer (int32) Silence after which Azure separates recognized speech into segments, in milliseconds.
Rules: 100–5000
Example: 500
phraseList List of string Words or phrases to help speech recognition, such as product names. Send separate list entries, not comma-separated text.
Rules: up to 500 entries; null allowed
Example: ["Nuvoca"]
Each entry: up to 500 characters
timezone string IANA timezone used for time-dependent Agent behavior, such as Europe/Berlin.
Rules: up to 100 characters; null allowed
Example: "Europe/Berlin"
greetingNonInterruptible boolean Prevent the caller from interrupting the greeting.
Rules: null allowed
greetingTimeoutSeconds integer (int32) Greeting time limit, in seconds.
Rules: 5–300; null allowed
Example: 30
sttProvider string Speech-recognition provider from the Agent catalog.
Rules: null allowed
Values: AZURE, DEEPGRAM, KUGEL
deepgramEotThreshold number Confidence required for Deepgram to consider the caller's turn complete.
Rules: 0.5–0.9; null allowed
deepgramEotTimeoutMs integer (int32) Deepgram timeout for detecting the end of a turn, in milliseconds.
Rules: 500–10000; null allowed
deepgramLanguageHints List of string Language hints from the Agent catalog. They guide Deepgram without restricting its supported languages.
Rules: no duplicates; null allowed
Show all 10 allowed values

de, en, es, fr, hi, it, ja, nl, pt, ru
preferPreProcessingGreeting boolean Use the greeting from pre-processing when one is available.
Rules: null allowed
kugelLanguages List of string Ordered Kugel language codes from the Agent catalog. The first is the expected starting language. Defaults to German on creation; omission on update keeps the current list.
Rules: 1–9 entries; null allowed
kugelTurnDetectionLevel string RESPONSIVE reacts quickly; CONSERVATIVE waits longer during pauses. Applies to new calls; omission on update keeps the current setting.
Rules: null allowed
Values: RESPONSIVE, CONSERVATIVE
voiceConfiguration — fields
Field Type Description
temperature number (double) Voice sampling temperature. Lower values produce more consistent speech.
Rules: 0.3–1; null allowed
topP number (double) Top-p sampling setting, if supported by the voice.
Rules: 0.3–1; null allowed
topK integer (int32) Top-k sampling setting, if supported by the voice.
Rules: 1–50; null allowed
cfgScale number (double) Guidance strength for voices that support this parameter.
Rules: 1–2; null allowed
telecomEffectEnabled boolean Apply telephone-style audio for supported Azure HD voices. Null uses the platform default.
enhancePronunciationEnabled boolean Enable pronunciation enhancement for supported Azure HD voices. Null uses the platform default.
xmlLang string Language or accent code supported by the selected voice.
Rules: up to 10 characters; null allowed
Example: "de-AT"
style string Speaking style supported by the selected voice.
Rules: up to 50 characters; null allowed
options — fields
Field Type Description
model string Agent model from the Agent catalog. Check its reasoning, temperature and output limits.
Show all 19 allowed values

GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
reasoningEffort string Reasoning effort supported by the selected model in the Agent catalog.
Values: NONE, MINIMAL, LOW
systemPrompt string Complete Agent instructions, including behavior, knowledge boundaries and error handling.
Rules: up to 100000 characters
conversationHistoryLimit integer (int32) Maximum number of conversation-history entries supplied to the model.
Rules: 1–100
Example: 20
knowledgeBaseId string (uuid) ID of the assigned Knowledge Base. Null removes the assignment.
ragTopK integer (int32) Maximum knowledge chunks retrieved per search.
Rules: 1–50
Example: 5
ragSimilarityThreshold number (double) Minimum similarity a knowledge chunk must have to be included.
Rules: 0–1
Example: 0.5
temperature number (double) Response variation. Respect any fixed temperature in the selected model's catalog entry.
Rules: 0–2
Example: 0.3
maxTokens integer (int32) Maximum output-token budget. Also respect the selected model's limit in the catalog.
Rules: 10–25000
Example: 1000
ttsStreamingMode string Speech-output mode selected from the Agent catalog.
Values: QUALITY_SSML, LOW_LATENCY_TEXT_STREAM
queryTransformEnabled boolean Rewrite knowledge-search queries before retrieval. Omission or null means false.
queryTransformHistoryLimit integer (int32) Maximum conversation-history entries used for query rewriting.
Rules: 1–100
Example: 5
queryTransformPrompt string Query-rewrite prompt for LLM mode. DECISION mode uses decisionQueryTransform.
Rules: up to 20000 characters
queryTransformConfidenceThreshold number (double) Confidence required for the query transformer.
Rules: 0–1
Example: 0.8
queryTransformMode string Use an LLM rewrite or a separate search decision and rewrite.
Values: LLM, DECISION
decisionQueryTransform object Search-decision and query-rewrite settings. Requires availability in the Agent catalog.
decisionQueryTransform — fields
Field Type Description
rewriteModel string Model used for query rewriting. Select a catalog model with supportsQueryRewrite=true.
Show all 19 allowed values

GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
parallel boolean Run the search decision and query rewrite at the same time.
decisionPrompt string Instructions for deciding whether to search the Knowledge Base: SEARCH or SKIP.
rewritePrompt string Instructions for rewriting the knowledge-search query. 
{
  "id": "00000000-0000-0000-0000-000000000001",
  "revision": "revision-from-get",
  "agent": {
    "enabled": false,
    "agentType": "VOICE",
    "title": "Demo",
    "description": "string",
    "agentName": "Demo Assistant",
    "persona": "string",
    "sttLanguages": [
      "de-DE"
    ],
    "voiceId": "azure:FLORIAN_HD",
    "voiceConfiguration": {
      "temperature": 0.3,
      "topP": 0.3,
      "topK": 1,
      "cfgScale": 1,
      "telecomEffectEnabled": false,
      "enhancePronunciationEnabled": false,
      "xmlLang": "de-AT",
      "style": "string"
    },
    "greetingMorningText": "string",
    "greetingAfternoonText": "string",
    "greetingEveningText": "string",
    "importantNote": "string",
    "initialSilenceTimeoutMs": 1500,
    "segmentationSilenceTimeoutMs": 500,
    "phraseList": [
      "Nuvoca"
    ],
    "timezone": "Europe/Berlin",
    "greetingNonInterruptible": false,
    "greetingTimeoutSeconds": 30,
    "sttProvider": "AZURE",
    "deepgramEotThreshold": 0.5,
    "deepgramEotTimeoutMs": 500,
    "deepgramLanguageHints": [],
    "preferPreProcessingGreeting": false,
    "kugelLanguages": [
      "string"
    ],
    "kugelTurnDetectionLevel": "RESPONSIVE"
  },
  "options": {
    "model": "GPT_4_1_MINI",
    "reasoningEffort": "NONE",
    "systemPrompt": "string",
    "conversationHistoryLimit": 20,
    "knowledgeBaseId": "00000000-0000-0000-0000-000000000001",
    "ragTopK": 5,
    "ragSimilarityThreshold": 0.5,
    "temperature": 0.3,
    "maxTokens": 1000,
    "ttsStreamingMode": "QUALITY_SSML",
    "queryTransformEnabled": false,
    "queryTransformHistoryLimit": 5,
    "queryTransformPrompt": "string",
    "queryTransformConfidenceThreshold": 0.8,
    "queryTransformMode": "LLM",
    "decisionQueryTransform": {
      "rewriteModel": "GPT_4_1_MINI",
      "parallel": false,
      "decisionPrompt": "string",
      "rewritePrompt": "string"
    }
  }
}
Error responses
Status Meaning
400 Invalid input, unsupported selection or time range.
401 Missing, expired or invalid credential. The body may be empty.
403 Required scope or current user permission missing. The body may be empty.
404 Resource is unavailable in the bound workspace.
429 Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
503 Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field Type Description
status integer HTTP status code.
error string Description of the error.
details any Additional error details, when available.
Rules: null allowed
code string Machine-readable error code.
params object Additional values associated with the error code.
fieldErrors object Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Update Agent

PUT /api/external/v1/agents/{id}

Scope: agents:write

Saves configuration directly; no call, tool test or message delivery is executed. Read the resource first. Send its current ETag, including quotes, in If-Match. Send the full editable configuration. Omitted settings can be reset.

Parameters

Name Location Type Required Description
id Path string (uuid) Yes Resource identifier in the bound workspace.
If-Match Header string Yes ETag from the preceding read, including quotes.
Example: "revision-from-get"

Request body · application/json

Field Type Required Description
agent object Yes Conversation, speech recognition and voice settings.
options object Yes Model, prompt and knowledge-search settings.
agent — fields
Field Type Required Description
enabled boolean No Enable the Agent. Omission or null means false.
agentType string Yes VOICE handles voice calls; AGENTIC is a specialist in an Agentic Flow.
Values: AGENTIC, VOICE
title string Yes Display name of the resource.
Rules: up to 255 characters
Example: "Demo"
description string No Description of this resource's purpose.
Rules: up to 10000 characters; null allowed
agentName string Yes Name the Agent uses when speaking to callers.
Rules: up to 255 characters
Example: "Demo Assistant"
persona string No Personality and speaking style for the Agent.
Rules: up to 10000 characters; null allowed
sttLanguages List of string Yes Languages Azure should recognize. Values stay stored when another speech provider is selected.
Rules: at least 1 entry; no duplicates
Example: ["de-DE"]
Show all 85 allowed values

de-DE, de-AT, de-CH, en-US, en-GB, en-AU, en-CA, en-IE, en-IN, es-ES, es-MX, fr-FR, fr-CA, nl-NL, nl-BE, pt-BR, pt-PT, ja-JP, zh-CN, zh-HK, it-IT, pl-PL, cs-CZ, da-DK, sv-SE, fi-FI, el-GR, ru-RU, tr-TR, ar-EG, af-ZA, am-ET, hy-AM, az-AZ, bn-IN, bs-BA, bg-BG, ca-ES, hr-HR, et-EE, fa-IR, fil-PH, ka-GE, gl-ES, gu-IN, he-IL, hi-IN, hu-HU, is-IS, id-ID, jv-ID, kn-IN, kk-KZ, km-KH, ko-KR, lo-LA, lt-LT, lv-LV, mk-MK, ms-MY, mt-MT, mn-MN, nb-NO, ne-NP, pa-IN, ps-AF, sw-KE, ta-IN, te-IN, th-TH, uk-UA, ur-PK, uz-UZ, vi-VN, sr-RS, sq-AL, so-SO, sl-SI, sk-SK, si-LK, ro-RO, my-MM, ml-IN, ga-IE, cy-GB
voiceId string Yes Exact ID from the voice catalog, including its provider prefix.
Rules: up to 255 characters
voiceConfiguration object No Parameters supported by the selected voice. Null removes these parameters on Agent updates.
greetingMorningText string Yes Morning greeting, using the Agent's timezone.
Rules: up to 4000 characters
greetingAfternoonText string Yes Afternoon greeting, using the Agent's timezone.
Rules: up to 4000 characters
greetingEveningText string Yes Evening greeting, using the Agent's timezone.
Rules: up to 4000 characters
importantNote string No Additional instructions for the Agent.
Rules: up to 10000 characters; null allowed
initialSilenceTimeoutMs integer (int32) Yes How long Azure waits for the caller to start speaking, in milliseconds.
Rules: 0–60000
Example: 1500
segmentationSilenceTimeoutMs integer (int32) Yes Silence after which Azure separates recognized speech into segments, in milliseconds.
Rules: 100–5000
Example: 500
phraseList List of string No Words or phrases to help speech recognition, such as product names. Send separate list entries, not comma-separated text.
Rules: up to 500 entries; null allowed
Example: ["Nuvoca"]
Each entry: up to 500 characters
timezone string No IANA timezone used for time-dependent Agent behavior, such as Europe/Berlin.
Rules: up to 100 characters; null allowed
Example: "Europe/Berlin"
greetingNonInterruptible boolean No Prevent the caller from interrupting the greeting.
Rules: null allowed
greetingTimeoutSeconds integer (int32) No Greeting time limit, in seconds.
Rules: 5–300; null allowed
Example: 30
sttProvider string No Speech-recognition provider from the Agent catalog.
Rules: null allowed
Values: AZURE, DEEPGRAM, KUGEL
deepgramEotThreshold number No Confidence required for Deepgram to consider the caller's turn complete.
Rules: 0.5–0.9; null allowed
deepgramEotTimeoutMs integer (int32) No Deepgram timeout for detecting the end of a turn, in milliseconds.
Rules: 500–10000; null allowed
deepgramLanguageHints List of string No Language hints from the Agent catalog. They guide Deepgram without restricting its supported languages.
Rules: no duplicates; null allowed
Show all 10 allowed values

de, en, es, fr, hi, it, ja, nl, pt, ru
preferPreProcessingGreeting boolean No Use the greeting from pre-processing when one is available.
Rules: null allowed
kugelLanguages List of string No Ordered Kugel language codes from the Agent catalog. The first is the expected starting language. Defaults to German on creation; omission on update keeps the current list.
Rules: 1–9 entries; null allowed
kugelTurnDetectionLevel string No RESPONSIVE reacts quickly; CONSERVATIVE waits longer during pauses. Applies to new calls; omission on update keeps the current setting.
Rules: null allowed
Values: RESPONSIVE, CONSERVATIVE
voiceConfiguration — fields
Field Type Required Description
temperature number (double) No Voice sampling temperature. Lower values produce more consistent speech.
Rules: 0.3–1; null allowed
topP number (double) No Top-p sampling setting, if supported by the voice.
Rules: 0.3–1; null allowed
topK integer (int32) No Top-k sampling setting, if supported by the voice.
Rules: 1–50; null allowed
cfgScale number (double) No Guidance strength for voices that support this parameter.
Rules: 1–2; null allowed
telecomEffectEnabled boolean No Apply telephone-style audio for supported Azure HD voices. Null uses the platform default.
enhancePronunciationEnabled boolean No Enable pronunciation enhancement for supported Azure HD voices. Null uses the platform default.
xmlLang string No Language or accent code supported by the selected voice.
Rules: up to 10 characters; null allowed
Example: "de-AT"
style string No Speaking style supported by the selected voice.
Rules: up to 50 characters; null allowed
options — fields
Field Type Required Description
model string Yes Agent model from the Agent catalog. Check its reasoning, temperature and output limits.
Show all 19 allowed values

GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
reasoningEffort string No Reasoning effort supported by the selected model in the Agent catalog.
Values: NONE, MINIMAL, LOW
systemPrompt string Yes Complete Agent instructions, including behavior, knowledge boundaries and error handling.
Rules: up to 100000 characters
conversationHistoryLimit integer (int32) Yes Maximum number of conversation-history entries supplied to the model.
Rules: 1–100
Example: 20
knowledgeBaseId string (uuid) No ID of the assigned Knowledge Base. Null removes the assignment.
ragTopK integer (int32) Yes Maximum knowledge chunks retrieved per search.
Rules: 1–50
Example: 5
ragSimilarityThreshold number (double) No Minimum similarity a knowledge chunk must have to be included.
Rules: 0–1
Example: 0.5
temperature number (double) No Response variation. Respect any fixed temperature in the selected model's catalog entry.
Rules: 0–2
Example: 0.3
maxTokens integer (int32) Yes Maximum output-token budget. Also respect the selected model's limit in the catalog.
Rules: 10–25000
Example: 1000
ttsStreamingMode string No Speech-output mode selected from the Agent catalog.
Values: QUALITY_SSML, LOW_LATENCY_TEXT_STREAM
queryTransformEnabled boolean No Rewrite knowledge-search queries before retrieval. Omission or null means false.
queryTransformHistoryLimit integer (int32) Yes Maximum conversation-history entries used for query rewriting.
Rules: 1–100
Example: 5
queryTransformPrompt string No Query-rewrite prompt for LLM mode. DECISION mode uses decisionQueryTransform.
Rules: up to 20000 characters
queryTransformConfidenceThreshold number (double) No Confidence required for the query transformer.
Rules: 0–1
Example: 0.8
queryTransformMode string No Use an LLM rewrite or a separate search decision and rewrite.
Values: LLM, DECISION
decisionQueryTransform object No Search-decision and query-rewrite settings. Requires availability in the Agent catalog.
decisionQueryTransform — fields
Field Type Required Description
rewriteModel string No Model used for query rewriting. Select a catalog model with supportsQueryRewrite=true.
Show all 19 allowed values

GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
parallel boolean No Run the search decision and query rewrite at the same time.
decisionPrompt string No Instructions for deciding whether to search the Knowledge Base: SEARCH or SKIP.
rewritePrompt string No Instructions for rewriting the knowledge-search query. 
{
  "agent": {
    "enabled": false,
    "agentType": "VOICE",
    "title": "NuvoCar reception draft",
    "agentName": "NuvoCar Assistant",
    "sttProvider": "AZURE",
    "sttLanguages": [
      "en-US"
    ],
    "voiceId": "azure:FLORIAN_HD",
    "timezone": "Europe/Berlin",
    "greetingMorningText": "Good morning, this is NuvoCar's digital assistant. How can I help?",
    "greetingAfternoonText": "Hello, this is NuvoCar's digital assistant. How can I help?",
    "greetingEveningText": "Good evening, this is NuvoCar's digital assistant. How can I help?",
    "initialSilenceTimeoutMs": 1500,
    "segmentationSilenceTimeoutMs": 500,
    "phraseList": [
      "NuvoCar"
    ]
  },
  "options": {
    "model": "GPT_4_1_MINI",
    "systemPrompt": "You are NuvoCar's digital receptionist. Ask about the caller's request. Never invent prices or appointments. Explain when information is unavailable. Never claim storage or transfer without a successful configured action.",
    "conversationHistoryLimit": 20,
    "knowledgeBaseId": null,
    "ragTopK": 5,
    "ragSimilarityThreshold": 0.5,
    "temperature": 0.3,
    "maxTokens": 1000,
    "ttsStreamingMode": "QUALITY_SSML",
    "queryTransformEnabled": false,
    "queryTransformHistoryLimit": 5,
    "queryTransformConfidenceThreshold": 0.8,
    "queryTransformMode": "LLM"
  }
}

Response 200

Success.

Header Type Description
Cache-Control string The response must not be cached.
Example: no-store
ETag string Current revision. Send unchanged, including quotes, as If-Match when required.
Example: "revision-from-get"

application/json

Field Type Description
id string (uuid) Resource ID in your workspace.
revision string Current resource revision. Use the response ETag for If-Match when updating.
agent object Conversation, speech recognition and voice settings.
options object Model, prompt and knowledge-search settings.
agent — fields
Field Type Description
enabled boolean Enable the Agent. Omission or null means false.
agentType string VOICE handles voice calls; AGENTIC is a specialist in an Agentic Flow.
Values: AGENTIC, VOICE
title string Display name of the resource.
Rules: up to 255 characters
Example: "Demo"
description string Description of this resource's purpose.
Rules: up to 10000 characters; null allowed
agentName string Name the Agent uses when speaking to callers.
Rules: up to 255 characters
Example: "Demo Assistant"
persona string Personality and speaking style for the Agent.
Rules: up to 10000 characters; null allowed
sttLanguages List of string Languages Azure should recognize. Values stay stored when another speech provider is selected.
Rules: at least 1 entry; no duplicates
Example: ["de-DE"]
Show all 85 allowed values

de-DE, de-AT, de-CH, en-US, en-GB, en-AU, en-CA, en-IE, en-IN, es-ES, es-MX, fr-FR, fr-CA, nl-NL, nl-BE, pt-BR, pt-PT, ja-JP, zh-CN, zh-HK, it-IT, pl-PL, cs-CZ, da-DK, sv-SE, fi-FI, el-GR, ru-RU, tr-TR, ar-EG, af-ZA, am-ET, hy-AM, az-AZ, bn-IN, bs-BA, bg-BG, ca-ES, hr-HR, et-EE, fa-IR, fil-PH, ka-GE, gl-ES, gu-IN, he-IL, hi-IN, hu-HU, is-IS, id-ID, jv-ID, kn-IN, kk-KZ, km-KH, ko-KR, lo-LA, lt-LT, lv-LV, mk-MK, ms-MY, mt-MT, mn-MN, nb-NO, ne-NP, pa-IN, ps-AF, sw-KE, ta-IN, te-IN, th-TH, uk-UA, ur-PK, uz-UZ, vi-VN, sr-RS, sq-AL, so-SO, sl-SI, sk-SK, si-LK, ro-RO, my-MM, ml-IN, ga-IE, cy-GB
voiceId string Exact ID from the voice catalog, including its provider prefix.
Rules: up to 255 characters
voiceConfiguration object Parameters supported by the selected voice. Null removes these parameters on Agent updates.
greetingMorningText string Morning greeting, using the Agent's timezone.
Rules: up to 4000 characters
greetingAfternoonText string Afternoon greeting, using the Agent's timezone.
Rules: up to 4000 characters
greetingEveningText string Evening greeting, using the Agent's timezone.
Rules: up to 4000 characters
importantNote string Additional instructions for the Agent.
Rules: up to 10000 characters; null allowed
initialSilenceTimeoutMs integer (int32) How long Azure waits for the caller to start speaking, in milliseconds.
Rules: 0–60000
Example: 1500
segmentationSilenceTimeoutMs integer (int32) Silence after which Azure separates recognized speech into segments, in milliseconds.
Rules: 100–5000
Example: 500
phraseList List of string Words or phrases to help speech recognition, such as product names. Send separate list entries, not comma-separated text.
Rules: up to 500 entries; null allowed
Example: ["Nuvoca"]
Each entry: up to 500 characters
timezone string IANA timezone used for time-dependent Agent behavior, such as Europe/Berlin.
Rules: up to 100 characters; null allowed
Example: "Europe/Berlin"
greetingNonInterruptible boolean Prevent the caller from interrupting the greeting.
Rules: null allowed
greetingTimeoutSeconds integer (int32) Greeting time limit, in seconds.
Rules: 5–300; null allowed
Example: 30
sttProvider string Speech-recognition provider from the Agent catalog.
Rules: null allowed
Values: AZURE, DEEPGRAM, KUGEL
deepgramEotThreshold number Confidence required for Deepgram to consider the caller's turn complete.
Rules: 0.5–0.9; null allowed
deepgramEotTimeoutMs integer (int32) Deepgram timeout for detecting the end of a turn, in milliseconds.
Rules: 500–10000; null allowed
deepgramLanguageHints List of string Language hints from the Agent catalog. They guide Deepgram without restricting its supported languages.
Rules: no duplicates; null allowed
Show all 10 allowed values

de, en, es, fr, hi, it, ja, nl, pt, ru
preferPreProcessingGreeting boolean Use the greeting from pre-processing when one is available.
Rules: null allowed
kugelLanguages List of string Ordered Kugel language codes from the Agent catalog. The first is the expected starting language. Defaults to German on creation; omission on update keeps the current list.
Rules: 1–9 entries; null allowed
kugelTurnDetectionLevel string RESPONSIVE reacts quickly; CONSERVATIVE waits longer during pauses. Applies to new calls; omission on update keeps the current setting.
Rules: null allowed
Values: RESPONSIVE, CONSERVATIVE
voiceConfiguration — fields
Field Type Description
temperature number (double) Voice sampling temperature. Lower values produce more consistent speech.
Rules: 0.3–1; null allowed
topP number (double) Top-p sampling setting, if supported by the voice.
Rules: 0.3–1; null allowed
topK integer (int32) Top-k sampling setting, if supported by the voice.
Rules: 1–50; null allowed
cfgScale number (double) Guidance strength for voices that support this parameter.
Rules: 1–2; null allowed
telecomEffectEnabled boolean Apply telephone-style audio for supported Azure HD voices. Null uses the platform default.
enhancePronunciationEnabled boolean Enable pronunciation enhancement for supported Azure HD voices. Null uses the platform default.
xmlLang string Language or accent code supported by the selected voice.
Rules: up to 10 characters; null allowed
Example: "de-AT"
style string Speaking style supported by the selected voice.
Rules: up to 50 characters; null allowed
options — fields
Field Type Description
model string Agent model from the Agent catalog. Check its reasoning, temperature and output limits.
Show all 19 allowed values

GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
reasoningEffort string Reasoning effort supported by the selected model in the Agent catalog.
Values: NONE, MINIMAL, LOW
systemPrompt string Complete Agent instructions, including behavior, knowledge boundaries and error handling.
Rules: up to 100000 characters
conversationHistoryLimit integer (int32) Maximum number of conversation-history entries supplied to the model.
Rules: 1–100
Example: 20
knowledgeBaseId string (uuid) ID of the assigned Knowledge Base. Null removes the assignment.
ragTopK integer (int32) Maximum knowledge chunks retrieved per search.
Rules: 1–50
Example: 5
ragSimilarityThreshold number (double) Minimum similarity a knowledge chunk must have to be included.
Rules: 0–1
Example: 0.5
temperature number (double) Response variation. Respect any fixed temperature in the selected model's catalog entry.
Rules: 0–2
Example: 0.3
maxTokens integer (int32) Maximum output-token budget. Also respect the selected model's limit in the catalog.
Rules: 10–25000
Example: 1000
ttsStreamingMode string Speech-output mode selected from the Agent catalog.
Values: QUALITY_SSML, LOW_LATENCY_TEXT_STREAM
queryTransformEnabled boolean Rewrite knowledge-search queries before retrieval. Omission or null means false.
queryTransformHistoryLimit integer (int32) Maximum conversation-history entries used for query rewriting.
Rules: 1–100
Example: 5
queryTransformPrompt string Query-rewrite prompt for LLM mode. DECISION mode uses decisionQueryTransform.
Rules: up to 20000 characters
queryTransformConfidenceThreshold number (double) Confidence required for the query transformer.
Rules: 0–1
Example: 0.8
queryTransformMode string Use an LLM rewrite or a separate search decision and rewrite.
Values: LLM, DECISION
decisionQueryTransform object Search-decision and query-rewrite settings. Requires availability in the Agent catalog.
decisionQueryTransform — fields
Field Type Description
rewriteModel string Model used for query rewriting. Select a catalog model with supportsQueryRewrite=true.
Show all 19 allowed values

GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
parallel boolean Run the search decision and query rewrite at the same time.
decisionPrompt string Instructions for deciding whether to search the Knowledge Base: SEARCH or SKIP.
rewritePrompt string Instructions for rewriting the knowledge-search query. 
{
  "id": "00000000-0000-0000-0000-000000000001",
  "revision": "revision-from-get",
  "agent": {
    "enabled": false,
    "agentType": "VOICE",
    "title": "Demo",
    "description": "string",
    "agentName": "Demo Assistant",
    "persona": "string",
    "sttLanguages": [
      "de-DE"
    ],
    "voiceId": "azure:FLORIAN_HD",
    "voiceConfiguration": {
      "temperature": 0.3,
      "topP": 0.3,
      "topK": 1,
      "cfgScale": 1,
      "telecomEffectEnabled": false,
      "enhancePronunciationEnabled": false,
      "xmlLang": "de-AT",
      "style": "string"
    },
    "greetingMorningText": "string",
    "greetingAfternoonText": "string",
    "greetingEveningText": "string",
    "importantNote": "string",
    "initialSilenceTimeoutMs": 1500,
    "segmentationSilenceTimeoutMs": 500,
    "phraseList": [
      "Nuvoca"
    ],
    "timezone": "Europe/Berlin",
    "greetingNonInterruptible": false,
    "greetingTimeoutSeconds": 30,
    "sttProvider": "AZURE",
    "deepgramEotThreshold": 0.5,
    "deepgramEotTimeoutMs": 500,
    "deepgramLanguageHints": [],
    "preferPreProcessingGreeting": false,
    "kugelLanguages": [
      "string"
    ],
    "kugelTurnDetectionLevel": "RESPONSIVE"
  },
  "options": {
    "model": "GPT_4_1_MINI",
    "reasoningEffort": "NONE",
    "systemPrompt": "string",
    "conversationHistoryLimit": 20,
    "knowledgeBaseId": "00000000-0000-0000-0000-000000000001",
    "ragTopK": 5,
    "ragSimilarityThreshold": 0.5,
    "temperature": 0.3,
    "maxTokens": 1000,
    "ttsStreamingMode": "QUALITY_SSML",
    "queryTransformEnabled": false,
    "queryTransformHistoryLimit": 5,
    "queryTransformPrompt": "string",
    "queryTransformConfidenceThreshold": 0.8,
    "queryTransformMode": "LLM",
    "decisionQueryTransform": {
      "rewriteModel": "GPT_4_1_MINI",
      "parallel": false,
      "decisionPrompt": "string",
      "rewritePrompt": "string"
    }
  }
}
Error responses
Status Meaning
400 Invalid input, unsupported selection or time range.
401 Missing, expired or invalid credential. The body may be empty.
403 Required scope or current user permission missing. The body may be empty.
404 Resource is unavailable in the bound workspace.
409 Missing/stale revision or dependency/routing conflict. Read again before retrying.
429 Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
503 Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field Type Description
status integer HTTP status code.
error string Description of the error.
details any Additional error details, when available.
Rules: null allowed
code string Machine-readable error code.
params object Additional values associated with the error code.
fieldErrors object Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Read legacy Agent snapshot

GET /api/external/v1/agents/{agentId}/configuration

Scope: agents:configuration:read

Read-only compatibility snapshot. Use GET /agents/{id} for editable configuration and an ETag.

Parameters

Name Location Type Required Description
agentId Path string (uuid) Yes Resource identifier in the bound workspace.

Response 200

Success.

Header Type Description
Cache-Control string The response must not be cached.
Example: no-store

application/json

Field Type Description
agent object Conversation, speech recognition and voice settings.
options object Model, prompt and knowledge-search settings.
agent — fields
Field Type Description
agentId string (uuid) ID of the Agent.
tenantId string (uuid) ID of the workspace bound to the credential.
enabled boolean Whether this resource is enabled.
agentType string VOICE handles voice calls; AGENTIC is a specialist in an Agentic Flow.
Values: AGENTIC, VOICE
title string Display name of the resource.
description string Description of this resource's purpose.
Rules: null allowed
agentName string Name the Agent uses when speaking to callers.
Rules: at least 1 character
persona string Personality and speaking style for the Agent.
Rules: null allowed
sttLanguages List of string Languages Azure should recognize. Values stay stored when another speech provider is selected.
Rules: no duplicates
Show all 85 allowed values

de-DE, de-AT, de-CH, en-US, en-GB, en-AU, en-CA, en-IE, en-IN, es-ES, es-MX, fr-FR, fr-CA, nl-NL, nl-BE, pt-BR, pt-PT, ja-JP, zh-CN, zh-HK, it-IT, pl-PL, cs-CZ, da-DK, sv-SE, fi-FI, el-GR, ru-RU, tr-TR, ar-EG, af-ZA, am-ET, hy-AM, az-AZ, bn-IN, bs-BA, bg-BG, ca-ES, hr-HR, et-EE, fa-IR, fil-PH, ka-GE, gl-ES, gu-IN, he-IL, hi-IN, hu-HU, is-IS, id-ID, jv-ID, kn-IN, kk-KZ, km-KH, ko-KR, lo-LA, lt-LT, lv-LV, mk-MK, ms-MY, mt-MT, mn-MN, nb-NO, ne-NP, pa-IN, ps-AF, sw-KE, ta-IN, te-IN, th-TH, uk-UA, ur-PK, uz-UZ, vi-VN, sr-RS, sq-AL, so-SO, sl-SI, sk-SK, si-LK, ro-RO, my-MM, ml-IN, ga-IE, cy-GB
voice string Voice identifier in the legacy Agent configuration.
Show all 714 allowed values

KLAUS_MAI_FLASH, MIA_MAI_FLASH, ISLA_MAI_FLASH, ETHAN_MAI_FLASH, GRANT_MAI_FLASH, HARPER_MAI_FLASH, IRIS_MAI_FLASH, JASPER_MAI_FLASH, OLIVIA_MAI_FLASH, MARTA_MAI_FLASH, ALEJO_MAI_FLASH, VALERIA_MAI_FLASH, MARC_MAI_FLASH, SOLEIL_MAI_FLASH, ARJUN_MAI_FLASH, DHRUV_MAI_FLASH, KAVYA_MAI_FLASH, PRIYA_MAI_FLASH, BENCE_MAI_FLASH, LEVENTE_MAI_FLASH, LILLA_MAI_FLASH, REKA_MAI_FLASH, CAHYA_MAI_FLASH, SARI_MAI_FLASH, LUCA_MAI_FLASH, ROSA_MAI_FLASH, HARUTO_MAI_FLASH, SAKURA_MAI_FLASH, HAENA_MAI_FLASH, JUNHO_MAI_FLASH, FLEUR_MAI_FLASH, SANDER_MAI_FLASH, CAIO_MAI_FLASH, LUANA_MAI_FLASH, PEDRO_MAI_FLASH, RAFAEL_MAI_FLASH, RUI_MAI_FLASH, ANDREI_MAI_FLASH, ELENA_MAI_FLASH, IOANA_MAI_FLASH, RADU_MAI_FLASH, LEV_MAI_FLASH, MASHA_MAI_FLASH, KRIT_MAI_FLASH, NATTAPONG_MAI_FLASH, AYDIN_MAI_FLASH, ELIF_MAI_FLASH, LINH_MAI_FLASH, BO_MAI_FLASH, LAN_MAI_FLASH, MEI_MAI_FLASH, WEI_MAI_FLASH, CS_CZ_GRANT_MAI_FLASH, CS_CZ_HARPER_MAI_FLASH, DA_DK_GRANT_MAI_FLASH, DA_DK_HARPER_MAI_FLASH, DE_DE_GRANT_MAI_FLASH, DE_DE_HARPER_MAI_FLASH, EN_GB_EMILY_MAI_FLASH, EN_GB_HARRY_MAI_FLASH, EN_IN_DHRUV_MAI_FLASH, EN_IN_PRIYA_MAI_FLASH, EN_US_SAGE_MAI_FLASH, ES_MX_GRANT_MAI_FLASH, ES_MX_HARPER_MAI_FLASH, FI_FI_GRANT_MAI_FLASH, FI_FI_HARPER_MAI_FLASH, FR_FR_GRANT_MAI_FLASH, FR_FR_HARPER_MAI_FLASH, HI_IN_GRANT_MAI_FLASH, HI_IN_HARPER_MAI_FLASH, HU_HU_GRANT_MAI_FLASH, HU_HU_HARPER_MAI_FLASH, ID_ID_GRANT_MAI_FLASH, ID_ID_HARPER_MAI_FLASH, IT_IT_GRANT_MAI_FLASH, IT_IT_HARPER_MAI_FLASH, KO_KR_GRANT_MAI_FLASH, KO_KR_HARPER_MAI_FLASH, NB_NO_GRANT_MAI_FLASH, NB_NO_HARPER_MAI_FLASH, NL_NL_GRANT_MAI_FLASH, NL_NL_HARPER_MAI_FLASH, PL_PL_GRANT_MAI_FLASH, PL_PL_HARPER_MAI_FLASH, PT_BR_GRANT_MAI_FLASH, PT_BR_HARPER_MAI_FLASH, PT_PT_GRANT_MAI_FLASH, PT_PT_HARPER_MAI_FLASH, RO_RO_GRANT_MAI_FLASH, RO_RO_HARPER_MAI_FLASH, RU_RU_GRANT_MAI_FLASH, RU_RU_HARPER_MAI_FLASH, SV_SE_GRANT_MAI_FLASH, SV_SE_HARPER_MAI_FLASH, TH_TH_GRANT_MAI_FLASH, TH_TH_HARPER_MAI_FLASH, TR_TR_GRANT_MAI_FLASH, TR_TR_HARPER_MAI_FLASH, VI_VN_GRANT_MAI_FLASH, VI_VN_HARPER_MAI_FLASH, ZH_CN_GRANT_MAI_FLASH, ZH_CN_HARPER_MAI_FLASH, CS_CZ_GRANT_MAI_21, CS_CZ_HARPER_MAI_21, DA_DK_GRANT_MAI_21, DA_DK_HARPER_MAI_21, DE_DE_GRANT_MAI_21, DE_DE_HARPER_MAI_21, DE_DE_KLAUS_MAI_21, DE_DE_MIA_MAI_21, EN_AU_ISLA_MAI_21, EN_GB_EMILY_MAI_21, EN_GB_HARRY_MAI_21, EN_IN_DHRUV_MAI_21, EN_IN_PRIYA_MAI_21, EN_US_ETHAN_MAI_21, EN_US_GRANT_MAI_21, EN_US_HARPER_MAI_21, EN_US_IRIS_MAI_21, EN_US_JASPER_MAI_21, EN_US_OLIVIA_MAI_21, EN_US_SAGE_MAI_21, ES_ES_MARTA_MAI_21, ES_MX_ALEJO_MAI_21, ES_MX_GRANT_MAI_21, ES_MX_HARPER_MAI_21, ES_MX_VALERIA_MAI_21, FI_FI_GRANT_MAI_21, FI_FI_HARPER_MAI_21, FR_FR_GRANT_MAI_21, FR_FR_HARPER_MAI_21, FR_FR_MARC_MAI_21, FR_FR_SOLEIL_MAI_21, HI_IN_ARJUN_MAI_21, HI_IN_DHRUV_MAI_21, HI_IN_GRANT_MAI_21, HI_IN_HARPER_MAI_21, HI_IN_KAVYA_MAI_21, HI_IN_PRIYA_MAI_21, HU_HU_BENCE_MAI_21, HU_HU_GRANT_MAI_21, HU_HU_HARPER_MAI_21, HU_HU_LEVENTE_MAI_21, HU_HU_LILLA_MAI_21, HU_HU_REKA_MAI_21, ID_ID_GRANT_MAI_21, ID_ID_HARPER_MAI_21, IT_IT_GRANT_MAI_21, IT_IT_HARPER_MAI_21, IT_IT_LUCA_MAI_21, IT_IT_ROSA_MAI_21, KO_KR_GRANT_MAI_21, KO_KR_HAENA_MAI_21, KO_KR_HARPER_MAI_21, KO_KR_JUNHO_MAI_21, NB_NO_GRANT_MAI_21, NB_NO_HARPER_MAI_21, NL_NL_GRANT_MAI_21, NL_NL_HARPER_MAI_21, NL_NL_SANDER_MAI_21, PL_PL_GRANT_MAI_21, PL_PL_HARPER_MAI_21, PT_BR_CAIO_MAI_21, PT_BR_GRANT_MAI_21, PT_BR_HARPER_MAI_21, PT_BR_LUANA_MAI_21, PT_BR_PEDRO_MAI_21, PT_BR_RAFAEL_MAI_21, PT_PT_GRANT_MAI_21, PT_PT_HARPER_MAI_21, PT_PT_RUI_MAI_21, RO_RO_ANDREI_MAI_21, RO_RO_ELENA_MAI_21, RO_RO_GRANT_MAI_21, RO_RO_HARPER_MAI_21, RO_RO_IOANA_MAI_21, RO_RO_RADU_MAI_21, RU_RU_GRANT_MAI_21, RU_RU_HARPER_MAI_21, RU_RU_LEV_MAI_21, RU_RU_MASHA_MAI_21, SV_SE_GRANT_MAI_21, SV_SE_HARPER_MAI_21, TH_TH_GRANT_MAI_21, TH_TH_HARPER_MAI_21, TH_TH_KRIT_MAI_21, TH_TH_NATTAPONG_MAI_21, TR_TR_AYDIN_MAI_21, TR_TR_ELIF_MAI_21, TR_TR_GRANT_MAI_21, TR_TR_HARPER_MAI_21, VI_VN_GRANT_MAI_21, VI_VN_HARPER_MAI_21, ZH_CN_BO_MAI_21, ZH_CN_GRANT_MAI_21, ZH_CN_HARPER_MAI_21, ZH_CN_LAN_MAI_21, ZH_CN_MEI_MAI_21, ZH_CN_WEI_MAI_21, ADRI_OMNI, WILLEM_OMNI, AMEHA_OMNI, MEKDES_OMNI, FATIMA_OMNI, HAMDAN_OMNI, ALI_OMNI, LAILA_OMNI, AMINA_OMNI, ISMAEL_OMNI, SALEH_OMNI, SALMA_OMNI, SHAKIR_OMNI, BASSEL_OMNI, RANA_OMNI, SANA_OMNI, TAIM_OMNI, FAHED_OMNI, NOURA_OMNI, LAYLA_OMNI, RAMI_OMNI, IMAN_OMNI, OMAR_OMNI, JAMAL_OMNI, MOUNA_OMNI, ABDULLAH_OMNI, AMAL_OMNI, MOAZ_OMNI, HAMED_OMNI, ZARIYAH_OMNI, LAITH_OMNI, HEDI_OMNI, BABEK_OMNI, BANU_OMNI, KALINA_OMNI, BASHKAR_OMNI, TANISHAA_OMNI, GORAN_OMNI, VESNA_OMNI, ALBA_OMNI, ENRIC_OMNI, JOANA_OMNI, ANTONIN_OMNI, VLASTA_OMNI, ALED_OMNI, NIA_OMNI, CHRISTEL_OMNI, JEPPE_OMNI, INGRID_OMNI, JAN_OMNI, LENI_OMNI, AMALA_OMNI, BERND_OMNI, CHRISTOPH_OMNI, CONRAD_OMNI, ELKE_OMNI, FLORIAN_OMNI, FLORIAN_HD, KASPER_OMNI, KILLIAN_OMNI, KLARISSA_OMNI, KLAUS_OMNI, LOUISA_OMNI, MAJA_OMNI, OLIVACANTIQUE_OMNI, PERLANAMI_OMNI, RALF_OMNI, SERAPHINA_OMNI, SERAPHINA_HD, TANJA_OMNI, ATHINA_OMNI, NESTORAS_OMNI, ANNETTE_OMNI, DARREN_OMNI, DUNCAN_OMNI, ELSIE_OMNI, FREYA_OMNI, JOANNE_OMNI, KEN_OMNI, KIM_OMNI, NATASHA_OMNI, NEIL_OMNI, TIM_OMNI, TINA_OMNI, WILLIAM_OMNI, CLARA_OMNI, LIAM_OMNI, ADA_OMNI, ALFIE_OMNI, AMARILLOMIRFAK_OMNI, AZABACHETITICACA_OMNI, BELLA_OMNI, ELLIOT_OMNI, ETHAN_OMNI, LIBBY_OMNI, NACARAEGEAN_OMNI, NOAH_OMNI, OLIVER_OMNI, OLIVIA_OMNI, OLLIE_OMNI, RUBIGANGES_OMNI, RYAN_OMNI, SANDOVERTURE_OMNI, THOMAS_OMNI, SAM_OMNI, YAN_OMNI, EMILY_OMNI, AARAV_OMNI, AARTI_OMNI, AASHI_OMNI, ANANYA_OMNI, ARJUN_OMNI, KAVYA_OMNI, KUNAL_OMNI, NEERJA_OMNI, PRABHAT_OMNI, REHAAN_OMNI, ASILIA_OMNI, CHILEMBA_OMNI, ABEO_OMNI, EZINNE_OMNI, MITCHELL_OMNI, MOLLY_OMNI, JAMES_OMNI, ROSA_OMNI, LUNA_OMNI, WAYNE_OMNI, ELIMU_OMNI, IMANI_OMNI, ADAM_OMNI, ALLOY_OMNI, AMANDA_OMNI, AMBER_OMNI, ANDREW_OMNI, ARIA_OMNI, AVA_OMNI, AZABACHESTRATUS_OMNI, AZULLEGATO_OMNI, BRANDON_OMNI, BRIAN_OMNI, CALEB_OMNI, CHARCOALSOLARIA_OMNI, CHRISTOPHER_OMNI, CRIMSONMODERATO_OMNI, DANA_OMNI, DUSTIN_OMNI, ECHO_OMNI, ELIZABETH_OMNI, EMMA_OMNI, ERIC_OMNI, GRISADAMANT_OMNI, JANE_OMNI, JASON_OMNI, KAI_OMNI, LEMONNEBULA_OMNI, LOLA_OMNI, LUNA_US_OMNI, MARIN_OMNI, MOSTAZAPENUMBRA_OMNI, NANCY_OMNI, ONYX_OMNI, PEACHSHANNON_OMNI, PEWTERMALACHITE_OMNI, PISTACHETHYME_OMNI, ROGER_OMNI, ROUGEPEARL_OMNI, RUBICALIMA_OMNI, SAMUEL_OMNI, SANDCADENZA_OMNI, SANDCHILI_OMNI, SHIMMER_OMNI, SLATENEBULIS_OMNI, TONY_OMNI, TURQUOISECREPUSCULO_OMNI, VIOLETVIVACE_OMNI, LEAH_OMNI, LUKE_OMNI, ELENA_OMNI, TOMAS_OMNI, MARCELO_OMNI, SOFIA_OMNI, CATALINA_OMNI, LORENZO_OMNI, GONZALO_OMNI, SALOME_OMNI, JUAN_OMNI, MARIA_OMNI, BELKYS_OMNI, MANUEL_OMNI, EMILIO_OMNI, RAMONA_OMNI, LUIS_OMNI, ABRIL_OMNI, ARABELLA_OMNI, ARNAU_OMNI, BLEUETGANGES_OMNI, ELIAS_OMNI, ELVIRA_OMNI, ESTRELLA_OMNI, GRAPHITEGARDA_OMNI, JAVIER_OMNI, LAIA_OMNI, NIL_OMNI, SAUL_OMNI, SLATEOLA_OMNI, TEO_OMNI, TRIANA_OMNI, VERA_OMNI, ANDRES_OMNI, CARLOS_OMNI, KARLA_OMNI, AMARILLOYUKI_OMNI, BEATRIZ_OMNI, BLUSHVINAGRE_OMNI, CANDELA_OMNI, CARLOTA_OMNI, CECILIO_OMNI, CORALPASTEQUE_OMNI, GERARDO_OMNI, GRISPERLEFRAISE_OMNI, INDIGODIMINUENDO_OMNI, LARISSA_OMNI, LIBERTO_OMNI, LUCIANO_OMNI, MAGENTAHORIZONTE_OMNI, MANDARINAFUYU_OMNI, NOIRFRAISE_OMNI, NURIA_OMNI, PELAYO_OMNI, RENATA_OMNI, SAFIROTASMAN_OMNI, VERDEPOIRE_OMNI, YAGO_OMNI, FEDERICO_OMNI, YOLANDA_OMNI, MARGARITA_OMNI, ROBERTO_OMNI, ALEX_OMNI, CAMILA_OMNI, KARINA_OMNI, VICTOR_OMNI, MARIO_OMNI, TANIA_OMNI, LORENA_OMNI, RODRIGO_OMNI, ALONSO_OMNI, PALOMA_OMNI, MATEO_OMNI, VALENTINA_OMNI, PAOLA_OMNI, SEBASTIAN_OMNI, ANU_OMNI, KERT_OMNI, DILARA_OMNI, FARID_OMNI, HARRI_OMNI, NOORA_OMNI, SELMA_OMNI, ANGELO_OMNI, BLESSICA_OMNI, CHARLINE_OMNI, GERARD_OMNI, ANTOINE_OMNI, JEAN_OMNI, SYLVIE_OMNI, THIERRY_OMNI, ARIANE_OMNI, FABRICE_OMNI, ALAIN_OMNI, BRIGITTE_OMNI, CARAMELOTSUKI_OMNI, CELESTE_OMNI, CELESTESEL_OMNI, CLAUDE_OMNI, CORALIE_OMNI, DENISE_OMNI, JACQUELINE_OMNI, JEROME_OMNI, JOSEPHINE_OMNI, LUCIEN_OMNI, MAURICE_OMNI, REMY_OMNI, VIVIENNE_OMNI, YVES_OMNI, COLM_OMNI, ORLA_OMNI, ROI_OMNI, SABELA_OMNI, DHWANI_OMNI, NIRANJAN_OMNI, AVRI_OMNI, HILA_OMNI, AARAV_HI_OMNI, AARTI_HI_OMNI, ANANYA_HI_OMNI, ARJUN_HI_OMNI, HEERA_OMNI, KAVYA_HI_OMNI, KUNAL_HI_OMNI, MADHUR_OMNI, REHAAN_HI_OMNI, SWARA_OMNI, GABRIJELA_OMNI, NOEMI_OMNI, ANAHIT_OMNI, HAYK_OMNI, ARDI_OMNI, GADIS_OMNI, PRUNEARPEGGIO_OMNI, GUDRUN_OMNI, GUNNAR_OMNI, ALESSIO_OMNI, BENIGNO_OMNI, CALIMERO_OMNI, FABIOLA_OMNI, FIAMMA_OMNI, GIANNI_OMNI, IMELDA_OMNI, IRMA_OMNI, ISABELLA_OMNI, LISANDRO_OMNI, MARCELLO_OMNI, PALMIRA_OMNI, RINALDO_OMNI, DAICHI_OMNI, KEITA_OMNI, MASARU_OMNI, NAOKI_OMNI, SAFRANSAIMAA_OMNI, SHIORI_OMNI, SLATEADRIATIC_OMNI, DIMAS_OMNI, SITI_OMNI, EKA_OMNI, GIORGI_OMNI, AIGUL_OMNI, DAULET_OMNI, PISETH_OMNI, SREYMOM_OMNI, GAGAN_OMNI, SAPNA_OMNI, BONGJIN_OMNI, GOOKMIN_OMNI, INJOON_OMNI, JIMIN_OMNI, MARFILSTEEL_OMNI, MOCHACANNELLE_OMNI, YUJIN_OMNI, CHANTHAVONG_OMNI, KEOMANY_OMNI, LEONAS_OMNI, ONA_OMNI, EVERITA_OMNI, NILS_OMNI, ALEKSANDAR_OMNI, MARIJA_OMNI, MIDHUN_OMNI, SOBHANA_OMNI, BATAA_OMNI, YESUI_OMNI, YASMIN_OMNI, GRACE_OMNI, JOSEPH_OMNI, NILAR_OMNI, THIHA_OMNI, FINN_OMNI, ISELIN_OMNI, PERNILLE_OMNI, HEMKALA_OMNI, SAGAR_OMNI, ARNAUD_OMNI, DENA_OMNI, COLETTE_OMNI, MAARTEN_OMNI, OJAS_OMNI, AGNIESZKA_OMNI, MAREK_OMNI, ZOFIA_OMNI, GULNAWAZ_OMNI, LATIFA_OMNI, BLEUNOVA_OMNI, BLEUPEPPER_OMNI, BRENDA_OMNI, DONATO_OMNI, DOREREDWOOD_OMNI, ELZA_OMNI, FABIO_OMNI, FRANCISCA_OMNI, FUCSIACELTIC_OMNI, GIOVANNA_OMNI, HUMBERTO_OMNI, INDIGORUBIS_OMNI, IVORYNOCTURNE_OMNI, JULIO_OMNI, KURONILE_OMNI, LEILA_OMNI, MACERIO_OMNI, MANUELA_OMNI, NICOLAU_OMNI, OLIVAALBAHACA_OMNI, PLATACRESCENDO_OMNI, ROJOTREMOLO_OMNI, ROSEEBEURRE_OMNI, ROSEECASSIOPEIA_OMNI, THALITA_OMNI, VALERIO_OMNI, BLEUMARINEHEATWAVE_OMNI, BRUNPALLADIUM_OMNI, CREMAORATORIO_OMNI, FERNANDA_OMNI, ALINA_OMNI, EMIL_OMNI, DARIYA_OMNI, DMITRY_OMNI, SVETLANA_OMNI, SAMEERA_OMNI, THILINI_OMNI, LUKAS_OMNI, VIKTORIA_OMNI, PETRA_OMNI, ROK_OMNI, MUUSE_OMNI, UBAX_OMNI, ANILA_OMNI, ILIR_OMNI, NICHOLAS_OMNI, NICHOLASLATN_OMNI, SOPHIE_OMNI, HILLEVI_OMNI, MATTIAS_OMNI, SOFIE_OMNI, RAFIKI_OMNI, ZURI_OMNI, PALLAVI_OMNI, VALLUVAR_OMNI, MOHAN_OMNI, SHRUTI_OMNI, ACHARA_OMNI, NIWAT_OMNI, PREMWADEE_OMNI, AHMET_OMNI, EMEL_OMNI, OSTAP_OMNI, POLINA_OMNI, MADINA_OMNI, SARDOR_OMNI, HOAIMY_OMNI, NAMMINH_OMNI, AMBERROMARIN_OMNI, BLEUMARINECRISTAL_OMNI, CAFEPORTAMENTO_OMNI, CARAMELOTIBER_OMNI, GRAPHITEAURORA_OMNI, LILACRUBIS_OMNI, NAVYTORMENTA_OMNI, SAFIROSCHERZO_OMNI, SEPIAGIRASOL_OMNI, SILVERMARMARA_OMNI, XIAOCHEN_OMNI, XIAOHAN_OMNI, XIAOMENG_OMNI, XIAOMO_OMNI, XIAOROU_OMNI, XIAOYI_OMNI, XIAOYOU_OMNI, XIAOYUE_OMNI, YUNFAN_OMNI, YUNHAO_OMNI, YUNJIAN_OMNI, YUNJIE_OMNI, YUNQI_OMNI, YUNXIA_OMNI, YUNXIANG_OMNI, YUNXIAO_OMNI, YUNYANG_OMNI, YUNYI_OMNI, YUNZE_CUSTOMER_OMNI, HENAN_YUNDENG_OMNI, LIAONING_XIAOBEI_OMNI, SHAANXI_XIAONI_OMNI, SICHUAN_YUNXISICHUAN_OMNI, BLANCOFLORE_OMNI, GRISPIMIENTA_OMNI, HIUGAAI_OMNI, WANLUNG_OMNI, HSIAOCHEN_OMNI, HSIAOYU_OMNI, YUNJHE_OMNI, ADAM_HD, ALLOY_HD, ANDREW_HD, ANDREW2_HD, ANDREW3_HD, ARIA_HD, AVA_HD, AVA3_HD, BRIAN_HD, DAVIS_HD, EMMA_HD, EMMA2_HD, JENNY_HD, MULTITALKER_AVA_ANDREW_HD, NOVA_HD, PHOEBE_HD, SERENA_HD, STEFFAN_HD, TRISTAN_HD, XIMENA_HD, REMY_HD, VIVIENNE_HD, MASARU_HD, NANAMI_HD, XIAOCHEN_HD, YUNFAN_HD
voiceConfiguration object Parameters supported by the selected voice. Null removes these parameters on Agent updates.
timezone string IANA timezone used for time-dependent Agent behavior, such as Europe/Berlin.
Rules: at least 1 character
greetingMorningText string Morning greeting, using the Agent's timezone.
greetingAfternoonText string Afternoon greeting, using the Agent's timezone.
greetingEveningText string Evening greeting, using the Agent's timezone.
importantNote string Additional instructions for the Agent.
Rules: null allowed
initialSilenceTimeoutMs integer (int32) How long Azure waits for the caller to start speaking, in milliseconds.
segmentationSilenceTimeoutMs integer (int32) Silence after which Azure separates recognized speech into segments, in milliseconds.
phraseList List of string Words or phrases to help speech recognition, such as product names. Send separate list entries, not comma-separated text.
greetingNonInterruptible boolean Prevent the caller from interrupting the greeting.
greetingTimeoutSeconds integer (int32) Greeting time limit, in seconds.
sttProvider string Speech-recognition provider from the Agent catalog.
Values: AZURE, DEEPGRAM, KUGEL
deepgramEotThreshold number Confidence required for Deepgram to consider the caller's turn complete.
deepgramEotTimeoutMs integer (int32) Deepgram timeout for detecting the end of a turn, in milliseconds.
deepgramLanguageHints List of string Language hints from the Agent catalog. They guide Deepgram without restricting its supported languages.
Rules: no duplicates
Show all 10 allowed values

de, en, es, fr, hi, it, ja, nl, pt, ru
preferPreProcessingGreeting boolean Use the greeting from pre-processing when one is available.
ttsProvider string Speech-output provider in the legacy Agent configuration.
Rules: null allowed
Values: AZURE, KUGEL
kugelVoiceId integer (int32) Voice identifier in the legacy Kugel configuration.
Rules: ≥ 1; null allowed
kugelLanguages List of string Ordered Kugel language codes from the Agent catalog. The first is the expected starting language. Defaults to German on creation; omission on update keeps the current list.
kugelTurnDetectionLevel string RESPONSIVE reacts quickly; CONSERVATIVE waits longer during pauses. Applies to new calls; omission on update keeps the current setting.
Values: RESPONSIVE, CONSERVATIVE
voiceConfiguration — fields
Field Type Description
temperature number (double) Voice sampling temperature. Lower values produce more consistent speech.
Rules: 0.3–1; null allowed
topP number (double) Top-p sampling setting, if supported by the voice.
Rules: 0.3–1; null allowed
topK integer (int32) Top-k sampling setting, if supported by the voice.
Rules: 1–50; null allowed
cfgScale number (double) Guidance strength for voices that support this parameter.
Rules: 1–2; null allowed
telecomEffectEnabled boolean Apply telephone-style audio for supported Azure HD voices. Null uses the platform default.
enhancePronunciationEnabled boolean Enable pronunciation enhancement for supported Azure HD voices. Null uses the platform default.
xmlLang string Language or accent code supported by the selected voice.
Rules: up to 10 characters; null allowed
Example: "de-AT"
style string Speaking style supported by the selected voice.
Rules: up to 50 characters; null allowed
options — fields
Field Type Description
model string Agent model from the Agent catalog. Check its reasoning, temperature and output limits.
Show all 19 allowed values

GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
reasoningEffort string Reasoning effort supported by the selected model in the Agent catalog.
Values: NONE, MINIMAL, LOW
systemPrompt string Complete Agent instructions, including behavior, knowledge boundaries and error handling.
Rules: at least 1 character
conversationHistoryLimit integer (int32) Maximum number of conversation-history entries supplied to the model.
knowledgeBaseId string (uuid) ID of the assigned Knowledge Base. Null removes the assignment.
ragTopK integer (int32) Maximum knowledge chunks retrieved per search.
ragSimilarityThreshold number (double) Minimum similarity a knowledge chunk must have to be included.
temperature number (double) Response variation. Respect any fixed temperature in the selected model's catalog entry.
Rules: 0–2
maxTokens integer (int32) Maximum output-token budget. Also respect the selected model's limit in the catalog.
Rules: 10–25000
ttsStreamingMode string Speech-output mode selected from the Agent catalog.
Values: QUALITY_SSML, LOW_LATENCY_TEXT_STREAM
queryTransformEnabled boolean Rewrite knowledge-search queries before retrieval. Omission or null means false.
queryTransformHistoryLimit integer (int32) Maximum conversation-history entries used for query rewriting.
queryTransformPrompt string Query-rewrite prompt for LLM mode. DECISION mode uses decisionQueryTransform.
queryTransformConfidenceThreshold number (double) Confidence required for the query transformer.
queryTransformMode string Use an LLM rewrite or a separate search decision and rewrite.
Values: LLM, DECISION
decisionQueryTransform object Search-decision and query-rewrite settings. Requires availability in the Agent catalog.
decisionQueryTransform — fields
Field Type Description
rewriteModel string Model used for query rewriting. Select a catalog model with supportsQueryRewrite=true.
Show all 19 allowed values

GPT_6_1_SOL, GPT_6_1_TERRA, GPT_6_SOL, GPT_6_LUNA, GPT_5_6_SOL, GPT_5_6_TERRA, GPT_5_6_LUNA, GPT_5, GPT_5_MINI, GPT_5_NANO, GPT_5_4, GPT_5_4_MINI, GPT_5_4_NANO, GPT_4_1, GPT_4_1_MINI, GPT_4_1_NANO, DEEPSEEK_V4_FLASH, MISTRAL_LARGE_3, MICROSOFT_DECISION_1
parallel boolean Run the search decision and query rewrite at the same time.
decisionPrompt string Instructions for deciding whether to search the Knowledge Base: SEARCH or SKIP.
rewritePrompt string Instructions for rewriting the knowledge-search query. 
{
  "agent": {
    "agentId": "00000000-0000-0000-0000-000000000001",
    "tenantId": "00000000-0000-0000-0000-000000000001",
    "enabled": false,
    "agentType": "VOICE",
    "title": "NuvoCar service",
    "description": "string",
    "agentName": "string",
    "persona": "string",
    "sttLanguages": [],
    "voice": "KLAUS_MAI_FLASH",
    "voiceConfiguration": {
      "temperature": 0.3,
      "topP": 0.3,
      "topK": 1,
      "cfgScale": 1,
      "telecomEffectEnabled": false,
      "enhancePronunciationEnabled": false,
      "xmlLang": "de-AT",
      "style": "string"
    },
    "timezone": "string",
    "greetingMorningText": "string",
    "greetingAfternoonText": "string",
    "greetingEveningText": "string",
    "importantNote": "string",
    "initialSilenceTimeoutMs": 0,
    "segmentationSilenceTimeoutMs": 0,
    "phraseList": [],
    "greetingNonInterruptible": false,
    "greetingTimeoutSeconds": 0,
    "sttProvider": "AZURE",
    "deepgramEotThreshold": 0,
    "deepgramEotTimeoutMs": 0,
    "deepgramLanguageHints": [],
    "preferPreProcessingGreeting": false,
    "ttsProvider": "AZURE",
    "kugelVoiceId": 1,
    "kugelLanguages": [],
    "kugelTurnDetectionLevel": "RESPONSIVE"
  },
  "options": {
    "model": "GPT_4_1_MINI",
    "reasoningEffort": "NONE",
    "systemPrompt": "string",
    "conversationHistoryLimit": 0,
    "knowledgeBaseId": "00000000-0000-0000-0000-000000000001",
    "ragTopK": 0,
    "ragSimilarityThreshold": 0,
    "temperature": 0,
    "maxTokens": 10,
    "ttsStreamingMode": "QUALITY_SSML",
    "queryTransformEnabled": false,
    "queryTransformHistoryLimit": 0,
    "queryTransformPrompt": "string",
    "queryTransformConfidenceThreshold": 0,
    "queryTransformMode": "LLM",
    "decisionQueryTransform": {
      "rewriteModel": "GPT_4_1_MINI",
      "parallel": false,
      "decisionPrompt": "string",
      "rewritePrompt": "string"
    }
  }
}
Error responses
Status Meaning
400 Invalid input, unsupported selection or time range.
401 Missing, expired or invalid credential. The body may be empty.
403 Required scope or current user permission missing. The body may be empty.
404 Resource is unavailable in the bound workspace.
429 Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
503 Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field Type Description
status integer HTTP status code.
error string Description of the error.
details any Additional error details, when available.
Rules: null allowed
code string Machine-readable error code.
params object Additional values associated with the error code.
fieldErrors object Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.