Skip to main content
POST
/
api
/
v1
/
chats
Create Chat
curl --request POST \
  --url https://api.example.com/api/v1/chats/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "user_id": "<string>",
  "title": "<string>",
  "metadata": {}
}
'
{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "user_id": "user123",
  "tenant_id": "tenant-uuid-here",
  "title": "Support Session",
  "config": {
    "metadata": {
      "department": "technical",
      "priority": "high"
    }
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "last_message_at": null
}

​
Create Chat

This endpoint creates a new chat session for a user. The chat session can then be used for real-time messaging via WebSocket connections.

​
Authentication

​
X-API-Key
string
required
Authentication header with your tenant’s API key

​
Request Body

​
user_id
string
required
The ID of the user creating the chat session
​
title
string
Optional custom title for the chat. If not provided, a title will be auto-generated.
​
metadata
object
Optional metadata object to store additional information about the chat

​
Response

​
id
string
Unique identifier for the chat session (UUID format)
​
user_id
string
The ID of the user who owns this chat
​
tenant_id
string
The tenant identifier (automatically determined from API key)
​
title
string
The title of the chat session
​
config
object
Configuration object containing metadata and other chat settings
​
created_at
string
Timestamp when the chat was created
​
updated_at
string
Timestamp when the chat was last updated
​
last_message_at
string | null
Timestamp of the last message in this chat (null for new chats)
{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "user_id": "user123",
  "tenant_id": "tenant-uuid-here",
  "title": "Support Session",
  "config": {
    "metadata": {
      "department": "technical",
      "priority": "high"
    }
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "last_message_at": null
}

​
Error Responses

Invalid request body or missing required fields
Invalid or missing API key
Server error processing the request

​
Example Usage

​
cURL

curl -X POST "http://localhost:8000/api/v1/chats/" \
  -H "X-API-Key: your-tenant-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user123",
    "title": "Support Session",
    "metadata": {
      "department": "technical",
      "priority": "high"
    }
  }'

​
JavaScript

fetch('http://localhost:8000/api/v1/chats/', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-tenant-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    user_id: 'user123',
    title: 'Support Session',
    metadata: {
      department: 'technical',
      priority: 'high'
    }
  })
})
.then(response => response.json())
.then(data => {
  console.log('Chat created:', data);
  const chatId = data.id;
  // Use chatId for WebSocket connection
})
.catch(error => console.error('Error:', error));

​
Python

import requests
import json

url = "http://localhost:8000/api/v1/chats/"
headers = {
    "X-API-Key": "your-tenant-api-key",
    "Content-Type": "application/json"
}
data = {
    "user_id": "user123",
    "title": "Support Session",
    "metadata": {
        "department": "technical",
        "priority": "high"
    }
}

response = requests.post(url, headers=headers, json=data)
chat_data = response.json()
print(f"Chat created with ID: {chat_data['id']}")

​
Notes

  • Only user_id is required in the request body
  • If title is not provided, the system will auto-generate one
  • The tenant_id is automatically determined from the API key
  • If the user doesn’t exist, a user entity will be auto-created
  • The chat ID returned should be used for subsequent WebSocket connections
  • Metadata can contain any custom key-value pairs for your application needs