# 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 ``` ## 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: api-support@travelmate.ai - Documentation: https://docs.travelmate.ai - Status Page: https://status.travelmate.ai