# Create and train a chatbot

`POST https://api.chat-data.com/api/v2/create-chatbot`

Canonical: https://www.chat-data.com/api-reference/create-chatbot

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

Create a chatbot using one of our medical chat models, your own uploaded data, or a custom model. `model` is required; a request without a valid `model` is rejected with a 400.

Available models:
- `custom-data-upload`: For training with your own data using OpenAI GPT models including `GPT 5.6 Sol`, `GPT 5.6 Terra`, and `GPT 5.6 Luna`; Anthropic Claude models including `Claude Opus 5` and `Claude Sonnet 5`; Google Gemini models including `Gemini 3.7 Flash` and `Gemini 3.5 Flash Lite`; plus earlier supported models.
- `medical-chat-human`: For human medical questions
- `medical-chat-vet`: For veterinary medical questions
- `custom-model`: For using a custom model

For the `custom-data-upload` model, you can provide training data using `sourceText`, `urlsToScrape`, `products` or `qAndAs`. Other models do not use these fields, but `urlsToScrape` must still contain valid URLs and `products` must still be an array.

For the `custom-model` model, `customBackend` is required and `bearer` is optional. Chat Data sends a test request to the backend first and creates the chatbot only if the backend answers as expected.

You can poll the status of the training with `GET /chatbot/status/{chatbotId}` at an interval of 10 seconds. Training generally takes 1-2 minutes, depending on the length of the provided text or websites.

Note: The training data is subject to character limits based on your plan.

This operation requires a workspace API key; chatbot-scoped keys get a 403.

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| chatbotName | string | no | The name of the chatbot to be created. Defaults to an empty name. |
| sourceText | string | no | Text data for the chatbot, subject to character limits based on your plan. Relevant only if the model is `custom-data-upload`. |
| urlsToScrape | array of string | no | A list of URLs from which Chat Data extracts text content. Because the amount of text on a website cannot be known in advance, crawling stops when either the list of URLs is exhausted or the chatbot's character limit is reached. URLs must start with `http://` or `https://`, for example `https://www.chat-data.com`. Relevant only if the model is `custom-data-upload`. |
| products | array of object | no | A list of products for training the chatbot. |
| products[].id | string | yes | Unique ID for tracking the product in the knowledge base. Existing products with the same ID will be overwritten. |
| products[].information | object | yes | Structured data of the product in a key-value format. Optimal performance is achieved with one or two levels of depth. |
| qAndAs | array of object | no | A list of Q&As for the chatbot to learn specific topic answers. Items without both a question and an answer are skipped. |
| qAndAs[].question | string | yes | The question on a specific topic. |
| qAndAs[].answer | string | yes | The answer to the question. |
| customBackend | string | no | The URL of your own backend, starting with `http://` or `https://`. Required when `model` is `custom-model`; ignored for other models. |
| bearer | string | no | The bearer token sent to your custom backend. Only used when `model` is `custom-model`. |
| model | string | yes | The model the chatbot uses: - For training with your own data: `custom-data-upload` - For human medical questions: `medical-chat-human` - For veterinary medical questions: `medical-chat-vet` - For a custom model: `custom-model` There is no default; a missing or unknown value is rejected with a 400. For the medical models and the custom model, `sourceText`, `urlsToScrape`, `products` and `qAndAs` are not used, though `urlsToScrape` must still contain valid URLs and `products` must still be an array. |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/create-chatbot' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "custom-data-upload"
}'
```

## Example response (200)

```json
{
  "chatbotId": "6650f1c2a9e4b83d2c7a1f05",
  "consumedCharacters": 156,
  "remainingCharacters": 999844,
  "dataSources": [
    {
      "characters": 156,
      "type": "text"
    },
    {
      "name": "https://www.example.com/help/shipping",
      "characters": 0,
      "type": "website"
    }
  ],
  "status": "success"
}
```

## Responses

| Status | Description |
| --- | --- |
| 200 | The chatbot was created. Training on the provided data runs in the background; poll `GET /chatbot/status/{chatbotId}` for progress. |
| 400 | The chatbot could not be created. For example: the workspace has reached its chatbot limit, has no training characters left, `model` is missing or not one of the allowed values, a URL in `urlsToScrape` has no `http://` or `https://` scheme, `products` is not an array, the training data exceeds the per-chatbot character limit, or for `custom-model` the `customBackend` URL is missing or the backend did not respond as expected. |
| 401 | Authentication failed (the `Authorization` header is missing or malformed, the API key does not exist, its workspace is unavailable or has no owner, or the plan does not include API access), or `model` is `custom-model` and the plan does not include custom models (`Custom model is unavailable in the current plan.`). |
| 403 | The request used a chatbot-scoped API key. This operation needs a workspace key. |
| 429 | The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying. |