Chatbot Operations

Create and train a chatbot

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.

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

Request body

chatbotNamestring

The name of the chatbot to be created. Defaults to an empty name.

sourceTextstring

Text data for the chatbot, subject to character limits based on your plan. Relevant only if the model is custom-data-upload.

urlsToScrapestring[]

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.

customBackendstring

The URL of your own backend, starting with http:// or https://. Required when model is custom-model; ignored for other models.

bearerstring

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.

Example request

{
  "chatbotName": "Support Bot",
  "sourceText": "Our support team is available Monday to Friday, 9am to 6pm EST. Outside these hours you can email support@example.com and we'll reply the next business day.",
  "urlsToScrape": [
    "https://www.example.com/help/shipping",
    "https://www.example.com/help/returns"
  ],
  "products": [
    {
      "id": "shopify_1234567",
      "information": {
        "id": "shopify_1234567",
        "name": "Fleece Drawstring Joggers",
        "color": "white"
      }
    }
  ],
  "qAndAs": [
    {
      "question": "Do you ship internationally?",
      "answer": "Yes, we ship to over 40 countries. International orders usually arrive within 7-14 business days."
    }
  ],
  "customBackend": "https://bot.example.com/v1/chat",
  "bearer": "cb_7d3f9a2e5c81b4f0",
  "model": "custom-data-upload"
}

Response

The chatbot was created. Training on the provided data runs in the background; poll GET /chatbot/status/{chatbotId} for progress.

chatbotIdstring required

The unique identifier allocated to the chatbot. Use this ID in API calls about this chatbot.

consumedCharactersnumber required

The number of training characters charged by this call. Websites are not counted here; they are charged when they are crawled.

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

status'success' required

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.