# BnD REST API Platform - Full Technical Specification & LLM Reference Manual

> Official Complete Technical Documentation for the BnD REST API Platform by Lushai Dev.
> Version: v1.0.0
> Base URL: https://lushai.dev/api/v1
> Official Website: https://lushai.dev
> Contact & Support Email: support@lushai.dev

---

## 1. System Overview & Architecture

The BnD Platform (Bible & Dictionary Engine) by Lushai Dev provides high-throughput, rate-limited RESTful JSON APIs for accessing multi-translation Holy Scriptures and bidirectional English-Mizo dictionary datasets.

The system is designed with:
- **Clean Architecture**: Built using native PHP with custom MVC controllers and PDO database abstractions.
- **Security Engineering**: IP and API Key Rate Limiting, PDO Prepared Statements against SQL Injection, Security Headers (`X-Content-Type-Options`, `X-Frame-Options`, `X-XSS-Protection`), CSRF token validation, and Strict Role-Based Access Control (RBAC).
- **Database Backend**: MySQL / MariaDB schema containing `bibles`, `bible_verses`, `dictionaries`, `dictionary_words`, `users`, `api_keys`, `rate_limits`, `transactions`, and `contact_messages` tables.

---

## 2. Authentication & Authorization

All requests to the REST API endpoints require a valid developer API Key.

### API Key Headers & Format
- Key Format: `bnd_live_<64_hex_chars>` or `bnd_pro_<64_hex_chars>`
- Header Option 1 (Recommended): `X-API-Key: YOUR_BND_API_KEY`
- Header Option 2: `Authorization: Bearer YOUR_BND_API_KEY`
- Query Parameter Option 3: `https://lushai.dev/api/v1/bibles?api_key=YOUR_BND_API_KEY`
- Query Parameter Option 4: `https://lushai.dev/api/v1/bibles?key=YOUR_BND_API_KEY`

If an API key is missing, invalid, or blocked, the API returns HTTP 401 Unauthorized:
```json
{
  "status": "error",
  "authenticated": false,
  "message": "Authentication required. Please log in or provide a valid API Key."
}
```

---

## 3. Rate Limiting Specification

The API implements a sliding 1-minute window rate-limiter:

- **Free / Starter Tier**: 60 Requests Per Minute (RPM) per API Key or IP address.
- **Pro Tier**: 300 Requests Per Minute (RPM) per API Key. Cost: ₹149 / $1.77 USD Lifetime.

### Response HTTP Headers
Every API response includes rate limit status headers:
- `X-RateLimit-Limit`: Maximum requests allowed in the 60-second window (e.g. `60` or `300`).
- `X-RateLimit-Remaining`: Requests remaining in the current window.
- `X-RateLimit-Reset`: Unix timestamp when the 60-second window resets.

### HTTP 429 Error Response
If a client exceeds their rate limit:
```json
{
  "status": "error",
  "message": "Rate limit exceeded! You have sent too many requests within 1 minute. Please wait and try again after 1 minute.",
  "retry_after_seconds": 42
}
```

---

## 4. API Endpoints Specification

### 4.1 Bibles Endpoint (`GET /api/v1/bibles`)

Query books, chapters, and verses across loaded Bible translations.

#### Supported Bible Codes:
- `mizo`: Mizo Holy Bible (OV - Old Version)
- `kjv`: King James Version
- `niv`: New International Version
- `esv`: English Standard Version
- `web`: World English Bible
- `nkjv`: New King James Version

#### Request Query Parameters:
- `code` (string, optional): Bible code e.g. `mizo`.
- `book` (string, optional): Book name e.g. `John`, `Genesis`, `Psalms`, `Johana`.
- `chapter` (integer, optional): Chapter number e.g. `3`.
- `verse` (integer, optional): Verse number e.g. `16`.
- `q` (string, optional): Search keyword e.g. `Pathian`, `Love`, `Grace`.
- `limit` (integer, optional, default: 50, max: 100): Page size limit.
- `offset` (integer, optional, default: 0): Pagination offset.

#### Example Request:
`GET https://lushai.dev/api/v1/bibles?code=mizo&book=John&chapter=3&verse=16`

#### Example Response (HTTP 200 OK):
```json
{
  "status": "success",
  "total": 1,
  "limit": 50,
  "offset": 0,
  "data": [
    {
      "id": 26154,
      "bible_code": "mizo",
      "bible_name": "Mizo Holy Bible",
      "book": "Johana",
      "chapter": 3,
      "verse": 16,
      "text": "Pathianin khawvel a hmangaih em em a, chuvangin a Fapa mal neih chhun a pe a, amah chu tu pawh a ring apiang an boral loh va, chatuana nunna an neih zawk nan."
    }
  ]
}
```

---

### 4.2 Dictionaries Endpoint (`GET /api/v1/dictionaries`)

Query word definitions, phonetics, parts of speech, and sample usage sentences.

#### Supported Dictionary Codes:
- `eng_mizo`: English to Mizo Dictionary
- `mizo_eng`: Mizo to English Dictionary

#### Request Query Parameters:
- `code` (string, optional): Dictionary code e.g. `eng_mizo`.
- `word` (string, optional): Exact word lookup e.g. `Faith`.
- `q` (string, optional): Word or definition keyword search e.g. `Grace`.
- `limit` (integer, optional, default: 50, max: 100): Page size.
- `offset` (integer, optional, default: 0): Offset.

#### Example Request:
`GET https://lushai.dev/api/v1/dictionaries?code=eng_mizo&q=Faith`

#### Example Response (HTTP 200 OK):
```json
{
  "status": "success",
  "total": 1,
  "limit": 50,
  "offset": 0,
  "data": [
    {
      "id": 142,
      "dictionary_code": "eng_mizo",
      "dictionary_title": "English to Mizo Dictionary",
      "word": "Faith",
      "phonetic": "feɪθ",
      "definition": "(n.) Rinhlelhlohna, rindana, rinna nghet tak, beisei thil thleng ngei tura rinna.",
      "example": "Have faith in God."
    }
  ]
}
```

---

### 4.3 Daily Highlights Endpoint (`GET /api/v1/daily`)

Auto-generated Scripture verse of the day and word of the day highlights.

#### Request:
`GET https://lushai.dev/api/v1/daily`

#### Example Response (HTTP 200 OK):
```json
{
  "status": "success",
  "website": "BnD by Lushai Dev",
  "date": "2026-08-09",
  "daily_verse": {
    "bible_code": "mizo",
    "bible_name": "Mizo Holy Bible",
    "book": "Johana",
    "chapter": 3,
    "verse": 16,
    "text": "Pathianin khawvel a hmangaih em em a..."
  },
  "daily_word": {
    "dictionary_code": "eng_mizo",
    "dictionary_title": "English to Mizo Dictionary",
    "word": "Faith",
    "phonetic": "feɪθ",
    "definition": "(n.) Rinhlelhlohna, rindana, rinna nghet tak...",
    "example": "Have faith in God."
  }
}
```

---

### 4.4 API Key Management Endpoint (`GET / POST /api/v1/keys`)

Endpoint for authenticated users to view or generate API keys.

#### GET `/api/v1/keys` Response:
```json
{
  "status": "success",
  "authenticated": true,
  "api_key": "bnd_live_a1b2c3d4e5f6...",
  "owner_name": "Lushai Developer",
  "email": "dev@lushai.dev",
  "rate_limit_rpm": 60,
  "is_active": true,
  "created_at": "2026-08-09 10:00:00"
}
```

#### POST `/api/v1/keys` Request Body:
```json
{
  "action": "get_or_create"
}
```

---

## 5. HTTP Status Codes

- `200 OK`: Request succeeded, JSON payload returned.
- `201 Created`: Resource (API Key) created successfully.
- `400 Bad Request`: Invalid parameter format or missing mandatory input.
- `401 Unauthorized`: API Key is missing or invalid.
- `403 Forbidden`: Insufficient user permissions.
- `404 Not Found`: Endpoint or record does not exist.
- `429 Too Many Requests`: Rate limit quota exceeded. Check `X-RateLimit-Reset`.
- `500 Internal Server Error`: Database processing or server failure.

---

## 6. Multi-Language SDK Snippets

### JavaScript (Node.js & Web)
```javascript
const url = "https://lushai.dev/api/v1/bibles?code=mizo&book=John&chapter=3&verse=16";
const apiKey = "YOUR_BND_API_KEY";

async function getVerse() {
  const response = await fetch(url, {
    headers: { "X-API-Key": apiKey }
  });
  const data = await response.json();
  console.log("Mizo Verse:", data.data[0].text);
}
getVerse();
```

### Flutter / Dart
```dart
import 'package:http/http.dart' as http;
import 'dart:convert';

Future<void> fetchWord(String word) async {
  final url = Uri.parse("https://lushai.dev/api/v1/dictionaries?code=eng_mizo&word=$word");
  final response = await http.get(url, headers: {"X-API-Key": "YOUR_BND_API_KEY"});
  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    print("Definition: ${data['data'][0]['definition']}");
  }
}
```

### 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("Daily Highlights:", response.json())
```

---

## 7. Contact & Support
- Official Email: support@lushai.dev
- Developer Portal: https://lushai.dev/docs
- Official Website: https://lushai.dev