Query API

The Query API is the core endpoint for retrieving educational content from the BrainUs knowledge base. It uses Retrieval-Augmented Generation (RAG) to provide accurate answers with verifiable citations.

Endpoint

POST /api/v1/dev/query

Base URL: https://api.brainus.lk

Authentication

All requests require authentication using your API key. See Authentication for details.

X-API-Key: $BRAINUS_API_KEY

Quick Example

curl -X POST https://api.brainus.lk/api/v1/dev/query \
  -H "X-API-Key: $BRAINUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is photosynthesis?",
    "store_id": "default"
  }'

Request Parameters

Parameter	Type	Required	Description
`query`	string	Yes	The question or search query
`store_id`	string	Yes	Knowledge base identifier (use `"default"`)
`filters`	object	No	Filter results by grade, subject, or language
`options`	object	No	Additional options for the query

Response Format

{
  "answer": "AI-generated answer to your query",
  "citations": [
    {
      "document": "Source document name",
      "page": 45,
      "relevance": 0.95,
      "excerpt": "Relevant excerpt from the document"
    }
  ],
  "metadata": {
    "query_id": "qry_1234567890abcdef",
    "tokens_used": 256,
    "response_time_ms": 342
  }
}

All responses include citations from official Sri Lankan curriculum documents, ensuring verifiable answers.

Next Steps

Basic Usage - Learn how to make basic queries
Filters & Options - Advanced filtering and options
Best Practices - Optimization tips and patterns

Rate Limits

Query API requests count against your rate limits:

Plan	Requests/min	Requests/day	Requests/month
Free	10	300	300
Starter	20	2,000	2,000
Pro	60	10,000	10,000
Enterprise	200	50,000	50,000