Quick Start

Introduction

BrainUs AI is a RAG-powered educational API designed to provide accurate, curriculum-aligned content with verifiable citations. Built for developers creating educational applications, it offers seamless integration with comprehensive documentation coverage.

BrainUsAI API has different parts:

Query API

The core endpoint for retrieving educational content from our knowledge base with AI-powered search and verified citations.

Usage API

Track your API usage, monitor quotas, and analyze performance metrics in real-time.

Plans API

Retrieve information about available plans, pricing, and upgrade options programmatically.

SDKs & Libraries

Official Python and JavaScript SDKs with full TypeScript support, automatic retry handling, and rate limit management.

Want to learn more?

Read our detailed Getting Started guide and explore the API Reference.

Terminology

RAG (Retrieval-Augmented Generation): An AI approach that combines document retrieval with language generation to provide accurate, citation-backed answers.
Store: A collection of indexed documents. Use "default" for general Sri Lankan curriculum queries.
Citation: Source references with document name and page number that verify the accuracy of API responses.

Some basic knowledge of REST APIs and either Python or JavaScript would be useful.

Create Your Account

Visit developers.brainus.lk and create your free account. No credit card required.

Generate API Key

Navigate to Dashboard → API Keys and click "Generate New Key". Copy it immediately - you won't see it again!

Make Your First Request

Test your API key with a simple curl command:

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

Install SDK (Optional)

For Python or JavaScript projects, install our official SDK:

# Python
pip install brainus-ai

# JavaScript/TypeScript
npm install @brainus/ai

Your First Query

Using Python

import asyncio
import os
from brainus_ai import BrainusAI

async def main():
    # Ensure BRAINUS_API_KEY is set in your environment
    api_key = os.getenv("BRAINUS_API_KEY")
    
    async with BrainusAI(api_key=api_key) as client:
        result = await client.query(
            query="What is photosynthesis?",
            store_id="default"
        )
        print(result.answer)

        # Access citations
        if result.citations:
            for citation in result.citations:
                print(f"Source: {citation.document_name}")
                if citation.pages:
                    print(f"Pages: {', '.join(map(str, citation.pages))}")

if __name__ == "__main__":
    asyncio.run(main())

Using JavaScript

/* Use ESM or TypeScript */
import { BrainusAI } from "@brainus/ai";

/* Or CommonJS */
/* const { BrainusAI } = require("@brainus/ai"); */

// Ensure BRAINUS_API_KEY is set in your environment
const client = new BrainusAI({
  apiKey: process.env.BRAINUS_API_KEY,
});

async function main() {
  const result = await client.query({
    query: "What is photosynthesis?",
    storeId: "default",
  });

  console.log(result.answer);

  // Access citations
  if (result.citations && result.citations.length > 0) {
    result.citations.forEach((citation) => {
      console.log(`Source: ${citation.documentName}`);
      if (citation.pages.length > 0) {
         console.log(`Pages: ${citation.pages.join(", ")}`);
      }
    });
  }
}

main();

Using cURL

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

The free plan includes 300 requests per month. Perfect for testing and small projects!

FAQ

Common questions you may encounter.

How do I secure my API key?

Never expose your API key in client-side code. Always use environment variables and proxy requests through your backend:

# .env
BRAINUS_API_KEY=brainus_your_key_here

import os
from brainus_ai import BrainusAI

async with BrainusAI(api_key=os.getenv("BRAINUS_API_KEY")) as client:
    pass

See our Security Best Practices guide.

What happens when I hit rate limits?

The API returns a 429 status code with a retry_after header indicating how long to wait. Our SDKs handle this automatically with exponential backoff.

Learn more in Rate Limits.

Can I use filters to narrow results?

Yes! Use filters to target specific grades, subjects, or content types:

result = await client.query(
    query="Mathematics concepts",
    store_id="default",
    filters={
        "grade": ["9", "10"],
        "subject": ["Mathematics"]
    }
)

See Filters & Options.

How do I track my usage?

Use the Usage API to monitor your quota:

usage = await client.get_usage()
print(f"Used: {usage.quota_requests_used}/{usage.quota_requests_limit}")

View detailed analytics in the Dashboard.

Building with Python? Check out our Python SDK and Python Examples
Using JavaScript? Start with JavaScript SDK and JavaScript Examples
Need advanced features? Explore Filters & Options and Best Practices
Want to optimize? Read our Rate Limit Optimization guide

Join our Discord community for real-time help and discussions with other developers!

Introduction

Query API

Usage API

Plans API

SDKs & Libraries

Terminology

Create Your Account

Generate API Key

Make Your First Request

Install SDK (Optional)

Your First Query

Using Python

Using JavaScript

Using cURL

FAQ

How do I secure my API key?

What happens when I hit rate limits?

Can I use filters to narrow results?

How do I track my usage?

Can I upgrade my plan programmatically?

Learn More

Core Documentation

Getting Started

Authentication

Query API

Code Examples

SDKs & Integration

Python SDK

JavaScript/TypeScript SDK

Python Examples

JavaScript Examples

Advanced Topics

Rate Limits

Error Reference

Usage Tracking

Plans & Pricing

Next Steps

On this page