Agents
Update agent
Updates the agent identified by agent_id and returns the full updated configuration. The body uses the same fields as agent creation; provide the values you want the agent to have. Note that tool_ids and analysis_group_ids set the agent's links — use them to attach or replace linked tools and analysis groups. For adding analysis-group links specifically, you can also use the dedicated linking endpoints. Fetch the agent first (GET /api/ext/agent/{agent_id}) if you need its current values before modifying.
curl --request PUT \
--url 'https://api.nabrah.ai/api/ext/agent/<agent_id>' \
--header 'X-API-Key: <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
"name": "Support Assistant (v2)",
"start_first": true,
"first_sentence": "Hi, thanks for calling Nabrah support. How can I help today?",
"agent_type": "basic",
"who_are_you": "You are Layla, a senior support agent for Nabrah.",
"goal": "Resolve the caller'\''s issue on the first call whenever possible.",
"steps": "1) Greet. 2) Identify issue. 3) Resolve or escalate. 4) Confirm.",
"allow_interruptions": true,
"voice": "dania",
"languages": [
"ar",
"en"
],
"stack": "latest",
"speech_speed": 1,
"language_mode": "multi"
}'{
"agent_id": "00000000-0000-4000-8000-000000000000",
"project_id": "00000000-0000-4000-8000-000000000000",
"created_by_email": "string",
"created_at": "2026-01-15T12:00:00.000Z",
"last_update": "2026-01-15T12:00:00.000Z",
"name": "string",
"start_first": false,
"first_sentence": "string",
"agent_type": "basic",
"who_are_you": "string",
"goal": "string",
"steps": "string",
"allow_interruptions": false,
"voice": "dania",
"support_data": "string",
"languages": [
"ar"
],
"stack": "latest",
"speech_speed": 0.7,
"variables": [
{
"name": "string",
"type": "string",
"default_value": "string"
}
],
"pre_call_callback": {
"url": "string",
"parameters": [
{
"name": "string",
"location": "header",
"data_type": "string",
"value": "string"
}
]
},
"post_call_callback": {
"url": "string",
"parameters": [
{
"name": "string",
"location": "header",
"data_type": "string",
"value": "string"
}
]
},
"post_analysis_callback": {
"url": "string",
"parameters": [
{
"name": "string",
"location": "header",
"data_type": "string",
"value": "string"
}
]
},
"tools": [
{
"id": "00000000-0000-4000-8000-000000000000",
"name": "string"
}
],
"system_tools": [
{
"id": "00000000-0000-4000-8000-000000000000",
"name": "string",
"config": {},
"created_at": "2026-01-15T12:00:00.000Z",
"updated_at": "2026-01-15T12:00:00.000Z",
"when_to_use": "string"
}
],
"analysis_groups": [
{
"id": "00000000-0000-4000-8000-000000000000",
"name": "string"
}
],
"background_ambient": false,
"background_ambient_volume": 0,
"thinking_sound": false,
"thinking_sound_volume": 0,
"language_mode": "single"
}Where agent_id comes from
Use GET /api/ext/agent to list agents, or the agent_id returned by POST /api/ext/agent.
Field guidance
Body fields mirror Create Agent.
voice must be a valid TTS voice ID from GET /api/ext/tts/voices. tool_ids (from GET /api/ext/tool) and analysis_group_ids (from GET /api/ext/analysis) define the agent's current links. The update body does not include tool_ids/analysis_group_ids in the response; the response instead expands the resolved tools, system_tools, and analysis_groups.
voicetool_idsanalysis_group_idsCallback delivery
Callbacks are sent once and never retried.
pre_call_callbackCalled before each call, and before each chatbot reply on WhatsApp. Only an HTTP 200 JSON object is used; on any other response, an error or a timeout (10 seconds for calls, 30 seconds for WhatsApp) the conversation continues without those values.
pre_call_callbackpost_call_callback{ "call_details": { "id", … } }Sent once after a completed call, with a 30-second timeout. Calls that did not complete (for example no answer or busy) do not trigger it. Use call_details.id to deduplicate.
post_call_callbackpost_analysis_callbackSame payload, sent once after the call's analysis finishes.
post_analysis_callbackAuthenticationCallbacks are not signed. Add a secret header in parameters (location header) and check it on your side; body parameters are added to the JSON body.
Authorization
X-API-KeystringheaderrequiredYour workspace API key. Create one in the dashboard under API keys.
Path parameters
agent_idstringrequiredUUID of the agent to update.
Get this from GET /api/ext/agent or from the create-agent response (POST /api/ext/agent).
Body
application/jsonUpdate the display name and core persona while keeping behavior simple.
{
"name": "Support Assistant (v2)",
"start_first": true,
"first_sentence": "Hi, thanks for calling Nabrah support. How can I help today?",
"agent_type": "basic",
"who_are_you": "You are Layla, a senior support agent for Nabrah.",
"goal": "Resolve the caller's issue on the first call whenever possible.",
"steps": "1) Greet. 2) Identify issue. 3) Resolve or escalate. 4) Confirm.",
"allow_interruptions": true,
"voice": "dania",
"languages": [
"ar",
"en"
],
"stack": "latest",
"speech_speed": 1,
"language_mode": "multi"
}Response
Successful Response
application/json
Validation Error
application/json