The Tenant API provides comprehensive REST endpoints to integrate all dashboard functionality into your own systems. Manage bots, conversations, analytics, and knowledge base programmatically.
https://your-domain.com/api/v1
All requests and responses use JSON format:
Content-Type: application/json
All API requests require authentication using an API key. Include your API key in the request headers.
X-API-Key: tk_your_api_key_here
curl -X GET "https://your-domain.com/api/v1/tenant/info" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json"
Manage tenant information and usage statistics.
/tenant/info
Get tenant information
Retrieve basic information about your tenant account.
curl -X GET "https://your-domain.com/api/v1/tenant/info" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json"
{
"success": true,
"data": {
"id": "tenant-uuid",
"name": "Your Company",
"plan": "professional",
"is_active": true,
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-15T10:30:00Z"
}
}
/tenant/usage
Get usage statistics
Retrieve current usage statistics and plan limits.
curl -X GET "https://your-domain.com/api/v1/tenant/usage" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json"
{
"success": true,
"data": {
"usage": {
"bot_count": 5,
"conversation_count": 1250,
"message_count": 8500
},
"limits": {
"max_bots": 10,
"max_conversations_per_month": 5000,
"max_messages_per_month": 50000
},
"utilization": {
"bots": "5/10",
"conversations": "1250/5000",
"messages": "8500/50000"
}
}
}
Complete CRUD operations for managing your chatbots.
/bots
List all bots
Retrieve a paginated list of all bots for your tenant.
| Parameter | Type | Required | Description |
|---|---|---|---|
page |
integer | Optional | Page number (default: 1) |
per_page |
integer | Optional | Items per page (default: 20, max: 100) |
channel_type |
string | Optional | Filter by channel type (webchat, whatsapp, etc.) |
is_active |
boolean | Optional | Filter by active status |
curl -X GET "https://your-domain.com/api/v1/bots?page=1&per_page=10&channel_type=webchat" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json"
{
"success": true,
"data": [
{
"id": "bot-uuid-1",
"name": "Customer Support Bot",
"channel_type": "webchat",
"description": "Handles customer inquiries",
"welcome_message": "Hi! How can I help you today?",
"system_prompt": "You are a helpful customer service assistant.",
"is_active": true,
"is_default": false,
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-15T10:30:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 10,
"total": 5,
"pages": 1,
"has_prev": false,
"has_next": false
}
}
/bots/{bot_id}
Get specific bot
Retrieve detailed information about a specific bot.
| Parameter | Type | Required | Description |
|---|---|---|---|
bot_id |
string | Required | Unique identifier of the bot |
curl -X GET "https://your-domain.com/api/v1/bots/bot-uuid-1" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json"
{
"success": true,
"data": {
"id": "bot-uuid-1",
"name": "Customer Support Bot",
"channel_type": "webchat",
"description": "Handles customer inquiries",
"welcome_message": "Hi! How can I help you today?",
"system_prompt": "You are a helpful customer service assistant.",
"is_active": true,
"is_default": false,
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-15T10:30:00Z"
}
}
/bots
Create new bot
Create a new chatbot for your tenant.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Required | Name of the bot |
channel_type |
string | Required | Channel type (webchat, whatsapp, telegram, etc.) |
description |
string | Optional | Description of the bot's purpose |
welcome_message |
string | Optional | Initial message shown to users |
system_prompt |
string | Optional | AI system prompt for bot behavior |
is_active |
boolean | Optional | Whether the bot is active (default: true) |
language |
string | Optional | Primary language (en, es, fr, de, it, pt) (default: en) |
personality |
string | Optional | Bot personality (professional, friendly, helpful, expert, enthusiastic) |
bot_role |
string | Optional | Bot role (customer_support, sales, technical_support, general_assistant, lead_generation, appointment_booking) |
curl -X POST "https://your-domain.com/api/v1/bots" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Sales Assistant Bot",
"channel_type": "webchat",
"description": "Helps with sales inquiries and product information",
"welcome_message": "Hello! I'm here to help you with any sales questions.",
"system_prompt": "You are a knowledgeable sales assistant. Help customers with product information and guide them through the sales process.",
"is_active": true,
"language": "en",
"personality": "friendly",
"bot_role": "sales"
}'
{
"success": true,
"data": {
"id": "bot-uuid-new",
"name": "Sales Assistant Bot",
"channel_type": "webchat",
"description": "Helps with sales inquiries and product information",
"welcome_message": "Hello! I'm here to help you with any sales questions.",
"system_prompt": "You are a friendly sales assistant who helps customers find products...",
"is_active": true,
"language": "en",
"personality": "friendly",
"bot_role": "sales",
"message": "Bot created successfully"
}
}
/bots/{bot_id}
Update bot
Update an existing bot's configuration.
| Parameter | Type | Required | Description |
|---|---|---|---|
bot_id |
string | Required | Unique identifier of the bot to update |
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Optional | New name for the bot |
description |
string | Optional | New description |
welcome_message |
string | Optional | New welcome message |
system_prompt |
string | Optional | New system prompt |
is_active |
boolean | Optional | New active status |
language |
string | Optional | New primary language |
personality |
string | Optional | New bot personality |
bot_role |
string | Optional | New bot role |
curl -X PUT "https://your-domain.com/api/v1/bots/bot-uuid-1" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Customer Support Bot",
"welcome_message": "Hello! I'm your updated customer support assistant.",
"is_active": true
}'
{
"success": true,
"data": {
"id": "bot-uuid-1",
"name": "Updated Customer Support Bot",
"message": "Bot updated successfully"
}
}
/bots/{bot_id}
Delete bot
Permanently delete a bot and all associated data.
This action cannot be undone. All conversations, messages, and knowledge associated with this bot will be permanently deleted.
| Parameter | Type | Required | Description |
|---|---|---|---|
bot_id |
string | Required | Unique identifier of the bot to delete |
curl -X DELETE "https://your-domain.com/api/v1/bots/bot-uuid-1" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json"
{
"success": true,
"message": "Bot 'Customer Support Bot' deleted successfully"
}
Handle real-time conversations and message exchanges with your bots.
/conversations
List conversations
Retrieve a paginated list of conversations for your tenant's bots.
| Parameter | Type | Required | Description |
|---|---|---|---|
page |
integer | Optional | Page number (default: 1) |
per_page |
integer | Optional | Items per page (default: 20, max: 100) |
bot_id |
string | Optional | Filter by specific bot |
status |
string | Optional | Filter by status (active, ended, etc.) |
channel |
string | Optional | Filter by channel type |
curl -X GET "https://your-domain.com/api/v1/conversations?bot_id=bot-uuid-1&status=active" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json"
{
"success": true,
"data": [
{
"id": "conv-uuid-1",
"session_id": "session-123",
"bot_id": "bot-uuid-1",
"bot_name": "Customer Support Bot",
"user_identifier": "user@example.com",
"user_name": "John Doe",
"user_email": "user@example.com",
"channel": "webchat",
"status": "active",
"started_at": "2026-01-15T10:00:00Z",
"ended_at": null,
"created_at": "2026-01-15T10:00:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 1,
"pages": 1,
"has_prev": false,
"has_next": false
}
}
/conversations/{session_id}
Get conversation details
Retrieve detailed information about a specific conversation including all messages.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | Required | Unique session identifier |
curl -X GET "https://your-domain.com/api/v1/conversations/session-123" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json"
{
"success": true,
"data": {
"session": {
"id": "conv-uuid-1",
"session_id": "session-123",
"bot_id": "bot-uuid-1",
"bot_name": "Customer Support Bot",
"user_identifier": "user@example.com",
"user_name": "John Doe",
"user_email": "user@example.com",
"channel": "webchat",
"status": "active",
"started_at": "2026-01-15T10:00:00Z",
"ended_at": null,
"created_at": "2026-01-15T10:00:00Z"
},
"messages": [
{
"id": "msg-uuid-1",
"sender": "bot",
"message": "Hi! How can I help you today?",
"message_type": "text",
"created_at": "2026-01-15T10:00:00Z"
},
{
"id": "msg-uuid-2",
"sender": "user",
"message": "I need help with my order",
"message_type": "text",
"created_at": "2026-01-15T10:01:00Z"
},
{
"id": "msg-uuid-3",
"sender": "bot",
"message": "I'd be happy to help you with your order. Could you please provide your order number?",
"message_type": "text",
"created_at": "2026-01-15T10:01:30Z"
}
]
}
}
/conversations/{session_id}/messages
Send message
Send a message to a conversation and receive an AI-generated response.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | Required | Unique session identifier |
| Parameter | Type | Required | Description |
|---|---|---|---|
message |
string | Required | The message content to send |
curl -X POST "https://your-domain.com/api/v1/conversations/session-123/messages" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"message": "What are your business hours?"
}'
{
"success": true,
"data": {
"user_message": {
"id": "msg-uuid-4",
"message": "What are your business hours?",
"created_at": "2026-01-15T10:05:00Z"
},
"bot_response": {
"id": "msg-uuid-5",
"message": "Our business hours are Monday to Friday, 9 AM to 6 PM EST. We're also available on weekends from 10 AM to 4 PM. Is there anything specific I can help you with during these hours?",
"created_at": "2026-01-15T10:05:02Z"
}
}
}
Access comprehensive analytics and reporting data for your bots and conversations.
/analytics/overview
Get analytics overview
Retrieve high-level analytics overview for your tenant.
| Parameter | Type | Required | Description |
|---|---|---|---|
period |
integer | Optional | Number of days to analyze (default: 30) |
curl -X GET "https://your-domain.com/api/v1/analytics/overview?period=7" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json"
{
"success": true,
"data": {
"total_bots": 5,
"total_conversations": 1250,
"total_messages": 8500,
"active_conversations": 45,
"period_days": 7,
"bots": [
{
"id": "bot-uuid-1",
"name": "Customer Support Bot",
"channel_type": "webchat",
"is_active": true
}
]
}
}
/analytics/conversations
Get conversation analytics
Retrieve detailed conversation analytics with breakdowns by channel, status, and time.
| Parameter | Type | Required | Description |
|---|---|---|---|
period |
integer | Optional | Number of days to analyze (default: 30) |
bot_id |
string | Optional | Filter by specific bot |
curl -X GET "https://your-domain.com/api/v1/analytics/conversations?period=30&bot_id=bot-uuid-1" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json"
{
"success": true,
"data": {
"total_conversations": 1250,
"period_days": 30,
"breakdown": {
"by_channel": {
"webchat": 800,
"whatsapp": 300,
"telegram": 150
},
"by_status": {
"active": 45,
"ended": 1200,
"abandoned": 5
},
"by_day": {
"2026-01-01": 42,
"2026-01-02": 38,
"2026-01-03": 51
}
}
}
}
Manage knowledge sources and content for your bots' AI training.
/knowledge/sources
List knowledge sources
Retrieve a paginated list of knowledge sources for your tenant's bots.
| Parameter | Type | Required | Description |
|---|---|---|---|
page |
integer | Optional | Page number (default: 1) |
per_page |
integer | Optional | Items per page (default: 20, max: 100) |
bot_id |
string | Optional | Filter by specific bot |
source_type |
string | Optional | Filter by source type (file, url, text) |
curl -X GET "https://your-domain.com/api/v1/knowledge/sources?bot_id=bot-uuid-1" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json"
{
"success": true,
"data": [
{
"id": "knowledge-uuid-1",
"bot_id": "bot-uuid-1",
"bot_name": "Customer Support Bot",
"name": "Product FAQ",
"source_type": "file",
"content_preview": "Q: What is your return policy? A: We offer a 30-day return policy...",
"file_path": "/uploads/product-faq.pdf",
"created_at": "2026-01-01T00:00:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 1,
"pages": 1,
"has_prev": false,
"has_next": false
}
}
/knowledge/sources/{source_id}
Get knowledge source
Retrieve detailed information about a specific knowledge source including all chunks.
| Parameter | Type | Required | Description |
|---|---|---|---|
source_id |
string | Required | Unique identifier of the knowledge source |
curl -X GET "https://your-domain.com/api/v1/knowledge/sources/knowledge-uuid-1" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json"
{
"success": true,
"data": {
"source": {
"id": "knowledge-uuid-1",
"bot_id": "bot-uuid-1",
"bot_name": "Customer Support Bot",
"name": "Product FAQ",
"source_type": "file",
"content": "Q: What is your return policy? A: We offer a 30-day return policy for all products...",
"file_path": "/uploads/product-faq.pdf",
"created_at": "2026-01-01T00:00:00Z"
},
"chunks": [
{
"id": "chunk-uuid-1",
"content": "Q: What is your return policy? A: We offer a 30-day return policy for all products.",
"chunk_index": 0,
"created_at": "2026-01-01T00:00:00Z"
},
{
"id": "chunk-uuid-2",
"content": "Q: How do I track my order? A: You can track your order using the tracking number provided in your confirmation email.",
"chunk_index": 1,
"created_at": "2026-01-01T00:00:00Z"
}
]
}
}
/knowledge/sources
Create knowledge source
Create a new knowledge source for a bot.
| Parameter | Type | Required | Description |
|---|---|---|---|
bot_id |
string | Required | ID of the bot to add knowledge to |
name |
string | Required | Name of the knowledge source |
source_type |
string | Required | Type of source (file, url, text) |
content |
string | Optional | The knowledge content (required for text type) |
url |
string | Optional | Website URL to scrape (required for url type) |
file |
file | Optional | File upload (required for file type) |
include_subpages |
boolean | Optional | Include subpages when scraping (url type only) |
max_pages |
integer | Optional | Maximum pages to scrape (default: 5, max: 20) |
curl -X POST "https://your-domain.com/api/v1/knowledge/sources" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"bot_id": "bot-uuid-1",
"name": "Company Policies",
"source_type": "text",
"content": "Our company policies include: 1. Remote work is allowed up to 3 days per week. 2. All employees get 25 vacation days per year. 3. Health insurance is provided for all full-time employees."
}'
{
"success": true,
"data": {
"id": "knowledge-uuid-new",
"name": "Company Policies",
"message": "Knowledge source created successfully"
}
}
/knowledge/sources/{source_id}
Delete knowledge source
Permanently delete a knowledge source and all associated chunks.
| Parameter | Type | Required | Description |
|---|---|---|---|
source_id |
string | Required | Unique identifier of the knowledge source to delete |
curl -X DELETE "https://your-domain.com/api/v1/knowledge/sources/knowledge-uuid-1" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json"
{
"success": true,
"message": "Knowledge source deleted successfully"
}
/knowledge/upload
Upload knowledge file
Upload a file directly for knowledge base processing.
TXT, PDF, DOC, DOCX, MD, CSV (max 10MB)
| Parameter | Type | Required | Description |
|---|---|---|---|
bot_id |
string | Required | ID of the bot to add knowledge to |
file |
file | Required | The file to upload |
curl -X POST "https://your-domain.com/api/v1/knowledge/upload" \
-H "X-API-Key: tk_your_api_key_here" \
-F "bot_id=bot-uuid-1" \
-F "file=@/path/to/knowledge.pdf"
{
"success": true,
"data": {
"id": "knowledge-uuid-new",
"name": "knowledge.pdf",
"source_type": "file",
"status": "processing",
"file_size": 1048576,
"message": "File uploaded and processing started"
}
}
/knowledge/scrape
Scrape website for knowledge
Scrape a website or webpage for knowledge base content.
| Parameter | Type | Required | Description |
|---|---|---|---|
bot_id |
string | Required | ID of the bot to add knowledge to |
url |
string | Required | Website URL to scrape |
include_subpages |
boolean | Optional | Include subpages in scraping (default: false) |
max_pages |
integer | Optional | Maximum pages to scrape (default: 5, max: 20) |
curl -X POST "https://your-domain.com/api/v1/knowledge/scrape" \
-H "X-API-Key: tk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"bot_id": "bot-uuid-1",
"url": "https://example.com/help",
"include_subpages": true,
"max_pages": 10
}'
{
"success": true,
"data": {
"pages_scraped": 8,
"knowledge_chunks_created": 45,
"failed_urls": [],
"message": "Website scraped successfully"
}
}
Real-world examples of how to integrate the Tenant API into your applications.
Complete example of creating a bot and sending messages using JavaScript.
// Initialize API client
const API_BASE = 'https://your-domain.com/api/v1';
const API_KEY = 'tk_your_api_key_here';
const headers = {
'X-API-Key': API_KEY,
'Content-Type': 'application/json'
};
// Create a new bot
async function createBot() {
const response = await fetch(`${API_BASE}/bots`, {
method: 'POST',
headers: headers,
body: JSON.stringify({
name: 'Customer Service Bot',
channel_type: 'webchat',
description: 'Handles customer inquiries',
welcome_message: 'Hello! How can I assist you today?',
system_prompt: 'You are a helpful customer service representative.'
})
});
const result = await response.json();
if (result.success) {
console.log('Bot created:', result.data);
return result.data.id;
} else {
console.error('Error creating bot:', result.error);
}
}
// Send a message and get AI response
async function sendMessage(sessionId, message) {
const response = await fetch(`${API_BASE}/conversations/${sessionId}/messages`, {
method: 'POST',
headers: headers,
body: JSON.stringify({ message: message })
});
const result = await response.json();
if (result.success) {
console.log('User message:', result.data.user_message.message);
console.log('Bot response:', result.data.bot_response.message);
return result.data.bot_response.message;
} else {
console.error('Error sending message:', result.error);
}
}
// Get analytics overview
async function getAnalytics() {
const response = await fetch(`${API_BASE}/analytics/overview?period=7`, {
method: 'GET',
headers: headers
});
const result = await response.json();
if (result.success) {
console.log('Analytics:', result.data);
return result.data;
} else {
console.error('Error getting analytics:', result.error);
}
}
// Usage example
async function main() {
try {
// Create a bot
const botId = await createBot();
// Send a message
await sendMessage('session-123', 'What are your business hours?');
// Get analytics
await getAnalytics();
} catch (error) {
console.error('Error:', error);
}
}
main();
Python integration example using the requests library.
import requests
import json
class TenantAPIClient:
def __init__(self, base_url, api_key):
self.base_url = base_url
self.headers = {
'X-API-Key': api_key,
'Content-Type': 'application/json'
}
def create_bot(self, name, channel_type, description=None, welcome_message=None, system_prompt=None):
"""Create a new bot"""
data = {
'name': name,
'channel_type': channel_type
}
if description:
data['description'] = description
if welcome_message:
data['welcome_message'] = welcome_message
if system_prompt:
data['system_prompt'] = system_prompt
response = requests.post(
f'{self.base_url}/bots',
headers=self.headers,
json=data
)
return response.json()
def list_bots(self, page=1, per_page=20, channel_type=None, is_active=None):
"""List all bots"""
params = {'page': page, 'per_page': per_page}
if channel_type:
params['channel_type'] = channel_type
if is_active is not None:
params['is_active'] = is_active
response = requests.get(
f'{self.base_url}/bots',
headers=self.headers,
params=params
)
return response.json()
def send_message(self, session_id, message):
"""Send a message and get AI response"""
response = requests.post(
f'{self.base_url}/conversations/{session_id}/messages',
headers=self.headers,
json={'message': message}
)
return response.json()
def get_analytics(self, period=30):
"""Get analytics overview"""
response = requests.get(
f'{self.base_url}/analytics/overview',
headers=self.headers,
params={'period': period}
)
return response.json()
# Usage example
if __name__ == '__main__':
# Initialize client
client = TenantAPIClient(
base_url='https://your-domain.com/api/v1',
api_key='tk_your_api_key_here'
)
# Create a bot
bot_result = client.create_bot(
name='Support Bot',
channel_type='webchat',
description='Customer support assistant',
welcome_message='Hi! How can I help you?',
system_prompt='You are a helpful customer support agent.'
)
if bot_result['success']:
print(f"Bot created: {bot_result['data']['name']}")
bot_id = bot_result['data']['id']
else:
print(f"Error creating bot: {bot_result['error']}")
# List all bots
bots_result = client.list_bots()
if bots_result['success']:
print(f"Total bots: {len(bots_result['data'])}")
# Send a message
message_result = client.send_message('session-123', 'Hello, I need help')
if message_result['success']:
print(f"Bot response: {message_result['data']['bot_response']['message']}")
# Get analytics
analytics_result = client.get_analytics(period=7)
if analytics_result['success']:
analytics = analytics_result['data']
print(f"Total conversations: {analytics['total_conversations']}")
print(f"Total messages: {analytics['total_messages']}")
Understanding API error responses and how to handle them properly.
All API errors follow a consistent response format:
{
"success": false,
"error": "Error type or code",
"message": "Detailed error description"
}
| Status Code | Meaning | Description |
|---|---|---|
200 |
OK | Request successful |
201 |
Created | Resource created successfully |
400 |
Bad Request | Invalid request parameters or body |
401 |
Unauthorized | Invalid or missing API key |
403 |
Forbidden | Insufficient permissions or plan limits reached |
404 |
Not Found | Resource not found or doesn't belong to your tenant |
405 |
Method Not Allowed | HTTP method not supported for this endpoint |
500 |
Internal Server Error | Unexpected server error |
{
"success": false,
"error": "Invalid API key",
"message": "API key not found or tenant inactive"
}
{
"success": false,
"error": "Bot not found",
"message": "The requested bot does not exist or you don't have access"
}
{
"success": false,
"error": "Bot limit reached for current plan",
"message": "Upgrade your plan to create more bots"
}
{
"success": false,
"error": "Missing required field: name",
"message": "The 'name' field is required when creating a bot"
}