Agents
Create agent
Creates a new agent in the project tied to your API key and returns the full agent configuration, including the generated agent_id. An agent bundles the conversational persona (who_are_you, goal, steps), the speaking voice and languages, behavioral toggles (interruptions, ambient/thinking sounds), optional dynamic variables, webhook callbacks, and optional links to existing tools and analysis groups. Only name is conceptually essential; the remaining fields tune behavior and have sensible defaults. This is typically the first step in the workflow: create the agent, then create an analysis group, then link them.
curl --request POST \
--url 'https://api.nabrah.ai/api/ext/agent' \
--header 'X-API-Key: <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
"name": "Support Assistant",
"start_first": true,
"first_sentence": "مرحبًا، كيف يمكنني مساعدتك اليوم؟",
"agent_type": "basic",
"who_are_you": "You are Layla, a friendly customer support agent for Nabrah.",
"goal": "Resolve the caller'\''s billing question or hand off to a human if needed.",
"steps": "1) Greet the caller. 2) Identify the issue. 3) Look up account details. 4) Offer a resolution.",
"allow_interruptions": true,
"voice": "dania",
"languages": [
"ar"
],
"stack": "latest"
}'{
"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"
}Key body fields
Field meanings as they appear in the request body.
name is a human-readable label. who_are_you describes the agent's identity/persona, goal states what the call should accomplish, and steps outlines the procedure the agent should follow. first_sentence is the opening line and start_first controls whether the agent speaks first.
namewho_are_yougoalstepsfirst_sentencestart_firstsupport_dataagent_typevoice is a TTS voice ID — obtain valid values from GET /api/ext/tts/voices (e.g. "dania"). languages is the list of supported language codes (e.g. "ar", "en"). language_mode is "single" or "multi"; when multilingual, dtmf_language_message can prompt the caller to choose. speech_speed is a multiplier (e.g. 0.7–1.5) and allow_interruptions lets the caller barge in.
voicelanguageslanguage_modedtmf_language_messagespeech_speedallow_interruptionsbackground_ambient plays subtle background audio and background_ambient_volume sets its level; thinking_sound plays a filler sound while the agent processes and thinking_sound_volume sets its level.
background_ambientbackground_ambient_volumethinking_soundthinking_sound_volumetool_ids links existing tools (IDs from GET /api/ext/tool) and analysis_group_ids links existing analysis groups (IDs from GET /api/ext/analysis) at creation time. stack selects the model/runtime stack (e.g. "latest").
tool_idsanalysis_group_idsstackvariables are named placeholders the agent can reference at runtime; each has a name, a type, and a default_value.
variablespre_call_callback, post_call_callback, and post_analysis_callback each define an outbound HTTP webhook with a url and a list of parameters. Each parameter has a name, a location (e.g. "header", "query", "body"), a data_type, and a value.
pre_call_callbackpost_call_callbackpost_analysis_callbackResponse
Returns the full AgentResponse with the new agent_id and resolved relations.
Store the returned agent_id — you need it to fetch, update, delete, or link analysis groups to this agent. The response also expands linked tools, system_tools, and analysis_groups so you can confirm the wiring.
A 422 response means the body failed validation; inspect detail for the offending field path.
Callback 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.
Body
application/jsonSmallest practical payload: an Arabic-speaking agent with a persona and goal.
{
"name": "Support Assistant",
"start_first": true,
"first_sentence": "مرحبًا، كيف يمكنني مساعدتك اليوم؟",
"agent_type": "basic",
"who_are_you": "You are Layla, a friendly customer support agent for Nabrah.",
"goal": "Resolve the caller's billing question or hand off to a human if needed.",
"steps": "1) Greet the caller. 2) Identify the issue. 3) Look up account details. 4) Offer a resolution.",
"allow_interruptions": true,
"voice": "dania",
"languages": [
"ar"
],
"stack": "latest"
}Response
Successful Response
application/json
Validation Error
application/json