<!-- Source: https://docs.vinsi.ai/api-docs/agent-create -->
# Create Agent

Create a new agent. name is required, and the outbound object (the settings used when the agent places outbound calls) must be included. waitingSound must be "", keyboard_typing or hold_music, and maxCallTime must be a whole number (0 = no limit). tools is a list of tool IDs. Responds 201 with the new agent.

```http
POST https://dashboard.vinsi.ai/api/agents
```

## Authentication

Send your API key in the `x-api-key` header. Create keys in the VINSI dashboard under Settings → API Keys.

## Headers

| Name | Type | Required |
|---|---|---|
| Content-Type | string | yes (application/json) |
| x-api-key | string | yes |

## Example request body

```json
{
  "name": "New Agent",
  "voiceId": "",
  "welcomeMessage": "Thank you for calling. How can I help you today?",
  "instructions": "Test",
  "knowledge_base": "",
  "temperature": 0.6,
  "vad_threshold": 0.7,
  "language": "en-US",
  "maxTokens": 250,
  "isActive": true,
  "tools": [],
  "dispositions": [],
  "afterCallWebhookUrl": null,
  "timezone": "America/Los_Angeles",
  "firstActionToolId": null,
  "callData": {},
  "waitingSound": "",
  "allowInterruptions": "yes",
  "turnDetectionSensitivity": 0.7,
  "voiceSelectionMode": "cycling",
  "outbound": {
    "voiceId": "",
    "welcomeMessage": "Hi, this is Acme Dental calling about your appointment.",
    "instructions": "Confirm the appointment date and time.",
    "knowledge_base": "",
    "temperature": 0.6,
    "vad_threshold": 0.7,
    "language": "en-US",
    "maxCallTime": 0,
    "tools": [],
    "dispositions": [],
    "afterCallWebhookUrl": null,
    "timezone": "America/Los_Angeles",
    "firstActionToolId": null,
    "callData": {},
    "waitingSound": "",
    "voicemailMessage": "",
    "allowInterruptions": "yes",
    "turnDetectionSensitivity": 0.7,
    "voiceSelectionMode": "cycling"
  }
}
```

## Example request

```bash
curl -X POST 'https://dashboard.vinsi.ai/api/agents' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"New Agent","voiceId":"","welcomeMessage":"Thank you for calling. How can I help you today?","instructions":"Test","knowledge_base":"","temperature":0.6,"vad_threshold":0.7,"language":"en-US","maxTokens":250,"isActive":true,"tools":[],"dispositions":[],"afterCallWebhookUrl":null,"timezone":"America/Los_Angeles","firstActionToolId":null,"callData":{},"waitingSound":"","allowInterruptions":"yes","turnDetectionSensitivity":0.7,"voiceSelectionMode":"cycling","outbound":{"voiceId":"","welcomeMessage":"Hi, this is Acme Dental calling about your appointment.","instructions":"Confirm the appointment date and time.","knowledge_base":"","temperature":0.6,"vad_threshold":0.7,"language":"en-US","maxCallTime":0,"tools":[],"dispositions":[],"afterCallWebhookUrl":null,"timezone":"America/Los_Angeles","firstActionToolId":null,"callData":{},"waitingSound":"","voicemailMessage":"","allowInterruptions":"yes","turnDetectionSensitivity":0.7,"voiceSelectionMode":"cycling"}}'
```

## Example response

```json
{
  "id": "cmkoak2s90002l704zm7pkxbh",
  "userId": "cmg5ipqwt0000jp04a21yzv8b",
  "name": "New Agent",
  "welcomeMessage": "Thank you for calling. How can I help you today?",
  "instructions": "",
  "voiceId": "",
  "isActive": true,
  "createdAt": "2026-01-21T17:22:57.945Z",
  "updatedAt": "2026-01-21T17:22:58.290Z",
  "temperature": 0.6,
  "maxTokens": 250,
  "language": "en-US",
  "organizationId": "cmg5ipsl00001jp04ujljuq2w",
  "vad_threshold": 0.7,
  "knowledge_base": "",
  "dispositions": [],
  "timezone": "America/Los_Angeles",
  "afterCallWebhookUrl": null,
  "outbound_id": "cmkoak2ut0004l70405u76dw8",
  "mode": "prompt",
  "workflowDefinition": null,
  "firstActionToolId": null,
  "callData": {},
  "waitingSound": "",
  "currentHistoryId": 1548,
  "integrations": null,
  "voicemailMessage": "",
  "allowInterruptions": "",
  "turnDetectionSensitivity": 0.7,
  "turnDetectionSettings": {
    "minEndpointingDelay": 0.5,
    "maxEndpointingDelay": 3,
    "minInterruptionDuration": 0.35,
    "minInterruptionWords": 1,
    "userAwayTimeout": 15,
    "preemptiveGeneration": true,
    "agentFalseInterruptionTimeout": 4,
    "vadMode": "fast"
  },
  "voiceIds": [
    "uYXf8XasLslADfZ2MB4u"
  ],
  "voiceSelectionMode": "cycling",
  "outbound": {
    "id": "cmkoak2ut0004l70405u76dw8",
    "userId": "cmg5ipqwt0000jp04a21yzv8b",
    "name": "New Agent",
    "welcomeMessage": "Thank you for calling. How can I help you today?",
    "instructions": "",
    "aimodel": "gpt-4o",
    "voiceId": null,
    "isActive": true,
    "createdAt": "2026-01-21T17:22:58.037Z",
    "updatedAt": "2026-01-21T17:22:58.400Z",
    "temperature": 0.6,
    "maxTokens": null,
    "language": "en-US",
    "organizationId": "cmg5ipsl00001jp04ujljuq2w",
    "vad_threshold": 0.7,
    "knowledge_base": "",
    "dispositions": [],
    "timezone": "America/Los_Angeles",
    "afterCallWebhookUrl": null,
    "outbound_id": null,
    "mode": "prompt",
    "workflowDefinition": null,
    "firstActionToolId": null,
    "callData": {},
    "waitingSound": "",
    "currentHistoryId": 1547,
    "integrations": null,
    "voicemailMessage": "",
    "allowInterruptions": "yes",
    "turnDetectionSensitivity": 0.7,
    "turnDetectionSettings": {
      "minEndpointingDelay": 0.5,
      "maxEndpointingDelay": 3,
      "minInterruptionDuration": 0.35,
      "minInterruptionWords": 1,
      "userAwayTimeout": 15,
      "preemptiveGeneration": true,
      "agentFalseInterruptionTimeout": 4,
      "vadMode": "fast"
    },
    "voiceIds": [
      "uYXf8XasLslADfZ2MB4u"
    ],
    "voiceSelectionMode": "cycling",
    "tools": []
  },
  "tools": []
}
```