API Documentation

Complete reference for the BodhDisha API

v1.0.0 Last updated: September 25, 2026

Getting Started

The BodhDisha API provides programmatic access to India's most comprehensive education data repository. This REST API allows you to access structured information about exams, colleges, universities, courses, scholarships, and coaching centres.

Quick Start in 3 Steps

1

Get Your API Key

Sign up at bodhdisha.com/api/register to get your API key.

2

Make Your First Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://bodhdisha.com/api/v1/health"
3

Start Building

Explore the endpoints below to find the data you need.

Base URL: All endpoints are relative to https://bodhdisha.com/api/v1

Authentication

Every protected API request requires a valid API key. You can obtain your API key from the developer dashboard after signing up.

Authentication Methods

Send your API key using one of these methods:

Bearer Token (Recommended)
Authorization: Bearer YOUR_API_KEY
API Key Header
X-API-Key: YOUR_API_KEY
Security Notice: Keep your API key confidential. Never expose it in client-side code, public repositories, or screenshots.

Base URL

All API endpoints are relative to the following base URL:

https://bodhdisha.com/api/v1

Example full endpoint:

https://bodhdisha.com/api/v1/colleges

Rate Limiting

Each API key has a request limit per hour. The limit varies based on your subscription tier. When exceeded, the API returns a 429 status with a Retry-After header.

Free 50 requests/hour
Basic 500 requests/hour
Pro 2000 requests/hour
Enterprise Custom
Best Practice: Always implement exponential backoff when handling 429 responses. Repeated immediate retries will delay your access further.

API Endpoints

All endpoints support GET requests only and return JSON responses.

Exams

Access information about educational exams in India.

Method Endpoint Description
GET /exams List all active exams
GET /exams/{slug} Get detailed exam information by slug

Search fields: name, short_name, category, education_level, state

GET /exams?search=JEE&page=1&per_page=20
View Example Response
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Joint Entrance Examination Main",
      "slug": "jee-main",
      "short_name": "JEE Main",
      "category": "engineering",
      "education_level": "undergraduate",
      "state": "national",
      "description": "Joint Entrance Examination Main is a national-level entrance exam...",
      "eligibility_summary": "10+2 with Physics, Chemistry, and Mathematics",
      "last_verified_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-06-20T14:22:10Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 125,
    "last_page": 7
  }
}

Colleges

Access information about colleges across India.

Method Endpoint Description
GET /colleges List all active colleges
GET /colleges/{slug} Get detailed college information by slug

Search fields: name, state, city, accreditation

GET /colleges?search=delhi&page=1&per_page=20
View Example Response
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Indian Institute of Technology Delhi",
      "slug": "iit-delhi",
      "state": "Delhi",
      "city": "New Delhi",
      "accreditation": "AICTE",
      "is_verified": true,
      "trust_score": 4.9,
      "description": "IIT Delhi is one of the premier engineering institutes...",
      "official_website": "https://iitd.ac.in",
      "last_verified_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Universities

Access information about universities across India.

Method Endpoint Description
GET /universities List all active universities
GET /universities/{slug} Get detailed university information by slug

Search fields: name, state, city, accreditation

Courses

Access information about courses offered by various institutions.

Method Endpoint Description
GET /courses List all active courses
GET /courses/{slug} Get detailed course information by slug

Search fields: name, provider, level, duration

Scholarships

Access information about scholarships available for students.

Method Endpoint Description
GET /scholarships List all active scholarships
GET /scholarships/{slug} Get detailed scholarship information by slug

Search fields: name, provider, education_level, state

Coaching Centres

Access information about coaching centres across India.

Method Endpoint Description
GET /coaching List all active coaching centres
GET /coaching/{slug} Get detailed coaching centre information by slug

Search fields: name, city, area_hub, state, fee_range

Pagination

All collection endpoints support pagination to help you manage large datasets.

Parameter Type Default Description
page Integer 1 Page number (starts at 1)
per_page Integer 20 Records per page (max: 100)

Example

GET /colleges?page=2&per_page=50

Response

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 2,
    "per_page": 50,
    "total": 125,
    "last_page": 3
  }
}

Response Format

Single Record Response

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Indian Institute of Technology Guwahati",
    "slug": "iit-guwahati",
    "location": "Guwahati, Assam",
    "accreditation": "AICTE",
    "website": "https://www.iitg.ac.in",
    "trust_score": 4.8,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-06-20T14:22:10Z"
  }
}

Collection Response

{
  "success": true,
  "data": [
    { ... },
    { ... }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 125,
    "last_page": 7
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "College not found"
  }
}

HTTP Status Codes

Code Meaning Description
200 OK Request successful
400 Bad Request Invalid parameters or malformed request
401 Unauthorized Missing or invalid API key
403 Forbidden API key does not have permission
404 Not Found Resource does not exist
429 Too Many Requests Rate limit exceeded
500 Server Error Unexpected server error

Error Response Format

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found"
  }
}

Code Examples

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://bodhdisha.com/api/v1/colleges/iit-guwahati"

JavaScript (Fetch)

const response = await fetch(
  'https://bodhdisha.com/api/v1/colleges?search=guwahati',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json'
    }
  }
);

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}

const result = await response.json();
console.log(result.data);

JavaScript (Axios)

import axios from 'axios';

const response = await axios.get(
  'https://bodhdisha.com/api/v1/colleges',
  {
    params: {
      search: 'guwahati',
      per_page: 20
    },
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

console.log(response.data.data);

Python

import requests

response = requests.get(
    'https://bodhdisha.com/api/v1/colleges',
    params={
        'search': 'guwahati',
        'per_page': 20
    },
    headers={
        'Authorization': 'Bearer YOUR_API_KEY'
    }
)

response.raise_for_status()
data = response.json()
print(data['data'])

PHP

<?php

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://bodhdisha.com/api/v1/colleges?search=guwahati',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Accept: application/json'
    ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    print_r($data['data']);
} else {
    echo "Error: HTTP $httpCode\n";
}

Ruby

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://bodhdisha.com/api/v1/colleges')
params = { search: 'guwahati', per_page: 20 }
uri.query = URI.encode_www_form(params)

req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer YOUR_API_KEY'
req['Accept'] = 'application/json'

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(req)
end

if res.is_a?(Net::HTTPSuccess)
  data = JSON.parse(res.body)
  puts data['data']
else
  puts "Error: #{res.code} - #{res.message}"
end

Go

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
)

func main() {
    baseURL, _ := url.Parse("https://bodhdisha.com/api/v1/colleges")
    params := url.Values{}
    params.Add("search", "guwahati")
    params.Add("per_page", "20")
    baseURL.RawQuery = params.Encode()

    req, _ := http.NewRequest("GET", baseURL.String(), nil)
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Accept", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    
    if resp.StatusCode == 200 {
        var result map[string]interface{}
        json.Unmarshal(body, &result)
        fmt.Printf("%v\n", result["data"])
    } else {
        fmt.Printf("Error: %d\n", resp.StatusCode)
    }
}

Security Best Practices

  • Keep API keys confidential — treat them like passwords
  • Use HTTPS — always encrypt data in transit
  • Store keys in environment variables or a secure secrets manager
  • Never commit API keys to version control (Git, SVN, etc.)
  • Do not expose API keys in client-side JavaScript
  • Request only the data you need — use search filters effectively
  • Respect rate limits — implement graceful error handling
  • Rotate keys periodically and revoke compromised keys immediately

Frequently Asked Questions

How do I get an API key?

Sign up at bodhdisha.com/api/register using Google or GitHub. Your API key will be displayed in the dashboard.

What happens if I exceed my rate limit?

You'll receive a 429 Too Many Requests response. The limit resets every hour.

Can I use the API for commercial purposes?

Yes, the API is available for commercial use with appropriate subscription plans.

How fresh is the data?

Data is updated regularly. Cache duration varies by endpoint (5-15 minutes for lists, 30 minutes for details).

Is there a sandbox environment?

The production API can be used for testing with the Free tier (50 requests/hour).

How do I report an issue?

Contact us at [email protected] or through the contact form.