← Back to DocuDroid View App Info

API Documentation

Complete guide to integrating with the DocuDroid API for document analysis and intelligent chat interactions.

🔐 Authentication

Currently, the API operates without authentication for demo purposes. In a production environment, implement appropriate authentication mechanisms such as API keys or OAuth2.

Security Note: When deploying to production, ensure proper authentication is implemented to secure your API endpoints.

📋 Workflow Guide

1. Initialize a Session

  • Start by calling /session/init to get a thread_id
  • This thread_id is required for all subsequent interactions

2. Choose Your Interaction Mode

  • General Chat: Start chatting immediately using /chat with mode: "general"
  • PDF Analysis:
    1. Upload PDF using /upload/pdf
    2. Check processing status via /status/{process_id}
    3. Start chatting with /chat using mode: "pdf"
  • Web Content Analysis:
    1. Submit URLs via /upload/web
    2. Start chatting with /chat using mode: "web"

💬 Chat Modes

DocuDroid supports three distinct chat modes, each designed for specific use cases:

General Mode

Standard conversation mode without document context.

  • Default mode if none specified
  • Suitable for general queries and system information
  • No prior content upload required

PDF Mode

Enables conversation about uploaded PDF documents.

  • Requires prior PDF upload
  • Supports document analysis and specific queries
  • Maintains context across conversations

Web Mode

Facilitates discussion about processed web content.

  • Requires prior URL submission
  • Analyzes web page content
  • Suitable for web research and content analysis

🔄 Session Management

Each interaction is managed through a session identified by a unique thread_id.

Important: The thread_id maintains conversation context and must be included in all requests after initialization.

📡 API Endpoints

POST
/session/init

Initialize Chat Session

Creates a new chat session and returns a thread ID for subsequent requests.

Curl Example:

curl -X POST http://localhost:8000/session/init \
    -H "Content-Type: application/json"

Success Response:

{
    "thread_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "Welcome! You can:\n1. Chat generally\n2. Upload PDFs for analysis\n3. Share URLs for web content analysis"
}
POST
/chat

Send Chat Message

Send a message and receive an AI response based on the selected mode.

Parameter Type Description
messagerequired string The user's message or question
thread_idrequired string Session identifier from /session/init
modeoptional string Chat mode: "general" (default), "pdf", or "web"
Mode Requirements:
  • "pdf" mode requires prior PDF upload
  • "web" mode requires prior URL submission

Curl Example:

curl -X POST http://localhost:8000/chat \
    -H "Content-Type: application/json" \
    -d '{
        "message": "Tell me about your capabilities",
        "thread_id": "550e8400-e29b-41d4-a716-446655440000",
        "mode": "general"
    }'

Success Response:

{
    "response": "I am DocuDroid, an intelligent document assistant. I can help you with general conversations, analyze PDF documents after they're uploaded via the /upload/pdf endpoint, and process web content that's been shared through the /upload/web endpoint."
}

Error Response:

{
    "detail": "No PDF content has been loaded yet. Please upload a PDF first."
}
POST
/upload/pdf

Upload PDF Document

Upload a PDF file for analysis. Uses multipart/form-data format.

Parameter Type Description
filerequired file PDF file to upload (max size: 10MB)
thread_idrequired string Session identifier

Curl Example:

curl -X POST http://localhost:8000/upload/pdf \
    -H "Content-Type: multipart/form-data" \
    -F "file=@document.pdf" \
    -F "thread_id=550e8400-e29b-41d4-a716-446655440000"

Success Response:

{
    "status": "processing",
    "message": "📄 Processing PDF: document.pdf...",
    "filename": "document.pdf",
    "process_id": "proc-550e8400-e29b-41d4-a716-446655440000"
}
POST
/upload/web

Add Web Content

Process content from provided URLs for analysis.

Parameter Type Description
thread_idrequired string Session identifier
urlsrequired array Array of URLs to process

Curl Example:

curl -X POST http://localhost:8000/upload/web \
    -H "Content-Type: application/json" \
    -d '{
        "thread_id": "550e8400-e29b-41d4-a716-446655440000",
        "urls": [
            "https://example.com/article1",
            "https://example.com/article2"
        ]
    }'

Success Response:

{
    "status": "success",
    "message": "🌐 Successfully added web content. You can now ask questions about it."
}
GET
/status/{process_id}

Check Processing Status

Check the status of a PDF processing task.

Curl Example:

curl -X GET http://localhost:8000/status/proc-550e8400-e29b-41d4-a716-446655440000

Success Response:

{
    "status": "completed",
    "message": "✅ Successfully processed document.pdf. You can now ask questions about its content."
}

⚡ Best Practices

⚠️ Error Handling

The API uses standard HTTP status codes and provides detailed error messages:

Status Code Description Common Scenarios
200 Success Request processed successfully
400 Bad Request Missing parameters, invalid file type
404 Not Found Invalid process_id, resource not found
413 Payload Too Large PDF file exceeds size limit
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Processing error, server issues

Error Response Format:

{
    "detail": "Detailed error message explaining what went wrong"
}

🔄 Rate Limiting

Note: The demo version does not implement rate limiting. Production deployments should implement appropriate rate limiting based on your requirements.

Recommended limits for production:

Rate limit headers will be included in responses:

X-RateLimit-Limit: [requests_per_window]
X-RateLimit-Remaining: [requests_remaining]
X-RateLimit-Reset: [reset_timestamp]