# OneKural — Full Reference for LLM Agents

This is the comprehensive machine-readable reference for the OneKural API and dataset.
For a concise overview, see: https://onekural.com/llms.txt

---

## About the Thirukkural

The Thirukkural is a 2,000-year-old Tamil text by the poet-saint Thiruvalluvar. It consists of 1,330 couplets (kurals) organized into 133 chapters of 10 verses each, grouped into 3 books:

- **Book 1 — Aram (Virtue):** Ethical conduct, righteousness, domestic life (chapters 1–38, kurals 1–380)
- **Book 2 — Porul (Wealth):** Governance, statecraft, economics (chapters 39–108, kurals 381–1080)
- **Book 3 — Inbam (Love):** Romance, desire, union and separation (chapters 109–133, kurals 1081–1330)

---

## Complete API Reference

Base URL: `https://onekural.com`

### GET /api/kural/{id}

Retrieve a single kural by its numeric ID.

- **Path param:** `id` — integer 1 to 1330
- **Returns:** Kural object (see schema)
- **Example:** `GET /api/kural/1`

### GET /api/kurals?chapter={n}

Retrieve all 10 kurals in a chapter.

- **Query param:** `chapter` — integer 1 to 133
- **Returns:** Array of Kural objects (10 items)
- **Example:** `GET /api/kurals?chapter=1`

### GET /api/kurals/batch?ids={csv}

Retrieve multiple kurals by ID in one request.

- **Query param:** `ids` — comma-separated list of integers (max 100)
- **Returns:** Array of Kural objects ordered by ID
- **Example:** `GET /api/kurals/batch?ids=1,2,3,100,500`

### GET /api/chapters?book={n}

Retrieve all chapters in a book.

- **Query param:** `book` — integer 1, 2, or 3
- **Returns:** Array of Chapter objects
- **Example:** `GET /api/chapters?book=1`

### GET /api/search?q={query}

Full-text search across Tamil, transliteration, and English meanings.

- **Query param:** `q` — string, max 200 characters
- **Returns:** Array of up to 50 matching Kural objects
- **Example:** `GET /api/search?q=education`

### GET /api/openapi

OpenAPI 3.1 specification as JSON.

- **Returns:** Complete OpenAPI spec with all endpoint schemas
- **Also available as YAML:** `GET /openapi.yaml`

---

## Static Data

### All Kurals (JSON)

`GET https://onekural.com/data/kurals.json`

Returns all 1,330 kurals as a JSON array. No authentication required. Recommended for bulk processing, RAG pipelines, or offline indexing.

---

## Data Schemas

### Kural Object

```typescript
interface Kural {
  id: number;                        // 1–1330
  book: number;                      // 1=Aram, 2=Porul, 3=Inbam
  chapter: number;                   // 1–133
  chapter_name_tamil: string;        // Chapter name in Tamil script
  chapter_name_english: string;      // Chapter name in English
  kural_tamil: string;               // Two-line Tamil verse
  transliteration: string;           // Romanized Tamil
  meaning_english: string;           // English translation/meaning
  meaning_tamil: string;             // Tamil meaning (Solomon Pappaiah)
  explanation_english?: string;      // AI-generated detailed explanation (may be null)
  explanation_tamil?: string;        // AI-generated Tamil explanation (may be null)
}

interface Chapter {
  chapter: number;
  chapter_name_tamil: string;
  chapter_name_english: string;
  book: number;
}
```

---

## All 133 Chapters

### Book 1 — Aram (Virtue), Chapters 1–38

| # | English | Tamil |
|---|---------|-------|
| 1 | The Praise of God | கடவுள் வாழ்த்து |
| 2 | The Blessing of Rain | வான் சிறப்பு |
| 3 | The Greatness of Ascetics | நீத்தார் பெருமை |
| 4 | Assertion of the Strength of Virtue | அறன் வலியுறுத்தல் |
| 5 | Domestic Life | இல்வாழ்க்கை |
| 6 | The Good Wife | வாழ்க்கைத் துணைநலம் |
| 7 | The Blessing of Children | மக்கட்பேறு |
| 8 | The Possession of Love | அன்புடைமை |
| 9 | Hospitality | விருந்தோம்பல் |
| 10 | The Utterance of Pleasant Words | இனியவை கூறல் |
| 11 | Gratitude | செய்ந்நன்றி அறிதல் |
| 12 | Impartiality | நடுவு நிலைமை |
| 13 | The Possession of Self-Restraint | அடக்கமுடைமை |
| 14 | The Possession of Decorum | ஒழுக்கமுடைமை |
| 15 | Not Coveting Another's Wife | பிறனில் விழையாமை |
| 16 | The Possession of Patience | பொறையுடைமை |
| 17 | Not Envying | அழுக்காறாமை |
| 18 | Not Coveting | வெஃகாமை |
| 19 | Not Backbiting | புறங்கூறாமை |
| 20 | Not Speaking Profitless Words | பயனில சொல்லாமை |
| 21 | Dread of Evil Deeds | தீவினையச்சம் |
| 22 | Duty to Society | ஒப்புரவறிதல் |
| 23 | Giving | ஈகை |
| 24 | Renown | புகழ் |
| 25 | Compassion | அருளுடைமை |
| 26 | Abstaining from Flesh | புலான்மறுத்தல் |
| 27 | Penance | தவம் |
| 28 | Imposture | கூடா ஒழுக்கம் |
| 29 | The Absence of Fraud | கள்ளாமை |
| 30 | Veracity | வாய்மை |
| 31 | The Restraint of Anger | வெகுளாமை |
| 32 | Not Doing Evil | இன்னாசெய்யாமை |
| 33 | Not Killing | கொல்லாமை |
| 34 | Instability | நிலையாமை |
| 35 | Renunciation | துறவு |
| 36 | Knowledge of the True | மெய்யுணர்தல் |
| 37 | The Extirpation of Desire | அவா அறுத்தல் |
| 38 | Fate | ஊழ் |

### Book 2 — Porul (Wealth), Chapters 39–108

| # | English | Tamil |
|---|---------|-------|
| 39 | The Greatness of Kings | இறைமாட்சி |
| 40 | Learning | கல்வி |
| 41 | Ignorance | கல்லாமை |
| 42 | Listening | கேள்வி |
| 43 | The Possession of Knowledge | அறிவுடைமை |
| 44 | The Correction of Faults | குற்றங்கடிதல் |
| 45 | Seeking the Aid of Great Men | பெரியாரைத் துணைக்கோடல் |
| 46 | Avoiding Mean Associations | சிற்றினஞ்சேராமை |
| 47 | Acting after Due Deliberation | தெரிந்து செயல்வகை |
| 48 | Knowing the Fitting Time | வலியறிதல் |
| 49 | Knowing the Right Place | காலமறிதல் |
| 50 | Selecting and Trusting | இடனறிதல் |
| 51 | Selection and Employment | தெரிந்து தெளிதல் |
| 52 | Selection of the Worthy | தெரிந்து வினையாடல் |
| 53 | Cherishing Kinsmen | சுற்றந்தழால் |
| 54 | Indifference to Favourites | பொச்சாவாமை |
| 55 | Sovereignty | செங்கோன்மை |
| 56 | Cruel Sovereignty | கொடுங்கோன்மை |
| 57 | Absence of Terrorism | வெருவந்தசெய்யாமை |
| 58 | Benignity | கண்ணோட்டம் |
| 59 | Spies | ஒற்றாடல் |
| 60 | Energy | ஊக்கமுடைமை |
| 61 | Idleness | மடியின்மை |
| 62 | Diligence | ஆள்வினையுடைமை |
| 63 | Fortitude in Trouble | இடுக்கண்அழியாமை |
| 64 | The Minister of State | அமைச்சு |
| 65 | Eloquence | சொல்வன்மை |
| 66 | Purity in Action | வினைத்தூய்மை |
| 67 | Strength of Action | வினைத்திட்பம் |
| 68 | Manners of Action | வினை செயல்வகை |
| 69 | The Ambassador | தூது |
| 70 | Conduct in the Presence of the King | மன்னரைச் சேர்ந்தொழுகல் |
| 71 | Considering One's Resources | குறிப்பறிதல் |
| 72 | Knowing the Assembly | அவையறிதல் |
| 73 | Not to be Afraid of the Assembly | அவையஞ்சாமை |
| 74 | The Land | நாடு |
| 75 | The Fortification | அரண் |
| 76 | The Way of Accumulating Wealth | பொருள்செயல்வகை |
| 77 | The Excellence of an Army | படைமாட்சி |
| 78 | Military Spirit | படைச்செருக்கு |
| 79 | Friendship | நட்பு |
| 80 | Friendship Investigated | நட்பாராய்தல் |
| 81 | Old Friendship | பழைமை |
| 82 | Bad Friendship | தீ நட்பு |
| 83 | Unreal Friendship | கூடா நட்பு |
| 84 | Folly | பேதைமை |
| 85 | Ignorance | புல்லறிவாண்மை |
| 86 | Hostility | இகல் |
| 87 | Enmity within | பகை மாட்சி |
| 88 | Knowing the Quality of Hate | பகைத்திறம் தெரிதல் |
| 89 | Enmity | உட்பகை |
| 90 | Not Offending the Great | பெரியாரைப் பிழையாமை |
| 91 | Being Led by Women | பெண்வழிச்சேறல் |
| 92 | Wanton Women | வரைவின் மகளிர் |
| 93 | Not Drinking Palm-Wine | கள்ளுண்ணாமை |
| 94 | Gambling | சூது |
| 95 | Medicine | மருந்து |
| 96 | Nobility | குடிமை |
| 97 | Honour | மானம் |
| 98 | Greatness | பெருமை |
| 99 | Perfectness of Nature | சான்றாண்மை |
| 100 | Courtesy | பண்புடைமை |
| 101 | Fruitless Riches | நன்றியில் செல்வம் |
| 102 | Shame | நாணுடைமை |
| 103 | The Ways of the Great | குடிசெயல்வகை |
| 104 | Farming | உழவு |
| 105 | Poverty | நல்குரவு |
| 106 | Begging | இரவு |
| 107 | Dread of Begging | இரவச்சம் |
| 108 | Meanness | கயமை |

### Book 3 — Inbam (Love), Chapters 109–133

| # | English | Tamil |
|---|---------|-------|
| 109 | The Pre-Nuptial Love | தகையணங்குறுத்தல் |
| 110 | Recognition of the Signs of Love | குறிப்பறிதல் |
| 111 | The Delight of Reunion | புணர்ச்சி மகிழ்தல் |
| 112 | Declaration of Love's Special Pleasures | நலம் புனைந்துரைத்தல் |
| 113 | The Abandonment of Reserve | காதற்சிறப்புரைத்தல் |
| 114 | The Publication of Love | நாணுத் துறவுரைத்தல் |
| 115 | The Separation Unendurable | அலர் அறிவுறுத்தல் |
| 116 | Separation Endured | பிரிவாற்றாமை |
| 117 | Complaint of the Loneliness of Night | படர்மெலிந்திரங்கல் |
| 118 | The Eye Bewailing | கண் விதுப்பழிதல் |
| 119 | Pallor Caused by Love Longing | பசப்புறு பருவரல் |
| 120 | The Solitary Anguish | தனிப்படர் மிகுதி |
| 121 | Memories | நினைந்தவர் புலம்பல் |
| 122 | The Vision in the Dream | கனவுநிலை உரைத்தல் |
| 123 | Laments in the Evening | பொழுதுகண்டிரங்கல் |
| 124 | The Wasting Away | உறுப்பு நலனழிதல் |
| 125 | The Soliloquy | நெஞ்சொடு கிளத்தல் |
| 126 | Dread of Ill Repute | நிறையழிதல் |
| 127 | The Longing for Reunion | அவர்வயின் விதும்பல் |
| 128 | The Reading of Signs | குறிப்பறிவுறுத்தல் |
| 129 | Longing in Absence | புணர்வு விதும்பல் |
| 130 | Expostulation with Oneself | நெஞ்சொடு புலத்தல் |
| 131 | Sulking | புலவி |
| 132 | The Pleasures of Temporary Variance | புலவி நுணுக்கம் |
| 133 | The Absence of Sulking | ஊடலுவகை |

---

## Integration Examples

### Fetch a single kural (JavaScript)
```javascript
const res = await fetch('https://onekural.com/api/kural/1');
const kural = await res.json();
console.log(kural.kural_tamil);
console.log(kural.meaning_english);
```

### Fetch all kurals for RAG indexing (JavaScript)
```javascript
const res = await fetch('https://onekural.com/data/kurals.json');
const kurals = await res.json(); // Array of 1,330 Kural objects
```

### Search kurals (curl)
```bash
curl "https://onekural.com/api/search?q=education"
```

### Batch fetch (curl)
```bash
curl "https://onekural.com/api/kurals/batch?ids=1,100,500,1000,1330"
```

---

## Notes for AI Agents

- All 1,330 kurals are public (no auth required for read)
- `data/kurals.json` is a static file — no rate limiting, safe for bulk fetching
- The daily kural is computed deterministically from the date (no DB needed): see `src/lib/kurals.ts`
- Each kural page at `/kural/{id}` contains JSON-LD structured data (schema.org CreativeWork)
- Source code: https://github.com/tharunsuresh-code/onekural