--- title: "Create and train a chatbot" method: POST path: "/create-chatbot" tags: ["Chatbot Operations"] --- # Create and train a chatbot `POST /create-chatbot` ## Request - Base URL: `https://api.chat-data.com/api/v2` - URL: `https://api.chat-data.com/api/v2/create-chatbot` - Auth: HTTP bearer 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 - CreatChatbotReq - `chatbotName` string: The name of the chatbot to be created. Defaults to an empty name. - `sourceText` string: Text data for the chatbot, subject to character limits based on your plan. Relevant only if the model is `custom-data-upload`. - `urlsToScrape` string[]: 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` 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. - `question` string, required: The question on a specific topic. - `answer` string, required: The answer to the question. - `customBackend` string: The URL of your own backend, starting with `http://` or `https://`. Required when `model` is `custom-model`; ignored for other models. - `bearer` string: The bearer token sent to your custom backend. Only used when `model` is `custom-model`. - `model` 'custom-data-upload' | 'medical-chat-human' | 'medical-chat-vet' | 'custom-model', required: 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. ## Response `200` The chatbot was created. Training on the provided data 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 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. --- [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)