Quick Start

Get up and running with the BrainUs API in just 5 minutes. This guide will walk you through making your first API request.

You'll need a BrainUs account to follow this guide. Sign up here if you haven't already.

Prerequisites

Before you begin, make sure you have:

A BrainUs account (sign up here)
Basic knowledge of REST APIs
Command line access or a programming environment (Python/Node.js)

Step-by-Step Guide

Create Your Account

Visit developers.brainus.lk and sign up for a free account. You'll get:

300 requests/month on the free plan
Immediate API access
No credit card required

Use your work email to make it easier for your team to collaborate later.

Generate an API Key

Once logged in:

Navigate to the Dashboard → API Keys
Click "Create New Key"
Give your key a descriptive name (e.g., "Test Key" or "Production Key")
Select your plan (Free tier is pre-selected)
Click "Generate"

Important: Copy your API key immediately! For security reasons, you won't be able to see it again. Keys look like: brainus_abc123...

Store your API key securely:

# Add to your environment variables
export BRAINUS_API_KEY="brainus_your_key_here"

Make Your First Request

Now let's query the API! Choose your preferred method:

Open your terminal and run:

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 the Pythagorean theorem?",
    "store_id": "default"
  }'

Install the SDK:

pip install brainus-ai

Then run this code:

import asyncio
import os
from brainus_ai import BrainusAI

async def main():
    # Initialize client
    async with BrainusAI(api_key=os.getenv("BRAINUS_API_KEY")) as client:
        # Make a query
        response = await client.query(
            query="What is the Pythagorean theorem?",
            store_id="default"
        )

        # Print results
        print("Answer:", response.answer)
        print("\nCitations:")
        if response.citations:
            for citation in response.citations:
                print(f"  - {citation.document_name}")
                if citation.pages:
                    print(f"    Pages: {', '.join(map(str, citation.pages))}")

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

Install the SDK:

npm install @brainus/ai

Then run this code:

import { BrainusAI } from '@brainus/ai';

const client = new BrainusAI({
  apiKey: process.env.BRAINUS_API_KEY
});

async function main() {
  // Make a query
  const response = await client.query({
    query: 'What is the Pythagorean theorem?',
    storeId: 'default'
  });

  // Print results
  console.log('Answer:', response.answer);
  console.log('\nCitations:');
  if (response.hasCitations) {
    response.citations.forEach(citation => {
      console.log(`  - ${citation.documentName}`);
      if (citation.pages.length > 0) {
         console.log(`    Pages: ${citation.pages.join(", ")}`);
      }
    });
  }
}

main();

Install dependencies:

npm install axios

Create a file test.js:

const axios = require('axios');

async function queryBrainUs() {
  try {
    const response = await axios.post(
      'https://api.brainus.lk/api/v1/dev/query',
      {
        query: 'What is the Pythagorean theorem?',
        store_id: 'default'
      },
      {
        headers: {
          'X-API-Key': process.env.BRAINUS_API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('Answer:', response.data.answer);
    console.log('\nCitations:');
    response.data.citations.forEach(citation => {
      console.log(`  - ${citation.document}, page ${citation.page}`);
    });
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

queryBrainUs();

Run it:

node test.js

Understand the Response

You should receive a JSON response like this:

{
  "answer": "The Pythagorean theorem states that in a right-angled triangle, the square of the length of the hypotenuse (the side opposite the right angle) is equal to the sum of the squares of the lengths of the other two sides. This can be written as: a² + b² = c², where c represents the length of the hypotenuse and a and b represent the lengths of the other two sides.",
  "citations": [
    {
      "document": "Grade 10 Mathematics Textbook",
      "page": 87,
      "relevance": 0.98,
      "excerpt": "Pythagorean theorem: a² + b² = c²"
    }
  ],
  "metadata": {
    "tokens_used": 156,
    "response_time_ms": 342,
    "store_id": "default"
  }
}