API Documentation.md

Lung Cancer AI Advisor API Documentation

Base URL

https://moazx-lung-cancer-ai-advisor.hf.space/  # Production
http://127.0.0.1:7860/                         # Development

---

1. POST /ask

Full Endpoint: https://moazx-lung-cancer-ai-advisor.hf.space/ask (Production) Development: http://127.0.0.1:7860/ask Purpose: Get a complete AI response for a lung cancer-related medical query.

Request

• Method: POST
• Content-Type: application/json
• Authentication: Required (via Authorization header)

Request Body (JSON):

{
  "query": "What are the early symptoms of lung cancer?",
  "session_id": "user_123_session_1699612345"
}

Parameters:

• query (required, string): The medical question about lung cancer
• session_id (required, string): Unique session identifier for conversation continuity. Format: user_{user_id}_session_{timestamp}

Response (200 OK)

{
  "response": "Early symptoms of lung cancer may include...\n\n**Common Early Signs:**\n- Persistent cough...",
  "session_id": "user_123_session_1699612345"
}

Error Responses

• 400 Bad Request: Missing or invalid parameters
• 401 Unauthorized: Missing or invalid authentication
• 500 Internal Server Error: Error processing the query
• 503 Service Unavailable: Service is initializing, try again later

---

2. POST /ask/stream (Recommended)

Full Endpoint: https://moazx-lung-cancer-ai-advisor.hf.space/ask/stream (Production) Development: http://127.0.0.1:7860/ask/stream Purpose: Stream AI response in real-time for better UX.

Request

• Method: POST
• Content-Type: application/json
• Authentication: Required (via Authorization header)

Request Body (JSON):

{
  "query": "What are the early symptoms of lung cancer?",
  "session_id": "user_123_session_1699612345"
}

Parameters:

• query (required, string): The medical question about lung cancer
• session_id (required, string): Unique session identifier for conversation continuity. Format: user_{user_id}_session_{timestamp}

Response

• Streams the AI response in chunks (text/event-stream or similar).
• Each chunk contains a part of the response.

Error Responses

• 400 Bad Request: Missing or invalid parameters
• 401 Unauthorized: Missing or invalid authentication
• 500 Internal Server Error: Error processing the query
• 503 Service Unavailable: Service is initializing, try again later

---

3. GET /health

Full Endpoint: https://moazx-lung-cancer-ai-advisor.hf.space/health (Production) Development: http://127.0.0.1:7860/health

Related Endpoints:

• GET /health/ping - Basic connectivity check
• GET /health/initialization - Check initialization status
• GET /health/version - Get API version information Purpose: Comprehensive health check of all system components.

Response (200 OK)

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-01T12:00:00Z",
  "components": {
    "agent": "healthy",
    "vector_store": "healthy",
    "data_loaders": "healthy",
    "tools": "healthy"
  },
  "initialization": {
    "is_complete": true,
    "status_message": "Initialization complete",
    "is_successful": true,
    "error": null
  }
}

Component Status Values:

• healthy: Component is functioning normally
• unhealthy: Component is not functioning
• initializing: Component is still initializing

Initialization Status:

• is_complete: Whether initialization has completed
• is_successful: Whether initialization was successful
• status_message: Current status message
• error: Any error that occurred during initialization

---

4. Export Endpoints

4.1 GET /export/{format}

Full Endpoint: https://moazx-lung-cancer-ai-advisor.hf.space/export/{format} (Production) Development: http://127.0.0.1:7860/export/{format} Purpose: Export conversation history in the specified format.

Path Parameters:

• format (string, required):
  • docx: Microsoft Word document (.docx)
  • pdf: Portable Document Format (.pdf)

Query Parameters:

• session_id (string, required): The session ID to export (e.g., "user_123_session_1699612345")

Example Request:

GET /export/pdf?session_id=user_123_session_1699612345

Responses:

• 200 OK:
  • Returns the exported file with appropriate content-type header
  • Headers:
    • Content-Type: application/pdf or application/vnd.openxmlformats-officedocument.wordprocessingml.document
    • Content-Disposition: attachment; filename=conversation_{session_id}_{timestamp}.{format}
• 400 Bad Request:
  • Invalid format (not 'docx' or 'pdf')
  • Missing required parameters
• 401 Unauthorized: Missing or invalid authentication
• 404 Not Found: No conversation history found for the specified session
• 500 Internal Server Error: Error generating export file
• 503 Service Unavailable: Service is initializing, try again later

Response Headers:

• Content-Type: application/pdf or application/vnd.openxmlformats-officedocument.wordprocessingml.document
• Content-Disposition: attachment; filename=conversation_{session_id}_{timestamp}.{format}

Frontend Integration Tips:

• Trigger file download using the browser's built-in behavior
• Show loading state during export generation
• Handle errors gracefully with user-friendly messages
• For PDF exports, consider showing a preview using PDF.js

---

5. Session Management

5.1 GET /sessions

Purpose: List all active conversation sessions.

Response (200 OK):

{
  "active_sessions": ["session1", "session2"],
  "count": 2,
  "timestamp": "2024-01-01T12:00:00Z"
}

5.2 DELETE /sessions/{session_id}

Purpose: Clear conversation history for a specific session.

Path Parameters:

• session_id: The session ID to clear

Response (200 OK):

{
  "message": "Session 'session_id' cleared successfully",
  "session_id": "session_id",
  "timestamp": "2024-01-01T12:00:00Z"
}

5.3 DELETE /sessions

Purpose: Clear all conversation sessions.

Response (200 OK):

{
  "message": "All sessions cleared successfully",
  "timestamp": "2024-01-01T12:00:00Z"
}

---

6. Error Handling

All error responses follow this format:

{
  "error": "error_type",
  "message": "Human-readable error message",
  "details": {
    "field": "Additional error details"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

Common Error Types:

• validation_error: Request validation failed
• authentication_error: Invalid or missing authentication
• not_found: Requested resource not found
• rate_limit_exceeded: Too many requests
• server_error: Internal server error

---

7. Rate Limiting

• Rate Limit: 100 requests per minute per IP address
• Headers:
  • X-RateLimit-Limit: Request limit per time window
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Time when the rate limit resets (UTC timestamp)

---

8. Authentication

All endpoints (except /health and /health/ping) require authentication.

Authentication Header:

Authorization: Bearer YOUR_API_KEY

Getting an API Key: Contact the administrator to obtain an API key with appropriate permissions.

---

9. Best Practices

1. Session Management

   • Always use unique session IDs for different users
   • Reuse the same session ID for follow-up questions
   • Clean up old sessions when no longer needed

2. Error Handling

   • Implement retry logic for transient errors (5xx)
   • Cache successful responses when appropriate
   • Log errors for debugging purposes

3. Performance

   • Use the streaming endpoint (/ask/stream) for better UX
   • Implement client-side caching of responses
   • Batch requests when possible

4. Security

   • Never expose API keys in client-side code
   • Use HTTPS for all requests
   • Validate all user input

---

10. Support

For questions or issues, please contact:

• Email: support@lungcanceradvisor.com
• Slack: #api-support channel
• Documentation: https://docs.lungcanceradvisor.com/api

---

Changelog

v1.0.0 (2024-01-01)

• Initial release of the Lung Cancer AI Advisor API
• Support for streaming and non-streaming queries
• Session-based conversation history
• Export functionality (PDF/DOCX)
• Comprehensive health monitoring

---

Documentation last updated: November 10, 2024

For questions or further integration help, contact the backend team.