docs/API.md

API Documentation

This document provides a quick reference for the RAG Chat Application REST API endpoints.

Base URL

http://localhost:8000

Authentication

Most endpoints require a GROQ API key to be configured:

POST /set-api-key
Content-Type: application/json

{
  "api_key": "your_groq_api_key_here"
}

Core Endpoints

Document Processing

Upload Files

POST /upload-files
Content-Type: multipart/form-data

# Form data with file uploads
files: [file1.pdf, file2.txt, ...]

Response:

{
  "total_files": 5,
  "total_documents": 12,
  "total_chunks": 87,
  "file_types": ["pdf", "txt", "py"],
  "type_counts": {"pdf": 3, "txt": 1, "py": 1}
}

Process Directory

POST /process-directory
Content-Type: application/x-www-form-urlencoded

directory_path=/path/to/documents

Chat Interface

Send Chat Message

POST /chat
Content-Type: application/json

{
  "message": "What is the main topic of the documents?"
}

Response:

{
  "response": "Based on the documents, the main topics include...",
  "citations": [
    {
      "content": "relevant excerpt from document",
      "citation": "/path/to/source/file.pdf",
      "type": "pdf",
      "score": 0.85
    }
  ],
  "themes": {
    "key_themes": ["AI", "Machine Learning", "RAG"],
    "analysis": "The documents focus on AI and ML concepts..."
  },
  "timestamp": "2025-06-11T10:30:00.123456"
}

Data Management

Get Statistics

GET /stats

Response:

{
  "total_files": 10,
  "total_documents": 25,
  "total_chunks": 150,
  "file_types": ["pdf", "txt", "py", "md"],
  "type_counts": {"pdf": 5, "txt": 3, "py": 1, "md": 1},
  "processed_at": "2025-06-11 10:30:00"
}

Get Chat History

GET /chat-history

Response:

[
  {
    "user_message": "What is RAG?",
    "assistant_response": "RAG stands for Retrieval-Augmented Generation...",
    "timestamp": "2025-06-11T10:30:00.123456",
    "citations": [...]
  }
]

Clear Chat History

DELETE /clear-chat

Vector Store Management

Save Vector Store

POST /save-vector-store

Response:

{
  "message": "Vector store saved successfully"
}

Load Vector Store

POST /load-vector-store

Response:

{
  "message": "Vector store loaded successfully",
  "stats": {
    "total_files": 10,
    "total_documents": 25,
    "total_chunks": 150
  }
}

Frontend Serving

Main Application

GET /

Returns the HTML frontend application.

Error Responses

All endpoints return errors in this format:

{
  "detail": "Error description message"
}

Common HTTP status codes:

• 200 - Success
• 400 - Bad Request (invalid input)
• 422 - Validation Error
• 500 - Internal Server Error

Interactive Documentation

When the server is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Examples

Complete Workflow

# 1. Set API key
curl -X POST "http://localhost:8000/set-api-key" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your_groq_key"}'

# 2. Upload files
curl -X POST "http://localhost:8000/upload-files" \
  -F "files=@document1.pdf" \
  -F "files=@document2.txt"

# 3. Chat with documents
curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize the key points"}'

# 4. Get statistics
curl -X GET "http://localhost:8000/stats"

# 5. Save vector store
curl -X POST "http://localhost:8000/save-vector-store"

Python Client Example

import requests

base_url = "http://localhost:8000"

# Set API key
response = requests.post(f"{base_url}/set-api-key", 
                        json={"api_key": "your_groq_key"})

# Upload files
files = {'files': open('document.pdf', 'rb')}
response = requests.post(f"{base_url}/upload-files", files=files)

# Chat
response = requests.post(f"{base_url}/chat", 
                        json={"message": "What is this document about?"})
print(response.json())