# Retrain an existing chatbot

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

Canonical: https://www.chat-data.com/api-reference/retrain-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

The Chatbot Retrain API enables you to retrain an existing chatbot. This API is applicable for chatbots with the `custom-data-upload` model. It allows you to update the chatbot's knowledge base with new information or remove existing data.

You can provide new training data through various methods:
- Text data via `sourceText`
- URLs to scrape via `urlsToScrape`
- Product information via `products`
- Q&A pairs via `qAndAs`

You can also remove specific knowledge chunks using the `deletes` array.

Note: The amount of new data you can add is subject to character limits based on your plan.

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| chatbotId | string | yes | The unique identifier allocated to the chatbot. |
| sourceText | string | no | Text data intended for chatbot training, subject to character limits based on your plan. A chatbot has one text source: this value replaces the current text. Send an empty string to remove the text; omit the field to keep the current text. |
| urlsToScrape | array of string | no | A list of URLs provided for text content extraction. The web crawling process concludes once the list of URLs is fully processed or the chatbot's character limit is reached. URLs must begin with 'http://' or 'https://'. Applicable only to chatbots using the `custom-data-upload` model. A website that already exists with the same URL is recrawled to get the latest content. |
| options | object | no | Configuration options that control how websites are scraped from the URLs provided in the `urlsToScrape` parameter. These options affect the content extraction process for each URL being crawled. |
| options.Cookies | string | no | A list of cookies separated by semicolons that authorizes the scraping process, so that content can be accessed as if logged in. For example: "cookie1=value1; cookie2=value2; cookie3=value3". |
| options.extractMainContent | boolean | no | When enabled, automatically removes common non-content elements such as the header, footer, nav, navbar, menu, sidebar and advertisements from the webpage, without needing to specify exclude tags. |
| options.includeOnlyTags | string | no | A comma-separated list of CSS selectors representing DOM elements to exclusively extract from the webpage. For example, "div.site-content" extracts only the content of that div. |
| options.excludeTags | string | no | A comma-separated list of CSS selectors representing DOM elements to exclude from the scraping result. For example, "div#sidebar" excludes the div element with the id "sidebar". |
| 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, and a pair identical to an existing one is not added twice. |
| qAndAs[].question | string | yes | The question on a specific topic. |
| qAndAs[].answer | string | yes | The answer to the question. |
| qAndAs[].folder | string | no | The Q&A folder to put the pair in. If omitted, the pair takes the folder shared by all existing pairs with the same question and answer or, failing that, with the same question; otherwise it goes to the standard folder. |
| deletes | array of object | no | A list of knowledge sources to remove from the chatbot's knowledge base. To remove the plain text source, send `sourceText` as an empty string instead. |
| deletes[].type | string | yes | The type of the knowledge chunk to delete. One of: `website`, `q&a`, `product`, `file`. |
| deletes[].url | string | no | One of the alternatives. The URL to delete if the type is `website`. |
| deletes[].id | string | no | One of the alternatives. The product ID to delete if the type is `product`. |
| deletes[].question | string | no | One of the alternatives. The question to delete if the type is `q&a`. Every Q&A with this exact question is removed. |
| deletes[].name | string | no | One of the alternatives. The file name to delete if the type is `file`. |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/retrain-chatbot' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "chatbotId": "6650f1c2a9e4b83d2c7a1f05"
}'
```

## 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 new data was accepted. Training runs in the background; poll `GET /chatbot/status/{chatbotId}` for progress. |
| 400 | The chatbot could not be retrained. For example: `chatbotId` is missing, a URL in `urlsToScrape` has no `http://` or `https://` scheme, `products` or `deletes` is not an array, the chatbot does not use the `custom-data-upload` model, the training data exceeds the chatbot's character limit, or the workspace has no training characters left. |
| 401 | Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which. |
| 403 | The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace. |
| 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. |