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

# Create agent

> Create a new AI agent in your organization.

# Create agent

Creates a new AI agent. The agent is created as a draft (`is_published: false`) and with a Human Handoff action enabled.

```http theme={null}
POST https://app.chatnorris.ai/api/v2/chatbots
Authorization: Bearer <your_api_key>
Content-Type: application/json
```

**Required scope:** `chatbots:write`

***

## Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | ✅ | Agent name (1–100 characters) |
| `system_prompt` | string | — | System instructions for the agent |
| `locale` | string | — | Language of the default texts of the actions created with the agent (Human Handoff and, when applicable, Lead Form): `es` (default) or `en`. It isn't stored on the agent or returned in the response |
| `widget_config` | object | — | Widget visual settings |
| `widget_config.primaryColor` | string | — | Widget primary color (hex) |
| `widget_config.greeting` | string | — | Welcome message |
| `widget_config.leadCapture` | boolean | — | If `true`, the agent is also created with a Lead Form action enabled |

### Example

```json theme={null}
{
  "name": "Customer support",
  "system_prompt": "You are Acme Corp's virtual assistant. Reply in Spanish, with a friendly, concise tone.",
  "locale": "es",
  "widget_config": {
    "primaryColor": "#00ed64",
    "greeting": "Hi! How can I help you today?",
    "leadCapture": false
  }
}
```

***

## Response `201 Created`

```json theme={null}
{
  "status": "success",
  "data": {
    "id": "bot_xyz789",
    "name": "Customer support",
    "description": null,
    "system_prompt": "You are Acme Corp's virtual assistant...",
    "model": "claude-sonnet-4-6",
    "temperature": 0.7,
    "max_tokens": 1000,
    "is_active": true,
    "is_published": false,
    "widget_config": {
      "primaryColor": "#00ed64",
      "greeting": "Hi! How can I help you today?",
      "leadCapture": false
    },
    "created_at": "2026-06-30T18:00:00.000Z",
    "updated_at": "2026-06-30T18:00:00.000Z"
  }
}
```

***

## Common errors

| Code | Description |
| - | - |
| `INVALID_INPUT` | The `name` field is missing or exceeds 100 characters |
| `PLAN_LIMIT_REACHED` | The plan's agent limit was reached |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.