API Reference

Introduction

The HackRx 6.0 system exposes a modern, RESTful API for seamless integration into your existing workflows. All endpoints are secured and require an API token for access. The API is built using FastAPI, ensuring high performance and providing interactive documentation out-of-the-box.

Authentication

All requests to the API must include an Authorization header containing a Bearer token.

Header Format: Authorization: Bearer YOUR_API_TOKEN

The API token is defined in your environment configuration (e.g., the .env file).

Main Endpoint: Document Query

This is the primary endpoint for processing a document and getting answers to your questions. It orchestrates the entire retrieval and generation pipeline.

POST /hackrx/run

This endpoint processes a specified document file, finds the most relevant information related to your questions, and returns AI-generated answers.

Request Body

The request must be a JSON object with the following structure, as defined in the QueryRequest schema:

Field	Type	Description	Required
documents	string	The filename of the document you want to query. The file must be located in the app/data directory of the repository. Example: "BAJHLIP23020V012223.pdf".	Yes
questions	List[string]	A list of one or more questions you want to ask about the document's content.	Yes

Response Body

If successful, the API will return a JSON object with a list of answers, as defined in the QueryResponse schema:

Field	Type	Description
answers	List[string]	A list of answers generated by the LLM. The order of answers corresponds directly to the order of the questions in the request.

Example Usage

Here is an example of how to call the endpoint using cURL:

curl -X POST "http://localhost:8000/hackrx/run" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "documents": "HDFHLIP23024V072223.pdf",
  "questions": [
    "What is the waiting period for pre-existing diseases?",
    "What is the coverage for maternity expenses?"
  ]
}'

Expected API Response

Executing your cURL command against the running service would yield the following JSON response. The answers are generated by finding the most relevant sections in the provided policy document.

{
  "answers": [
    "Expenses related to the treatment of a pre-existing disease (PED) and its direct complications are excluded until the expiry of 36 months of continuous coverage after the date of inception of the first policy with the insurer.",
    "Medical expenses for delivery, including caesarean sections, and lawful medical termination of pregnancy are covered, limited to two instances in a lifetime. Coverage amounts depend on the plan; for example, the Standard plan covers Normal Delivery up to Rs. 15,000 and Caesarean Delivery up to Rs. 25,000, which includes pre-natal and post-natal expenses."
  ]
}

Possible Errors

• 400 Bad Request: This will be returned if the documents filename or the questions list is missing from the request.

• 401 Unauthorized: This will be returned if the API token is missing or invalid.

• 404 Not Found: This error occurs if the specified document filename does not exist in the app/data directory.

• 500 Internal Server Error: This indicates a general server-side error during processing.

Utility Endpoints

These endpoints provide health status and basic statistics about the system.

GET /health

This endpoint can be used to check if the API is running and accessible. It does not require authentication.

• Response: A JSON object indicating the health status of the application.

{
  "status": "healthy",
  "embedding_model": "all-MiniLM-L6-v2",
  "database_connected": true
}

GET /stats

This endpoint provides basic statistics about the documents and Q&A sessions processed by the system. It requires authentication.

• Response: A JSON object with key statistics.

{
  "total_documents": 15,
  "total_qa_sessions": 122,
  "embedding_index_size": 4532
}

How to Change the Host in Swagger UI

The "host" (the server URL where the API is running) is determined by how the application is run and accessed. In your current setup:

• Local Host: The docker-compose.yml file exposes the service on port 8000 of your local machine. Therefore, the default host is http://localhost:8000.

When you navigate to the interactive Swagger UI at http://localhost:8000/docs, it will automatically use this URL as the base for all API calls you test from that page.