API Usage Examples

Ready-to-use examples for all Docura AI endpoints using cURL, Python, and Postman.

Example API Usage Examples
A demo of the API Usage Examples component in action.

API Endpoints Overview

HackRx
Query & answers
Cache
Memory management
Health
Status monitoring

How to add

# Production API
BASE_URL="https://yourapi.example.com"

# Local Development
BASE_URL="http://localhost:8000"

How to use

# Quick Health Check
curl -X GET "https://yourapi.example.com/health"

# Quick Query Example
curl -X POST "https://yourapi.example.com/hackrx/run" \
  -H "Content-Type: application/json" \
  -d '{"documents": ["document.pdf"], "questions": ["What is this document about?"]}'

🧠 HackRx Query Processing

Single Document Query - cURL

# Query a single document
curl -X POST "https://yourapi.example.com/hackrx/run" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": ["document.pdf"],
    "questions": ["What is the main topic of this document?"],
    "search_strategy": "hybrid"
  }'

# Multiple questions on same document
curl -X POST "https://yourapi.example.com/hackrx/run" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": ["report.pdf"],
    "questions": [
      "What are the key findings?",
      "What recommendations are made?",
      "What is the conclusion?"
    ],
    "search_strategy": "semantic"
  }'

Multiple Documents Query - cURL

# Query multiple documents
curl -X POST "https://yourapi.example.com/hackrx/run" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": ["doc1.pdf", "doc2.docx", "presentation.pptx"],
    "questions": [
      "Compare the main findings across all documents",
      "What common themes appear in these documents?"
    ],
    "search_strategy": "hybrid"
  }'

Postman HackRx Query

1

Create New Request

• Method: POST
• URL: https://yourapi.example.com/hackrx/run
2

Headers

Content-Type: application/json
3

Body (raw JSON)

{
  "documents": ["document.pdf"],
  "questions": ["What is this document about?"],
  "search_strategy": "hybrid"
}

Advanced Postman Setup

1

Environment Variables

Create a new environment with:
baseUrl: https://yourapi.example.com
localUrl: http://localhost:8000
2

Multiple Questions Example

{
  "documents": ["doc1.pdf", "doc2.docx"],
  "questions": [
    "What are the main findings?",
    "What recommendations are made?",
    "Compare the two documents"
  ],
  "search_strategy": "semantic"
}
3

Tests Tab (Optional)

Add response validation:
pm.test("Status is 200", function () {
  pm.response.to.have.status(200);
});

💚 Health Check

Health Status - cURL

# Check API health
curl -X GET "https://yourapi.example.com/health"

# With verbose output
curl -X GET "https://yourapi.example.com/health" -v

# Save health status
curl -X GET "https://yourapi.example.com/health" -o health.json

Postman Health Check

1

Create Health Check Request

• Method: GET
• URL: https://yourapi.example.com/health
2

Expected Response

{
  "status": "healthy",
  "timestamp": 1691234567.89
}

Postman Health Monitoring

1

Collection Setup

Create a collection named "API Health Monitoring" with the health endpoint
2

Collection Runner

• Run → Iterations: 10
• Delay: 30000ms (30 seconds)
• Save responses for monitoring
3

Monitor Setup (Pro)

Use Postman Monitors to automatically check health every 5 minutes

🗄️ Cache Management

Cache Operations - cURL

# Get cache statistics
curl -X GET "https://yourapi.example.com/cache/stats"

# Clear all cache entries
curl -X POST "https://yourapi.example.com/cache/clear"

# Clear expired entries (no-op for this API)
curl -X POST "https://yourapi.example.com/cache/clear-expired"

Postman Cache Management

1

Cache Stats Request

• Method: GET
• URL: https://yourapi.example.com/cache/stats
2

Clear Cache Request

• Method: POST
• URL: https://yourapi.example.com/cache/clear
3

Collection Organization

Create a "Cache Management" folder with all cache endpoints for easy access

Postman Workspace Setup

Complete API Collection Structure:

📁 Docura AI API
  📁 HackRx Queries
    📄 Single Document Query
    📄 Multiple Documents Query
  📁 Health Monitoring
    📄 Health Check
  📁 Cache Management
    📄 Get Cache Stats
    📄 Clear Cache
    📄 Clear Expired Cache
Pro Tip: Save all requests in a collection and export for team sharing!

📄 Response Examples

✅ HackRx Query Success

{
  "answers": [
    "The document discusses machine learning applications in healthcare, focusing on diagnostic imaging and patient outcome prediction.",
    "Key findings include 95% accuracy in disease detection and 20% improvement in treatment effectiveness."
  ]
}

✅ Health Check

{
  "status": "healthy",
  "timestamp": 1691234567.89
}

✅ Cache Statistics

{
  "total_entries": 25,
  "memory_usage_mb": 145.7,
  "hit_rate": 0.85,
  "cache_size_limit": "1GB"
}

❌ Error Response

{
  "status": "error",
  "error": "Invalid file type",
  "supported_formats": ["pdf", "docx", "pptx", "html", "eml"],
  "received_format": "txt"
}

🔍 Search Strategies

Semantic

🧠 Meaning-based search
🎯 Best for concept queries
📝 Understands context

Hybrid

⚡ Best of both worlds
🎯 Semantic + keyword
📊 Recommended default

Keyword

🔤 Exact term matching
⚡ Fast performance
📍 Precise word search

⚡ Quick Reference

Endpoints

POST /hackrx/run
GET /health
GET /cache/stats
POST /cache/clear

File Limits

📏 Max: ~50MB per file
⏱️ Timeout: 60 seconds
📁 Types: PDF, DOCX, PPTX, HTML, EML

Best Practices

✅ Use absolute file paths
✅ Handle errors gracefully
✅ Set appropriate timeouts

Environment

🌐 Prod: yourapi.example.com
🏠 Local: localhost:8000
🔧 Use environment variables
Note: All examples use the production API endpoint. For local development, replace the URL with http://localhost:8000. The HackRx endpoint processes queries in parallel for better performance.