API Documentation

1. Get API Access

To obtain an API key, simply log in with your Google account and visit the Get API Key page. You can request a unique API key directly from the platform without contacting support.

2. Make Your First Request

With API Key (Production):

curl -X POST https://khoj-bd.com/api/v1/factcheck \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"query": "বাংলাদেশে করোনা ভ্যাকসিনের পার্শ্বপ্রতিক্রিয়া আছে"}'

Without API Key (Development - requires API_AUTH_REQUIRED=false):

curl -X POST https://khoj-bd.com/api/v1/factcheck \
  -H "Content-Type: application/json" \
  -d '{"query": "বাংলাদেশে করোনা ভ্যাকসিনের পার্শ্বপ্রতিক্রিয়া আছে"}'

Method 1: Authorization Header (Recommended)

Authorization: Bearer <your-api-key>

Method 2: X-API-Key Header

X-API-Key: <your-api-key>

Fact-Check a Claim

Verify a claim or statement and receive a detailed fact-checking report.

Endpoint: POST /api/v1/factcheck

Authentication: Required (unless API_AUTH_REQUIRED=false)

{
  "query": "The claim or statement to fact-check"
}

{
  "success": true,
  "data": {
    "claim": "বাংলাদেশে করোনা ভ্যাকসিনের পার্শ্বপ্রতিক্রিয়া আছে",
    "report": "# দাবি\n\n[Detailed Bengali report in Markdown format...]",
    "verdict": "false",
    "sources": [
      {
        "id": 1,
        "title": "Source Title",
        "url": "https://example.com/article",
        "snippet": "Article snippet...",
        "language": "Bengali"
      }
    ],
    "relatedArticles": [...],
    "sourceInfo": {
      "hasBengaliSources": true,
      "hasEnglishSources": false,
      "totalSources": 12,
      "geography": "bangladesh",
      "tierBreakdown": {
        "tier1": 5,
        "tier2": 4,
        "tier3": 2,
        "tier4": 1,
        "tier5": 0,
        "general": 0
      }
    },
    "generatedAt": "2024-01-01T12:00:00.000Z"
  },
  "meta": {
    "apiVersion": "1.0",
    "generatedAt": "2024-01-01T12:00:00.000Z",
    "authenticated": true
  }
}

Verdict Values

The verdict field can have one of the following values:

• "true": The claim is verified as true
• "false": The claim is verified as false
• "unverified": The claim could not be verified with available sources
• "context_dependent": The claim's truthfulness depends on context

Response Structure

{
  "success": true,
  "data": {
    "claim": "string - The original claim",
    "report": "string - Detailed fact-checking report in Bengali (Markdown format)",
    "verdict": "string - One of: 'true', 'false', 'unverified', 'context_dependent'",
    "sources": [
      {
        "id": "number",
        "title": "string",
        "url": "string",
        "snippet": "string",
        "language": "string - 'Bengali' or 'English'"
      }
    ],
    "relatedArticles": "array - Related fact-check articles from Khoj database",
    "sourceInfo": {
      "hasBengaliSources": "boolean",
      "hasEnglishSources": "boolean",
      "totalSources": "number",
      "geography": "string - 'bangladesh' or 'international'",
      "tierBreakdown": "object - Breakdown of sources by tier"
    },
    "generatedAt": "string - ISO 8601 timestamp"
  },
  "meta": {
    "apiVersion": "string",
    "generatedAt": "string - ISO 8601 timestamp",
    "authenticated": "boolean"
  }
}

CORS Headers

All API responses include the following CORS headers:

• Access-Control-Allow-Origin: * - Allows requests from any origin
• Access-Control-Allow-Methods: GET, POST, OPTIONS - Allowed HTTP methods
• Access-Control-Allow-Headers: Content-Type, Authorization, X-API-Key - Allowed request headers

Preflight Requests

The API automatically handles CORS preflight (OPTIONS) requests. Browsers will send these automatically before making cross-origin POST requests.

Error Responses

All error responses (400, 401, 429, 500) include proper CORS headers, ensuring that error messages are accessible from cross-origin requests.

Example: Using from Browser

You can call the API directly from any web page using JavaScript:

// This works from any web page, no CORS issues
async function factCheck(query, apiKey = null) {
  const headers = { 
    'Content-Type': 'application/json' 
  };
  
  if (apiKey) {
    headers['Authorization'] = `Bearer ${apiKey.trim()}`;
  }
  
  const response = await fetch('https://khoj-bd.com/api/v1/factcheck', {
    method: 'POST',
    headers: headers,
    body: JSON.stringify({ query })
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Fact-check failed');
  }
  
  return await response.json();
}

// Usage
factCheck('বাংলাদেশে করোনা ভ্যাকসিনের পার্শ্বপ্রতিক্রিয়া আছে')
  .then(result => console.log('Verdict:', result.data.verdict))
  .catch(error => console.error('Error:', error));

Common Error Codes:

• 400 Bad Request: Invalid or missing query parameter, or invalid JSON in request body
• 401 Unauthorized: Invalid or missing API key. For development, set API_AUTH_REQUIRED=false in your server's .env file to test without an API key.
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server-side error occurred

Error Response Examples

{
  "error": "Bad Request",
  "message": "Query is required and must be a non-empty string"
}

{
  "error": "Unauthorized",
  "message": "No API key provided. Please provide a valid API key...",
  "developmentTip": "Set API_AUTH_REQUIRED=false in your .env file..."
}

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your rate limit. Please try again after 2024-01-01T13:00:00.000Z.",
  "resetAt": "2024-01-01T13:00:00.000Z"
}

{
  "success": false,
  "error": "Internal Server Error",
  "message": "Failed to generate fact-checking report"
}

Test with API Key (Production)

curl -X POST https://khoj-bd.com/api/v1/factcheck \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{"query": "বাংলাদেশে করোনা ভ্যাকসিনের পার্শ্বপ্রতিক্রিয়া আছে"}'

Test Without API Key (Development)

⚠️ Requires API_AUTH_REQUIRED=false in server's .env file

curl -X POST https://khoj-bd.com/api/v1/factcheck \
  -H "Content-Type: application/json" \
  -d '{"query": "বাংলাদেশে করোনা ভ্যাকসিনের পার্শ্বপ্রতিক্রিয়া আছে"}'

Test API Info Endpoint

curl https://khoj-bd.com/api/v1/factcheck

1. Cache Results

Fact-checking reports are deterministic for the same query. Consider caching results to reduce API calls and improve response times.

2. Handle Rate Limits

Implement exponential backoff when you receive a 429 response. Check the X-RateLimit-Reset header to know when to retry.

3. Error Handling

Always check the response status and handle errors appropriately. Implement retry logic for transient errors.

4. Query Formatting

Provide clear, specific claims for better fact-checking results. Avoid vague or overly broad queries.

5. Store API Keys Securely

Never commit API keys to version control. Store them in environment variables and use different keys for development and production.