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

# Create Client AI Agent

> Creates an AI agent in a client workspace

Available on agency plans. The API token must belong to the agency owner.

## Path Parameters

| Name         | Type   | Description                     |
| ------------ | ------ | ------------------------------- |
| client\_id\* | String | The ID of the client workspace. |

## Headers

| Name              | Type   | Description                                                                                                                             |
| ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| Accept\*          | String | application/json                                                                                                                        |
| Authorization\*   | String | Bearer {api_token}                                                                                                                      |
| Content-Type\*    | String | application/json                                                                                                                        |
| Idempotency-Key\* | String | A unique key for this request. Retrying with the same key and body returns the original response instead of creating a duplicate agent. |

## Body Parameters

| Name          | Type   | Description                                                                |
| ------------- | ------ | -------------------------------------------------------------------------- |
| name\*        | String | The AI agent name.                                                         |
| website\_url  | String | A website URL to crawl and train the agent on.                             |
| accent\_color | String | Accent color for the agent widget. A random gradient is used when omitted. |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.sitespeak.ai/v1/agency/clients/{client_id}/chatbots" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: billing-account-1001-agent-2" \
    -d '{
      "name": "Acme Sales Agent",
      "website_url": "https://acme.example"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.sitespeak.ai/v1/agency/clients/{client_id}/chatbots',
    {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json',
        'Idempotency-Key': 'billing-account-1001-agent-2'
      },
      body: JSON.stringify({
        name: 'Acme Sales Agent',
        website_url: 'https://acme.example'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

## Response

<Tabs>
  <Tab title="201 Created">
    ```json theme={null}
    {
      "chatbot": {
        "id": "9f2a1c44-7d31-4a09-b2f1-3f5f4f2f7f10",
        "name": "Acme Sales Agent",
        "enabled": true,
        "accent_color": "linear-gradient(135deg, #4f46e5, #6366f1)",
        "messages_remaining": 726,
        "created_at": "2026-07-22T19:40:00+00:00"
      }
    }
    ```
  </Tab>

  <Tab title="400 Missing Idempotency-Key">
    Returns when the `Idempotency-Key` header is missing.
  </Tab>

  <Tab title="403 Not an agency account">
    Returns when the API token does not belong to an agency account owner.
  </Tab>

  <Tab title="404 Not found">
    Returns when no client workspace with this ID exists in your agency.
  </Tab>

  <Tab title="409 Request in progress">
    Returns when a request with the same `Idempotency-Key` is still being processed. Retry shortly.
  </Tab>

  <Tab title="422 Validation error">
    Returns when the client's AI agent limit or your plan's agent limit is reached, a field is invalid, or the `Idempotency-Key` was already used with a different request body.
  </Tab>
</Tabs>