Developer Docs

API Reference

Integrate Xtell into your application. Create chatbots, add training data, and query your bot programmatically.

Authentication

All API requests require an API key. Generate one from your chatbot's settings page. Include it in the x-api-key header.

curl

curl https://xtell.io/api/chat/CHATBOT_ID \
  -H "Content-Type: application/json" \
  -H "x-api-key: sb_live_your_api_key" \
  -d '{"messages": [{"role": "user", "parts": [{"type": "text", "text": "Hello"}]}]}'

JavaScript

const response = await fetch("https://xtell.io/api/chat/CHATBOT_ID", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "sb_live_your_api_key",
  },
  body: JSON.stringify({
    messages: [
      { role: "user", parts: [{ type: "text", text: "Hello" }] }
    ],
  }),
});

Python

import requests

response = requests.post(
    "https://xtell.io/api/chat/CHATBOT_ID",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "sb_live_your_api_key",
    },
    json={
        "messages": [
            {"role": "user", "parts": [{"type": "text", "text": "Hello"}]}
        ]
    },
)

Chat with your bot

POST /api/chat/{chatbotId}

Send messages to your chatbot and receive streaming responses. The API uses the AI SDK UIMessage format.

Parameters

Name	Type	Required	Description
messages	UIMessage[]	Yes	Array of messages in the conversation. Each message has a role (user/assistant) and parts array.
visitorId	string	No	Optional visitor identifier for conversation tracking.
conversationId	string	No	Optional existing conversation ID to continue a thread.

curl

curl -X POST https://xtell.io/api/chat/CHATBOT_ID \
  -H "Content-Type: application/json" \
  -H "x-api-key: sb_live_your_api_key" \
  -d '{
    "messages": [
      {
        "role": "user",
        "parts": [{ "type": "text", "text": "What is your return policy?" }]
      }
    ],
    "visitorId": "visitor-123"
  }'

JavaScript

// Streaming response with fetch
const response = await fetch(
  "https://xtell.io/api/chat/CHATBOT_ID",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "sb_live_your_api_key",
    },
    body: JSON.stringify({
      messages: [
        {
          role: "user",
          parts: [{ type: "text", text: "What is your return policy?" }],
        },
      ],
      visitorId: "visitor-123",
    }),
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

Python

import requests

response = requests.post(
    "https://xtell.io/api/chat/CHATBOT_ID",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "sb_live_your_api_key",
    },
    json={
        "messages": [
            {
                "role": "user",
                "parts": [{"type": "text", "text": "What is your return policy?"}],
            }
        ],
        "visitorId": "visitor-123",
    },
    stream=True,
)

for chunk in response.iter_content(chunk_size=None):
    print(chunk.decode(), end="")

Add a data source

POST /api/data-sources

Train your chatbot by adding URLs or text content. The data will be automatically chunked and embedded for RAG retrieval.

Parameters

Name	Type	Required	Description
chatbotId	string	Yes	The chatbot to add the data source to.
type	"url" \| "document"	Yes	Either "url" to crawl a webpage or "document" to add text content.
url	string	No	Required when type is "url". The webpage URL to crawl.
name	string	No	Required when type is "document". A label for the content.
content	string	No	Required when type is "document". The text content to ingest.

curl (URL)

# Add a URL to crawl
curl -X POST https://xtell.io/api/data-sources \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "chatbotId": "CHATBOT_ID",
    "type": "url",
    "url": "https://example.com/docs"
  }'

curl (text)

# Add text content directly
curl -X POST https://xtell.io/api/data-sources \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "chatbotId": "CHATBOT_ID",
    "type": "document",
    "name": "FAQ",
    "content": "Q: What are your hours? A: We are open 9am-5pm."
  }'

JavaScript

// Add a URL data source
const response = await fetch("https://xtell.io/api/data-sources", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  credentials: "include",
  body: JSON.stringify({
    chatbotId: "CHATBOT_ID",
    type: "url",
    url: "https://example.com/docs",
  }),
});

const dataSource = await response.json();
console.log("Data source created:", dataSource.id);

Upload a file

POST /api/data-sources/upload

Upload a document file to train your chatbot. Supports PDF, TXT, CSV, and DOCX formats up to 10 MB.

Parameters

Name	Type	Required	Description
file	File	Yes	The document file. Accepted formats: PDF, TXT, CSV, DOCX. Max 10 MB.
chatbotId	string	Yes	The chatbot to associate this file with.

curl

curl -X POST https://xtell.io/api/data-sources/upload \
  -H "Cookie: your-session-cookie" \
  -F "chatbotId=CHATBOT_ID" \
  -F "file=@/path/to/document.pdf"

JavaScript

const formData = new FormData();
formData.append("chatbotId", "CHATBOT_ID");
formData.append("file", fileInput.files[0]);

const response = await fetch(
  "https://xtell.io/api/data-sources/upload",
  {
    method: "POST",
    credentials: "include",
    body: formData,
  }
);

const result = await response.json();
console.log("File uploaded:", result.id);

Python

import requests

with open("document.pdf", "rb") as f:
    response = requests.post(
        "https://xtell.io/api/data-sources/upload",
        files={"file": ("document.pdf", f, "application/pdf")},
        data={"chatbotId": "CHATBOT_ID"},
        cookies={"session": "your-session-cookie"},
    )

print("Uploaded:", response.json())