Skip to content

CHAT_API_DOCUMENTATION.md

Latest commit

 

History

History
459 lines (349 loc) · 8.61 KB

CHAT_API_DOCUMENTATION.md

File metadata and controls

459 lines (349 loc) · 8.61 KB
Raw

Chat API Documentation

This document provides comprehensive information about the Chat API endpoints, including request/response schemas, authentication requirements, and usage examples.

Base URL

http://localhost:8000

Authentication

All endpoints require authentication. Include the JWT token in the Authorization header:

Authorization: Bearer <your_jwt_token>

Endpoints

1. Send Chat Message

Endpoint: POST /chat

Description: Send a chat message and get a response from the AI agent.

Request Body:

{
    "message": "Hello, how are you?",
    "conversation_id": 1,
    "model": "openai:gpt-4o"
}

Response:

{
    "id": 1,
    "message": "Hello! I'm doing well, thank you for asking. How can I help you today?",
    "conversation_id": 1,
    "user_id": 1,
    "is_ai": true,
    "created_at": "2024-01-15T10:30:00Z",
    "token_usage": {
        "id": 1,
        "message_id": 1,
        "provider": "openai",
        "model": "gpt-4o",
        "input_tokens": 10,
        "output_tokens": 25,
        "total_tokens": 35,
        "cost_usd": 0.0015,
        "created_at": "2024-01-15T10:30:00Z"
    }
}

cURL Example:

curl -X POST "http://localhost:8000/chat" \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, how are you?",
    "conversation_id": 1,
    "model": "openai:gpt-4o"
  }'

Python Example:

import requests

url = "http://localhost:8000/chat"
headers = {
    "Authorization": "Bearer <your_jwt_token>",
    "Content-Type": "application/json"
}
data = {
    "message": "Hello, how are you?",
    "conversation_id": 1,
    "model": "openai:gpt-4o"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

2. Get All Conversations

Endpoint: GET /conversations

Description: Retrieve all conversations for the authenticated user.

Response:

[
    {
        "id": 1,
        "title": "General Chat",
        "user_id": 1,
        "created_at": "2024-01-15T10:00:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "messages": [
            {
                "id": 1,
                "message": "Hello, how are you?",
                "conversation_id": 1,
                "user_id": 1,
                "is_ai": false,
                "created_at": "2024-01-15T10:00:00Z"
            },
            {
                "id": 2,
                "message": "Hello! I'm doing well, thank you for asking. How can I help you today?",
                "conversation_id": 1,
                "user_id": 1,
                "is_ai": true,
                "created_at": "2024-01-15T10:30:00Z"
            }
        ]
    }
]

cURL Example:

curl -X GET "http://localhost:8000/conversations" \
  -H "Authorization: Bearer <your_jwt_token>"

Python Example:

import requests

url = "http://localhost:8000/conversations"
headers = {
    "Authorization": "Bearer <your_jwt_token>"
}

response = requests.get(url, headers=headers)
conversations = response.json()
print(conversations)

3. Get Specific Conversation

Endpoint: GET /conversations/{conversation_id}

Description: Retrieve a specific conversation by ID.

Path Parameters:

  • conversation_id (integer): The ID of the conversation to retrieve

Response:

{
    "id": 1,
    "title": "General Chat",
    "user_id": 1,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "messages": [
        {
            "id": 1,
            "message": "Hello, how are you?",
            "conversation_id": 1,
            "user_id": 1,
            "is_ai": false,
            "created_at": "2024-01-15T10:00:00Z"
        },
        {
            "id": 2,
            "message": "Hello! I'm doing well, thank you for asking. How can I help you today?",
            "conversation_id": 1,
            "user_id": 1,
            "is_ai": true,
            "created_at": "2024-01-15T10:30:00Z"
        }
    ]
}

cURL Example:

curl -X GET "http://localhost:8000/conversations/1" \
  -H "Authorization: Bearer <your_jwt_token>"

Python Example:

import requests

conversation_id = 1
url = f"http://localhost:8000/conversations/{conversation_id}"
headers = {
    "Authorization": "Bearer <your_jwt_token>"
}

response = requests.get(url, headers=headers)
conversation = response.json()
print(conversation)

4. Create New Conversation

Endpoint: POST /conversations

Description: Create a new conversation.

Request Body:

{
    "title": "New Chat Session"
}

Response:

{
    "id": 2,
    "title": "New Chat Session",
    "user_id": 1,
    "created_at": "2024-01-15T11:00:00Z",
    "updated_at": "2024-01-15T11:00:00Z",
    "messages": []
}

cURL Example:

curl -X POST "http://localhost:8000/conversations" \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Chat Session"
  }'

Python Example:

import requests

url = "http://localhost:8000/conversations"
headers = {
    "Authorization": "Bearer <your_jwt_token>",
    "Content-Type": "application/json"
}
data = {
    "title": "New Chat Session"
}

response = requests.post(url, headers=headers, json=data)
new_conversation = response.json()
print(new_conversation)

5. Delete Conversation

Endpoint: DELETE /conversations/{conversation_id}

Description: Delete a specific conversation.

Path Parameters:

  • conversation_id (integer): The ID of the conversation to delete

Response:

{
    "message": "Conversation deleted successfully"
}

cURL Example:

curl -X DELETE "http://localhost:8000/conversations/1" \
  -H "Authorization: Bearer <your_jwt_token>"

Python Example:

import requests

conversation_id = 1
url = f"http://localhost:8000/conversations/{conversation_id}"
headers = {
    "Authorization": "Bearer <your_jwt_token>"
}

response = requests.delete(url, headers=headers)
result = response.json()
print(result)

Data Models

ChatRequest

class ChatRequest(BaseModel):
    message: str
    conversation_id: int
    model: str = "openai:gpt-4o"  # Default model

ChatResponse

class ChatResponse(BaseModel):
    id: int
    message: str
    conversation_id: int
    user_id: int
    is_ai: bool
    created_at: datetime
    token_usage: Optional[TokenUsage] = None

Conversation

class Conversation(BaseModel):
    id: int
    title: str
    user_id: int
    created_at: datetime
    updated_at: datetime
    messages: List[Message]

ConversationCreate

class ConversationCreate(BaseModel):
    title: str

Error Responses

401 Unauthorized

{
    "detail": "Not authenticated"
}

404 Not Found

{
    "detail": "Conversation not found"
}

500 Internal Server Error

{
    "detail": "Error processing chat message: <error_description>"
}

Available Models

The system supports multiple LLM providers. You can specify the model in the chat request:

  • openai:gpt-4o - OpenAI GPT-4 Omni (default)
  • openai:gpt-4-turbo - OpenAI GPT-4 Turbo
  • openai:gpt-3.5-turbo - OpenAI GPT-3.5 Turbo
  • anthropic:claude-3-opus - Anthropic Claude 3 Opus
  • anthropic:claude-3-sonnet - Anthropic Claude 3 Sonnet
  • google:gemini-pro - Google Gemini Pro

Usage Examples

Complete Chat Flow

  1. Create a new conversation:
curl -X POST "http://localhost:8000/conversations" \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "AI Assistant Chat"}'
  1. Send a message:
curl -X POST "http://localhost:8000/chat" \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the capital of France?",
    "conversation_id": 1,
    "model": "openai:gpt-4o"
  }'
  1. Get conversation history:
curl -X GET "http://localhost:8000/conversations/1" \
  -H "Authorization: Bearer <your_jwt_token>"
  1. Delete conversation when done:
curl -X DELETE "http://localhost:8000/conversations/1" \
  -H "Authorization: Bearer <your_jwt_token>"

Notes

  • All timestamps are in ISO 8601 format (UTC)
  • Token usage tracking is automatic for AI responses
  • Conversations are user-specific and cannot be accessed by other users
  • The system automatically handles conversation threading and message ordering
  • Model selection affects response quality and cost