docs/API.md

# TravelMate AI Assistant API Documentation

## Overview

The TravelMate AI Assistant API provides a comprehensive set of endpoints for interacting with an AI-powered travel assistant. The API uses RAG (Retrieval-Augmented Generation) to provide accurate and contextually relevant travel information.

## Base URL

```
https://api.travelmate.ai/v1
```

## Authentication

All API endpoints require authentication using JWT (JSON Web Tokens). Include the token in the Authorization header:

```
Authorization: Bearer <your_token>
```

## Rate Limiting

The API implements rate limiting to ensure fair usage:
- 100 requests per hour per user
- Rate limit headers are included in responses:
  - `X-RateLimit-Limit`: Maximum requests per window
  - `X-RateLimit-Remaining`: Remaining requests in current window
  - `X-RateLimit-Reset`: Time until rate limit resets

## Endpoints

### Chat

#### POST /chat

Process a chat message and get AI-generated response.

**Request Body:**
```json
{
  "message": "What are the best places to visit in Paris?",
  "chat_history": [
    {
      "user": "Hello",
      "assistant": "Hi! How can I help you with your travel plans?"
    }
  ]
}
```

**Response:**
```json
{
  "answer": "Here are some must-visit places in Paris...",
  "sources": [
    {
      "title": "Paris Travel Guide",
      "url": "https://example.com/paris-guide",
      "relevance_score": 0.95
    }
  ],
  "suggested_questions": [
    "What's the best time to visit the Eiffel Tower?",
    "Are there any hidden gems in Paris?"
  ]
}
```

### User Profile

#### GET /profile

Get the current user's profile.

**Response:**
```json
{
  "user_id": "user_123",
  "preferences": {
    "travel_style": "balanced",
    "preferred_destinations": ["Paris", "Tokyo"],
    "dietary_restrictions": [],
    "accessibility_needs": [],
    "preferred_activities": ["sightseeing", "food"],
    "budget_range": {
      "min": 1000,
      "max": 5000
    },
    "preferred_accommodation": "hotel",
    "preferred_transportation": "flexible",
    "travel_frequency": "occasional",
    "preferred_seasons": ["spring", "fall"],
    "special_requirements": []
  }
}
```

#### PUT /profile/preferences

Update user preferences.

**Request Body:**
```json
{
  "travel_style": "luxury",
  "preferred_destinations": ["Paris", "Tokyo", "New York"],
  "budget_range": {
    "min": 2000,
    "max": 10000
  }
}
```

**Response:**
```json
{
  "message": "Preferences updated successfully"
}
```

### Health Check

#### GET /health

Check the health status of the API and its components.

**Response:**
```json
{
  "status": "healthy",
  "timestamp": "2024-02-20T12:00:00Z",
  "version": "1.0.0",
  "environment": "production",
  "components": {
    "rag_engine": "ok",
    "user_profile": "ok"
  }
}
```

## Error Handling

The API uses standard HTTP status codes and returns error responses in the following format:

```json
{
  "error": "Error type",
  "detail": "Detailed error message",
  "timestamp": "2024-02-20T12:00:00Z",
  "request_id": "req_123"
}
```

Common error codes:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 429: Too Many Requests
- 500: Internal Server Error
- 503: Service Unavailable

## Best Practices

1. **Error Handling**
   - Always check response status codes
   - Implement exponential backoff for retries
   - Handle rate limiting gracefully

2. **Performance**
   - Cache responses when appropriate
   - Minimize chat history size
   - Use compression for large requests

3. **Security**
   - Keep tokens secure
   - Use HTTPS for all requests
   - Validate all input data

4. **Rate Limiting**
   - Monitor rate limit headers
   - Implement request queuing
   - Handle 429 responses appropriately

## SDKs and Examples

### Python

```python
import requests

class TravelMateClient:
    def __init__(self, api_key, base_url="https://api.travelmate.ai/v1"):
        self.api_key = api_key
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        })

    def chat(self, message, chat_history=None):
        response = self.session.post(
            f"{self.base_url}/chat",
            json={
                "message": message,
                "chat_history": chat_history or []
            }
        )
        response.raise_for_status()
        return response.json()

    def get_profile(self):
        response = self.session.get(f"{self.base_url}/profile")
        response.raise_for_status()
        return response.json()

    def update_preferences(self, preferences):
        response = self.session.put(
            f"{self.base_url}/profile/preferences",
            json=preferences
        )
        response.raise_for_status()
        return response.json()
```

### JavaScript

```javascript
class TravelMateClient {
    constructor(apiKey, baseUrl = 'https://api.travelmate.ai/v1') {
        this.apiKey = apiKey;
        this.baseUrl = baseUrl;
    }

    async chat(message, chatHistory = []) {
        const response = await fetch(`${this.baseUrl}/chat`, {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${this.apiKey}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                message,
                chat_history: chatHistory
            })
        });
        
        if (!response.ok) {
            throw new Error(`API error: ${response.statusText}`);
        }
        
        return response.json();
    }

    async getProfile() {
        const response = await fetch(`${this.baseUrl}/profile`, {
            headers: {
                'Authorization': `Bearer ${this.apiKey}`
            }
        });
        
        if (!response.ok) {
            throw new Error(`API error: ${response.statusText}`);
        }
        
        return response.json();
    }

    async updatePreferences(preferences) {
        const response = await fetch(`${this.baseUrl}/profile/preferences`, {
            method: 'PUT',
            headers: {
                'Authorization': `Bearer ${this.apiKey}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(preferences)
        });
        
        if (!response.ok) {
            throw new Error(`API error: ${response.statusText}`);
        }
        
        return response.json();
    }
}
```

## Support

For API support, please contact:
- Email: [email protected]
- Documentation: https://docs.travelmate.ai
- Status Page: https://status.travelmate.ai