> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nedzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create agent

> Create a new AI agent in a Nedzo workspace via the REST API. Configure the agent type, prompt, voice, language, model, actions, and knowledge base.

Create a new agent within a workspace.

<Tip>
  `workspaceId` is required for **account-scoped** API keys and inferred from the key for **workspace-scoped** keys. See [Workspace ID and Request Scope](/authentication#workspace-id-and-request-scope).
</Tip>

## Common Fields

<ParamField body="name" type="string" required>
  Agent name (1-255 characters)
</ParamField>

<ParamField body="agentType" type="string" required>
  Type of agent to create. Valid values: `Voice`, `Chat`, `Widget`
</ParamField>

<ParamField body="direction" type="string">
  Call direction for Voice agents: `inbound` or `outbound` (default: "inbound"). Ignored for Chat and Widget agents.
</ParamField>

<ParamField body="workspaceId" type="string">
  Workspace UUID (required for account API keys, optional for workspace API keys)
</ParamField>

<ParamField body="prompt" type="string">
  System prompt for the agent
</ParamField>

<ParamField body="language" type="string">
  Agent language. Valid values: `english`, `spanish`, `french`, `german`, `portuguese`, `dutch`, `chinese`, `japanese` (default: "english")
</ParamField>

<ParamField body="isActive" type="boolean">
  Whether the agent is active (default: true)
</ParamField>

## Type-Specific Fields

<Tabs>
  <Tab title="Voice">
    <ParamField body="openingLine" type="string">
      Opening line the agent says when starting a conversation
    </ParamField>

    <ParamField body="voiceId" type="string">
      Voice ID for text-to-speech
    </ParamField>

    <ParamField body="voicemail" type="boolean">
      Enable voicemail detection (default: false). Typically used with outbound direction.
    </ParamField>

    <ParamField body="voicemailMessage" type="string">
      Message to leave on voicemail
    </ParamField>

    <ParamField body="backgroundSound" type="boolean">
      Enable background sound (default: true)
    </ParamField>

    <ParamField body="hipaaCompliance" type="boolean">
      When this is enabled, no logs, recordings, or transcriptions will be stored (default: false)
    </ParamField>

    <ParamField body="callDuration" type="integer">
      Maximum call duration in minutes, 1-60 (default: 30)
    </ParamField>

    <ParamField body="speed" type="number">
      Voice speed multiplier, 0.5-1.5 (default: 1.0)
    </ParamField>

    <ParamField body="postConversationWebhookUrl" type="string">
      URL to receive a POST request after each conversation ends. The payload includes the transcript, summary, outcome, duration, contact details, and extracted fields. Set to `null` to disable. See the [Post-conversation webhook](/agents/post-conversation-webhook) page for the full payload.
    </ParamField>

    <ParamField body="postCallWebhookUrl" type="string" deprecated>
      **Deprecated.** Use `postConversationWebhookUrl` instead. Still accepted on input for backwards compatibility; responses always use the new field.
    </ParamField>
  </Tab>

  <Tab title="Chat">
    <ParamField body="postConversationWebhookUrl" type="string">
      URL to receive a POST request after each chat conversation ends (SMS, Instagram, Messenger, email, or web chat). The payload includes the transcript, summary, channel, contact details, and extracted fields. Set to `null` to disable. See the [Post-conversation webhook](/agents/post-conversation-webhook) page for the full payload.
    </ParamField>
  </Tab>

  <Tab title="Widget">
    <ParamField body="postConversationWebhookUrl" type="string">
      URL to receive a POST request after each web agent conversation ends. The payload includes the transcript, summary, outcome, duration, and extracted fields. Set to `null` to disable. See the [Post-conversation webhook](/agents/post-conversation-webhook) page for the full payload.
    </ParamField>
  </Tab>
</Tabs>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.nedzo.ai/v1/agents" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Customer Support Agent",
        "agentType": "Voice",
        "direction": "inbound",
        "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
        "prompt": "You are a helpful customer support assistant.",
        "openingLine": "Hello! How can I help you today?",
        "language": "english",
        "voiceId": "voice_123",
        "backgroundSound": true,
        "callDuration": 30,
        "postConversationWebhookUrl": "https://example.com/webhooks/conversation-completed"
      }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Customer Support Agent",
    "agentType": "Voice",
    "direction": "inbound",
    "prompt": "You are a helpful customer support assistant.",
    "isActive": true,
    "backgroundSound": true,
    "openingLine": "Hello! How can I help you today?",
    "language": "english",
    "voicemail": false,
    "voicemailMessage": null,
    "hipaaCompliance": false,
    "callDuration": 30,
    "speed": 1.0,
    "voiceId": "voice_123",
    "postConversationWebhookUrl": "https://example.com/webhooks/conversation-completed",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
  ```
</ResponseExample>