---
title: "Retrain an existing chatbot"
method: POST
path: "/retrain-chatbot"
tags: ["Chatbot Operations"]
---

# Retrain an existing chatbot

`POST /retrain-chatbot`

## Request

- Base URL: `https://api.chat-data.com/api/v2`
- URL: `https://api.chat-data.com/api/v2/retrain-chatbot`
- Auth: HTTP bearer

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

- RetrainChatbotReq
  - `chatbotId` string, required: The unique identifier allocated to the chatbot.
  - `sourceText` string: 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` string[]: 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: 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.
    - `Cookies` string: 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".
    - `extractMainContent` boolean: 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.
    - `includeOnlyTags` string: 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.
    - `excludeTags` string: 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` object[]: A list of products for training the chatbot.
    - `id` string, required: Unique ID for tracking the product in the knowledge base. Existing products with the same ID will be overwritten.
    - `information` object, required: Structured data of the product in a key-value format. Optimal performance is achieved with one or two levels of depth.
  - `qAndAs` object[]: 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.
    - `question` string, required: The question on a specific topic.
    - `answer` string, required: The answer to the question.
    - `folder` string: 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` union[]: 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.
    - union
      - object
        - `type` 'website' | 'q&a' | 'product' | 'file', required: The type of the knowledge chunk to delete.
        - `url` string, required: The URL to delete if the type is `website`.
      - object
        - `type` 'website' | 'q&a' | 'product' | 'file', required: The type of the knowledge chunk to delete.
        - `id` string, required: The product ID to delete if the type is `product`.
      - object
        - `type` 'website' | 'q&a' | 'product' | 'file', required: The type of the knowledge chunk to delete.
        - `question` string, required: The question to delete if the type is `q&a`. Every Q&A with this exact question is removed.
      - object
        - `type` 'website' | 'q&a' | 'product' | 'file', required: The type of the knowledge chunk to delete.
        - `name` string, required: The file name to delete if the type is `file`.

## Response `200`

The new data was accepted. Training runs in the background; poll `GET /chatbot/status/{chatbotId}` for progress.

- TrainChatbotSuccessRes
  - `chatbotId` string, required: The unique identifier allocated to the chatbot. Use this ID in API calls about this chatbot.
  - `consumedCharacters` number, required: The number of training characters charged by this call. Websites are not counted here; they are charged when they are crawled.
  - `remainingCharacters` number, required: The number of training characters that remain available in your account. As long as the balance is positive, even by a single character, a training run proceeds and is limited only by the per-chatbot training character limit.
  - `dataSources` ChatbotDataSource[], required: All data sources of the chatbot after this call. Newly added websites show 0 characters until they have been crawled. In the retrain-chatbot response, Q&A sources are listed with their `question`, `answer` and `folder` instead of a character count.
    - `name` string: The name of the document, the product ID or the URL of the website. Absent for plain text and Q&As.
    - `characters` number: The total number of characters in this data source.
    - `question` string: The question of a `q&a` source. Only in the retrain-chatbot response.
    - `answer` string: The answer of a `q&a` source. Only in the retrain-chatbot response.
    - `folder` string: The folder of a `q&a` source, when it has one. Only in the retrain-chatbot response.
    - `type` string, required: The type of the data source (for example `website`, `text`, `product` or `q&a`).
  - `status` 'success', required

## Other responses

- `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.

---

[API](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide.md) · [All operations](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/llms.txt) · [OpenAPI document](https://skmtc.dev/chat-data/apis/chat-data-api-schema-guide/revisions/72871007f7f0?raw)