> ## Documentation Index > Fetch the complete documentation index at: https://docs.nixflex.com/llms.txt > Use this file to discover all available pages before exploring further. # Create agent > POST /v1/agents Creates a new AI agent. The agent immediately becomes available to attach to phone numbers and use for outbound calls. ## Request ```bash theme={null} 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 | Field | Type | Required | Default | Notes | | ----------------- | ------ | -------- | ------------------------------------ | ------------------------------------------ | | `name` | string | No | `"Untitled Agent"` | Display name (max 100 chars) | | `system_prompt` | string | No | friendly assistant | The AI's instructions (max \~10k chars) | | `welcome_message` | string | No | `"Hello! How can I help you today?"` | First line spoken on inbound calls | | `voice_id` | string | No | `"Ashley"` | Voice name. Browse voices in the dashboard | | `language` | string | No | `"multi"` | Default language. `multi` auto-detects | | `is_active` | bool | No | `true` | Set false to disable without deleting | ### Behaviour | Field | Type | Required | Default | Notes | | -------------------------- | ------ | -------- | --------- | ----------------------------------------------------------------- | | `temperature` | number | No | `0.3` | AI temperature, `0`-`1` | | `response_length` | enum | No | `"short"` | `short`, `medium`, `long` | | `ai_speaks_first` | bool | No | `true` | Agent greets caller immediately | | `dynamic_greeting` | bool | No | `false` | AI improvises greeting per call instead of static welcome | | `interruption_sensitivity` | int | No | `50` | `0`-`100`. Lower = harder to interrupt | | `pickup_delay` | int | No | `10` | Seconds the agent waits after pickup before speaking. Range 5–30. | ### Call controls | Field | Type | Required | Default | Notes | | --------------------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------- | | `max_call_duration_seconds` | int | No | `300` | Hard cap on call length. Range 60–1800 (1–30 min). See [End call](/actions/end-call). | | `silence_hangup_seconds` | int | No | `10` | Hang up if caller silent this long. Range 5–45. See [End call](/actions/end-call). | | `record_call` | bool | No | `true` | Save call audio to Supabase Storage | | `webhook_url` | string | No | `null` | Where to POST post-call data | ### Functions (tools the agent can call mid-conversation) | Field | Type | Required | Default | Notes | | ------------------ | ----------------------------------------------------------------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `func_end_call` | bool | No | `true` | Agent can end the call cleanly | | `transfer_whisper` | string | No | `null` | Warm transfer briefing text. If empty, the AI auto-generates from the conversation. | | ull | Warm transfer briefing text. If empty, the AI auto-generates from the conversation. | | | | | `func_send_sms` | bool | No | `false` | Agent can send SMS during the call | | `transfer_type` | enum | No | `"cold"` | `cold` or `warm`. Applies to inbound, outbound, and batch calls made by this agent. See [Transfer](/actions/transfer). | | `transfer_number` | string | No | `null` | Default destination for transfers | ### Other | Field | Type | Required | Default | Notes | | ------------------ | ------ | -------- | --------------------------------------- | ---------------------------------------------------- | | `voice_speed` | number | No | `0.85` | `0.5`-`2.0`. Voice speed | | `fallback_message` | string | No | "I am sorry, could you say that again?" | Said when transcription fails | | `phone_number` | string | No | `null` | Legacy. Numbers are now managed via `/phone-numbers` | ## Response `201 Created`: ```json theme={null} { "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](/api-reference/phone-numbers/import). ## Errors | Code | Cause | | ------------------ | ----------------------------------------- | | `prompt_too_long` | `system_prompt` exceeds 10,000 characters | | `invalid_voice_id` | Voice not in supported list | | `invalid_language` | Language code not supported | | `invalid_request` | Missing required field or bad format | See [Errors](/reference/errors) for handling patterns.