# BnD REST API Platform by Lushai Dev

> The premier high-performance REST API platform providing structured access to Mizo Holy Scriptures (OV), KJV, NIV, ESV, WEB, NKJV Bibles, and English-Mizo Dictionary datasets. Built with rate limiting and developer API keys.

## Platform Details
- **Base Endpoint URL**: https://lushai.dev/api/v1
- **API Version**: v1.0.0
- **Data Format**: JSON (utf-8)
- **Official Website**: https://lushai.dev
- **Contact & Support Email**: support@lushai.dev

## System Documentation Files
- Full Technical Specification: https://lushai.dev/llms-full.txt
- Interactive Web Documentation: https://lushai.dev/docs
- Developer Playbook & Integration Guide: https://lushai.dev/guide
- XML Sitemap: https://lushai.dev/sitemap.xml
- OpenAPI / Swagger Reference: https://lushai.dev/docs#docs

## Authentication Methods
Every request to the BnD REST API requires an API key to identify your client. You can pass your key using any of these 3 methods:
1. `X-API-Key: YOUR_BND_API_KEY` (Recommended HTTP Header)
2. `Authorization: Bearer YOUR_BND_API_KEY` (Standard Bearer Header)
3. `https://lushai.dev/api/v1/bibles?api_key=YOUR_BND_API_KEY` (Query Parameter)

## REST API Endpoints Overview

### 1. Holy Scriptures Endpoint
- **URL**: `GET /api/v1/bibles`
- **Description**: Query Bible translations, books, chapters, and verses.
- **Parameters**:
  - `code` (string): Bible code e.g. `mizo`, `kjv`, `niv`, `esv`, `web`, `nkjv`
  - `book` (string): Book name e.g. `John`, `Genesis`, `Psalms`
  - `chapter` (integer): Chapter number e.g. `3`
  - `verse` (integer): Verse number e.g. `16`
  - `q` (string): Full-text search keyword e.g. `Pathian`, `Grace`
  - `limit` (integer): Max results (default 50, max 100)
  - `offset` (integer): Pagination offset (default 0)

### 2. Dictionaries Endpoint
- **URL**: `GET /api/v1/dictionaries`
- **Description**: Query word definitions, phonetics, parts of speech, and sample sentences.
- **Parameters**:
  - `code` (string): Dictionary code e.g. `eng_mizo`, `mizo_eng`
  - `word` (string): Exact word lookup e.g. `Faith`
  - `q` (string): Definition keyword or word search e.g. `Grace`
  - `limit` (integer): Max results (default 50)
  - `offset` (integer): Pagination offset

### 3. Daily Highlights Endpoint
- **URL**: `GET /api/v1/daily`
- **Description**: Returns auto-generated daily Verse of the Day and Word of the Day JSON payload.

### 4. Developer Key Management Endpoint
- **URL**: `GET / POST /api/v1/keys`
- **Description**: View, generate, or regenerate API keys for authenticated users.

## Rate Limiting & Quotas
- **Starter Tier**: 60 Requests Per Minute (RPM) - Free
- **Pro Tier**: 300 Requests Per Minute (RPM) - ₹149 / $1.77 USD Lifetime
- **Headers Returned**: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

## Integration Code Examples

### cURL
```bash
curl -X GET "https://lushai.dev/api/v1/bibles?code=mizo&book=John&chapter=3&verse=16" \
     -H "X-API-Key: YOUR_BND_API_KEY"
```

### JavaScript (Fetch)
```javascript
fetch("https://lushai.dev/api/v1/dictionaries?code=eng_mizo&q=Faith", {
  headers: { "X-API-Key": "YOUR_BND_API_KEY" }
})
.then(res => res.json())
.then(data => console.log(data));
```

### Python
```python
import requests

url = "https://lushai.dev/api/v1/daily"
headers = {"X-API-Key": "YOUR_BND_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())
```