API Endpoints¶

https://your-domain.com/

POST /chat
Content-Type: application/json

{
  "metadata": {
    "speaker": "John",           // Filter by speaker name
    "topic": "AI",               // Filter by topic
    "file_id": "doc_123",        // Filter to specific document
    "document_type": "transcript" // Filter by document type
  }
}

{
  "response": "Based on the quarterly report, revenue increased by 15%...",
  "sources": [
    {
      "filename": "Q3-Report.pdf",
      "chunk_index": 3,
      "similarity": 0.8543,
      "keyword_score": 0.75,
      "combined_score": 0.8225
    }
  ],
  "context_used": true,
  "llm_provider": "openai"
}

{
  "response": "I don't have enough information to answer that question.",
  "sources": [],
  "context_used": false
}

{
  "response": "This conversation has reached its maximum length. Click the **+** button in the header to start a new conversation.",
  "sources": [],
  "context_used": false,
  "limit_reached": true
}

curl -X POST https://your-domain.com/chat \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my-tenant",
    "session_id": "user_12345",
    "message": "What were the key findings in the Q3 report?"
  }'

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 25
X-RateLimit-Reset: 1706889600

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

{
  "enable_ocr": true,
  "enable_tables": true,
  "enable_layout": true
}

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

{
  "success": true,
  "message": "Document processed and imported successfully",
  "document": {
    "filename": "report.pdf",
    "document_id": 42,
    "document_type": "pdf",
    "page_count": 15,
    "word_count": 5230,
    "tables_count": 3,
    "processing_time_ms": 2450
  }
}

{
  "success": true,
  "message": "Playlist processed: 8 of 10 videos imported",
  "assistant_message": "I've imported 8 videos from the playlist...",
  "playlist": {
    "title": "Training Series",
    "video_count": 10,
    "imported_count": 8
  },
  "documents": [
    {
      "title": "Video 1",
      "document_id": 43,
      "word_count": 1250
    }
  ],
  "failed_videos": [
    {
      "title": "Video 5",
      "url": "https://...",
      "error_type": "no_transcript",
      "error": "No transcript available",
      "retryable": true
    }
  ]
}

curl -X POST "https://your-domain.com/upload?tenant=my-tenant" \
  -H "X-API-Key: your-upload-api-key" \
  -F "file=@document.pdf" \
  -F 'metadata={"department": "Engineering"}'

curl -X POST "https://your-domain.com/upload?tenant=my-tenant" \
  -H "X-API-Key: your-upload-api-key" \
  -F "url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -F "subtitle_langs=en,es"

GET /media-info?tenant=my-tenant&url=<encoded_url>
X-API-Key: your-upload-api-key

POST /media-info?tenant=my-tenant
Content-Type: application/x-www-form-urlencoded
X-API-Key: your-upload-api-key

url=<media_url>

{
  "success": true,
  "supported": true,
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "type": "video",
  "info": {
    "title": "Video Title",
    "duration": 212,
    "uploader": "Channel Name"
  }
}

{
  "success": true,
  "supported": false,
  "url": "https://example.com/video.mp4",
  "message": "URL is not from a supported media platform",
  "supported_platforms": ["youtube.com", "youtu.be", "vimeo.com", "..."]
}

curl "https://your-domain.com/media-info?tenant=my-tenant&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ" \
  -H "X-API-Key: your-upload-api-key"

GET /debug-rag.php?tenant=my-tenant

{
  "mode": "documents",
  "stats": {
    "total_documents": 15,
    "total_chunks": 234,
    "total_embeddings": 234
  },
  "documents": [
    {
      "id": 42,
      "filename": "report.pdf",
      "chunk_count": 12,
      "embedding_count": 12,
      "has_embeddings": true,
      "source_url": null
    }
  ]
}

GET /debug-rag.php?tenant=my-tenant&search=report

GET /debug-rag.php?tenant=my-tenant&doc=42

{
  "mode": "document",
  "document": {
    "id": 42,
    "filename": "report.pdf",
    "metadata": {...}
  },
  "chunks": [
    {
      "id": 101,
      "chunk_index": 0,
      "text_preview": "First 200 characters...",
      "has_embedding": true
    }
  ]
}

GET /debug-rag.php?tenant=my-tenant&query=What+is+AI&threshold=0.25

combined_score = (vector_similarity × 0.7) + (keyword_score × 0.3)

{
  "mode": "query",
  "query": "What is AI",
  "threshold": 0.25,
  "results_above_threshold": 3,
  "results_below_threshold": 2,
  "passed_results": [
    {
      "chunk_id": 101,
      "filename": "ai-guide.pdf",
      "vector_similarity": 0.82,
      "keyword_score": 0.65,
      "combined_score": 0.77
    }
  ],
  "rejected_by_threshold": [...],
  "diagnosis": [
    "3 results above threshold 0.25"
  ]
}

GET /api-debug/logs/?tenant=my-tenant
Authorization: Basic <base64-credentials>

{
  "sessions": ["session_123", "session_456"],
  "total_sessions": 2,
  "log_path": "/var/www/chatbot/logs/api_debug"
}

GET /api-debug/logs/{session_id}
Authorization: Basic <base64-credentials>

{
  "session_id": "session_123",
  "message_count": 5,
  "summary": {
    "total_input_tokens": 1250,
    "total_output_tokens": 850,
    "total_tokens": 2100,
    "total_duration_ms": 3450.25
  },
  "messages": [
    {
      "timestamp": "2026-02-02T10:30:00Z",
      "provider": "openai",
      "model": "gpt-5.2",
      "tokens": {"input": 250, "output": 170},
      "duration_ms": 690
    }
  ]
}

DELETE /api-debug/logs/{session_id}
Authorization: Basic <base64-credentials>

{
  "success": true,
  "message": "Logs for session 'session_123' deleted"
}

X-API-Key: your_admin_api_key
X-Tenant-ID: my-tenant

GET /admin/documents

curl -X GET "https://your-domain.com/admin/documents?page=1" \
  -H "X-Tenant-ID: my-tenant" \
  -H "X-API-Key: your_admin_api_key"

{
  "data": [
    {
      "id": 42,
      "filename": "report.pdf",
      "document_type": "pdf",
      "word_count": 5230,
      "chunk_count": 12,
      "created_at": "2026-02-01T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 45,
    "total_pages": 3
  }
}

DELETE /admin/documents/{id}

curl -X DELETE "https://your-domain.com/admin/documents/42" \
  -H "X-Tenant-ID: my-tenant" \
  -H "X-API-Key: your_admin_api_key"

GET /admin/sessions

curl -X GET "https://your-domain.com/admin/sessions" \
  -H "X-Tenant-ID: my-tenant" \
  -H "X-API-Key: your_admin_api_key"

GET /admin/sessions/{session_id}/messages

curl -X GET "https://your-domain.com/admin/sessions/user_123/messages" \
  -H "X-Tenant-ID: my-tenant" \
  -H "X-API-Key: your_admin_api_key"

DELETE /admin/sessions/{session_id}

GET /admin/tenant-prompts

{
  "data": {
    "tenant_id": "my-tenant",
    "systemPrompt": "You are a helpful assistant...",
    "isActive": true
  },
  "isCustom": true,
  "defaultPrompt": "You are a helpful assistant..."
}

PUT /admin/tenant-prompts

{
  "systemPrompt": "You are a helpful assistant for ACME Corp...",
  "isActive": true
}

DELETE /admin/tenant-prompts

POST /admin/chat

{
  "tenant_id": "my-tenant",
  "session_id": "admin_session_123",
  "message": "What documents do we have about Q3?"
}

{
  "error": "Missing required fields: session_id and message"
}

{
  "error": "Authentication required"
}

{
  "error": "Rate limit exceeded",
  "retry_after": 45
}

{
  "error": "An error occurred processing your request. Please try again."
}

{
  "error": "Document parsing service unavailable"
}

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin

Access-Control-Allow-Origin: https://your-allowed-origin.com
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-API-Key
Access-Control-Max-Age: 3600

<?php
$client = new GuzzleHttp\Client();

$response = $client->post('https://your-domain.com/chat', [
    'json' => [
        'tenant_id' => 'my-tenant',
        'session_id' => 'user_123',
        'message' => 'What is in the report?'
    ]
]);

$data = json_decode($response->getBody(), true);
echo $data['response'];

import requests

response = requests.post(
    'https://your-domain.com/chat',
    json={
        'tenant_id': 'my-tenant',
        'session_id': 'user_123',
        'message': 'What is in the report?'
    }
)

data = response.json()
print(data['response'])

const response = await fetch('https://your-domain.com/chat', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        tenant_id: 'my-tenant',
        session_id: 'user_123',
        message: 'What is in the report?'
    })
});

const data = await response.json();
console.log(data.response);