Basil Docs

v1.0.0

Basil API Overview

API Overview

Complete API reference for Basil's RESTful endpoints. Build powerful search applications with semantic search, AI-powered Q&A, and more.

Base URL

http://localhost:8000

All API endpoints are relative to this base URL. For production deployments, replace localhost:8000 with your server's address.

Quick Reference

Method	Endpoint	Description	Example
GET	/	API information	Basic API info
POST	/search	Semantic search with JSON	{"query": "text", "max_results": 5}
GET	/search/query	Search with query params	?q=search&max_results=5
POST	/ask	AI-powered Q&A	{"question": "your question"}
GET	/health	Health check	System status
GET	/stats	Database statistics	Collection info

Search Endpoints

POST /search

Perform semantic search using JSON request body. This is the primary search endpoint with full parameter support.

Request Body

{
  "query": "string",        // Search query (required)
  "max_results": 5,         // Maximum results to return (optional, default: 5)
  "threshold": 0.7          // Similarity threshold (optional, default: 0.0)
}

Example Request

curl -X POST "http://localhost:8000/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "website development best practices",
    "max_results": 10,
    "threshold": 0.8
  }'

Response

{
  "results": [
    {
      "id": "page_123",
      "url": "https://example.com/dev-guide",
      "title": "Development Best Practices",
      "content": "Content snippet...",
      "score": 0.95,
      "metadata": {
        "search_patterns": ["web development", "best practices"],
        "last_updated": "2024-01-15"
      }
    }
  ],
  "total_results": 1,
  "query_time": 0.023
}

GET /search/query

Simple search using URL query parameters. Perfect for quick searches and browser integration.

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	Search query
max_results	integer	No	Maximum results (default: 5)
threshold	float	No	Similarity threshold (default: 0.0)

Example Request

curl "http://localhost:8000/search/query?q=API%20documentation&max_results=3"

AI-Powered Endpoints

POST /ask

Ask natural language questions and get AI-generated answers based on the scraped content.

Request Body

{
  "question": "string",     // Natural language question (required)
  "context_limit": 5        // Number of context documents (optional, default: 5)
}

Example Request

curl -X POST "http://localhost:8000/ask" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do I install this software?",
    "context_limit": 3
  }'

Response

{
  "answer": "To install the software, you need to...",
  "confidence": 0.89,
  "sources": [
    {
      "url": "https://example.com/install",
      "title": "Installation Guide",
      "relevance": 0.95
    }
  ],
  "processing_time": 1.234
}

POST /detect_intent

Analyze user messages to detect intent and extract key information for routing or processing.

Request Body

{
  "text": "string"          // Text to analyze (required)
}

Example Request

curl -X POST "http://localhost:8000/detect_intent" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I need help setting up the database"
  }'

Response

{
  "intent": "support_request",
  "category": "database",
  "confidence": 0.92,
  "entities": {
    "topic": "database setup",
    "urgency": "medium"
  },
  "suggested_actions": ["search_database_docs", "contact_support"]
}

System Endpoints

GET /health

Check the health and status of the Basil API and its components.

Response

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:30:00Z",
  "components": {
    "database": "connected",
    "ai_service": "available",
    "embedding_model": "loaded"
  },
  "uptime": "2d 14h 23m"
}

GET /stats

Get database statistics and collection information.

Response

{
  "collection_name": "basil_docs",
  "document_count": 1247,
  "last_updated": "2024-01-15T10:30:00Z",
  "index_size": "45.2MB",
  "search_patterns": 15623,
  "most_recent_scrape": {
    "url": "https://example.com",
    "pages_scraped": 156,
    "timestamp": "2024-01-15T09:15:00Z"
  }
}

POST /reload

Reload the vector database with fresh data. Useful after adding new content.

Response

{
  "status": "success",
  "message": "Database reloaded successfully",
  "documents_loaded": 1247,
  "reload_time": 3.456
}

Error Handling

Basil API uses standard HTTP status codes and returns detailed error information in JSON format.

Common Status Codes

200 Success - Request completed successfully

400 Bad Request - Invalid parameters or malformed request

422 Validation Error - Request validation failed

500 Internal Error - Server or AI service error

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Query parameter 'q' is required",
    "details": {
      "field": "q",
      "value": null,
      "constraint": "required"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456"
}

Interactive Documentation

Swagger UI

Explore and test all endpoints interactively with full parameter documentation and examples.

Open API Documentation

OpenAPI Schema

Download the complete OpenAPI 3.0 specification for integration with your tools.

Download OpenAPI Schema