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:

{
  "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:

{
  "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:

{
  "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:

{
  "travel_style": "luxury",
  "preferred_destinations": ["Paris", "Tokyo", "New York"],
  "budget_range": {
    "min": 2000,
    "max": 10000
  }
}

Response:

{
  "message": "Preferences updated successfully"
}

Health Check

GET /health

Check the health status of the API and its components.

Response:

{
  "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:

{
  "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

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

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