Skip to main content
POST
/
v1
/
agents
Create agent
curl --request POST \
  --url https://api.nixflex.com/v1/agents
Creates a new AI agent. The agent immediately becomes available to attach to phone numbers and use for outbound calls.

​
Request

curl -X POST https://api.nixflex.com/v1/agents \
  -H "Authorization: Bearer KEY_ID:KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Dental Receptionist",
    "system_prompt": "You are the friendly front-desk assistant at Acme Dental in Croydon...",
    "welcome_message": "Hello, Acme Dental, how can I help?",
    "voice_id": "Ashley",
    "language": "multi",
    "transfer_number": "+442087601234",
    "webhook_url": "https://api.acmedental.com/nixflex/calls"
  }'

​
Body parameters

Only name is recommended in practice — every other field has a sensible default. You can create a working agent with a one-line payload.

​
Core

FieldTypeRequiredDefaultNotes
namestringNo"Untitled Agent"Display name (max 100 chars)
system_promptstringNofriendly assistantThe AI’s instructions (max ~10k chars)
welcome_messagestringNo"Hello! How can I help you today?"First line spoken on inbound calls
voice_idstringNo"Ashley"Voice name. Browse voices in the dashboard
languagestringNo"multi"Default language. multi auto-detects
is_activeboolNotrueSet false to disable without deleting

​
Behaviour

FieldTypeRequiredDefaultNotes
temperaturenumberNo0.3AI temperature, 0-1
response_lengthenumNo"short"short, medium, long
ai_speaks_firstboolNotrueAgent greets caller immediately
dynamic_greetingboolNofalseAI improvises greeting per call instead of static welcome
interruption_sensitivityintNo500-100. Lower = harder to interrupt
pickup_delayintNo10Seconds the agent waits after pickup before speaking. Range 5–30.

​
Call controls

FieldTypeRequiredDefaultNotes
max_call_duration_secondsintNo300Hard cap on call length. Range 60–1800 (1–30 min). See End call.
silence_hangup_secondsintNo10Hang up if caller silent this long. Range 5–45. See End call.
record_callboolNotrueSave call audio to Supabase Storage
webhook_urlstringNonullWhere to POST post-call data

​
Functions (tools the agent can call mid-conversation)

FieldTypeRequiredDefaultNotes
func_end_callboolNotrueAgent can end the call cleanly
transfer_whisperstringNonullWarm transfer briefing text. If empty, the AI auto-generates from the conversation.
ullWarm transfer briefing text. If empty, the AI auto-generates from the conversation.
func_send_smsboolNofalseAgent can send SMS during the call
transfer_typeenumNo"cold"cold or warm. Applies to inbound, outbound, and batch calls made by this agent. See Transfer.
transfer_numberstringNonullDefault destination for transfers

​
Other

FieldTypeRequiredDefaultNotes
voice_speednumberNo0.850.5-2.0. Voice speed
fallback_messagestringNo”I am sorry, could you say that again?”Said when transcription fails
phone_numberstringNonullLegacy. Numbers are now managed via /phone-numbers

​
Response

201 Created: 
{
  "id": "1083c0db-699e-49ee-aa6c-aab29e2d87cf",
  "agent_id": "agent_125207e452f8714a",
  "api_key_id": "nxf_a1b2c3d4...",
  "name": "Acme Dental Receptionist",
  "system_prompt": "You are the friendly front-desk assistant...",
  "welcome_message": "Hello! How can I help you today?",
  "voice_id": "Ashley",
  "language": "multi",
  "temperature": 0.3,
  "response_length": "short",
  "ai_speaks_first": true,
  "dynamic_greeting": false,
  "interruption_sensitivity": 50,
  "pickup_delay": 10,
  "max_call_duration_seconds": 300,
  "silence_hangup_seconds": 10,
  "record_call": true,
  "func_end_call": true,
  "transfer_whisper": null,
  "func_send_sms": false,
  "transfer_type": "cold",
  "transfer_number": null,
  "webhook_url": null,
  "phone_number": null,
  "voice_speed": 0.85,
  "fallback_message": "I am sorry, could you say that again?",
  "is_active": true,
  "created_at": "2026-05-24T01:48:10Z",
  "updated_at": "2026-05-24T01:48:10Z"
}
Save the agent_id — you’ll use it for every subsequent operation.

​
Next step

Attach a Twilio phone number so the agent can make and receive calls. See Import phone number.

​
Errors

CodeCause
prompt_too_longsystem_prompt exceeds 10,000 characters
invalid_voice_idVoice not in supported list
invalid_languageLanguage code not supported
invalid_requestMissing required field or bad format
See Errors for handling patterns.