Thirukkural API

A developer-friendly REST API for exploring the 1,330 couplets of Thirukkural — with Tamil text, translations, and meanings.

Live App · Swagger UI · OpenAPI specification

Why this project?

Thirukkural is a classic Tamil work of 1,330 couplets covering virtue, prosperity, and love. This project makes that wisdom easy to discover and integrate into applications through a small, serverless-friendly API and a Next.js web experience.

Highlights

Complete collection — retrieve any Kural from 1–1330.
Useful discovery endpoints — daily, random, chapter, section, and keyword search.
Reader-friendly browsing — use the web app’s /browse page or global search icon to find Kurals by number, keyword, section, or chapter.
Rich responses — Tamil couplets plus meanings by Mu. Varadarajan, Solomon Pappayya, Kalaignar, an English translation, and a clearly labeled modern-English interpretation.
Kural Quiz — a fast, self-graded multiple-choice game at /quiz that matches a couplet to its modern meaning, with no AI wait.
AI-assisted exploration — an optional chat experience powered by Ollama or OpenRouter, including quiz-style Q&A.
OpenAPI included — browse the interactive Swagger UI or import the specification into your favorite client.

Quick start

Requirements

Node.js 24.20.0 (see package.json)
npm

Run locally

git clone https://github.com/nramc/thirukkural-api.git
cd thirukkural-api
npm install
npm run dev

Open http://localhost:3000 to view the app. The local API is available under http://localhost:3000/api.

For a production-like local run:

npm run build
npm run start

API at a glance

The production API base URL is https://kural.codewithram.dev/api. Single-Kural, daily, and random endpoints return this core shape:

{
  "number": 1,
  "section": {
    "id": 1,
    "names": {
      "ta": "அறத்துப்பால்",
      "en": "Virtue"
    }
  },
  "chapter": {
    "id": 1,
    "names": {
      "ta": "கடவுள் வாழ்த்து",
      "en": "The Praise of God"
    }
  },
  "kural": [
    "அகர முதல எழுத்தெல்லாம் ஆதி",
    "பகவன் முதற்றே உலகு."
  ],
  "transliteration": [
    "Akara Mudhala Ezhuththellaam Aadhi",
    "Pakavan Mudhatre Ulaku"
  ],
  "meaning": {
    "ta_mu_va": "...",
    "ta_salamon": "...",
    "ta_kalaignar": "...",
    "en": "As the letter A is the first of all letters, so the eternal God is first in the world.",
    "en_modern": "In today’s terms, this means: As the letter A is the first of all letters, so the eternal God is first in the world. For example, it can guide how we speak, learn, make decisions, and treat the people around us."
  }
}

Endpoint	Description
`GET /api/kural/{id}`	Get one Kural by number (`1`–`1330`).
`GET /api/kural?q={keyword}&page=1&limit=10`	Search meanings, including modern-English interpretations, Tamil couplet text, and transliteration. `q` accepts comma-separated keywords. Search requests return `{ results, total, page, limit }`. The `page` and `limit` query parameters default to `1` and `10`, respectively; `total` is the number of matching Kurals before pagination.
`GET /api/kural?section={1\|2\|3}`	Discover Kurals in a section. `chapter` takes precedence when both filters are supplied.
`GET /api/kural?chapter={1..133}`	Discover Kurals in a chapter.
`GET /api/sections`	List sections with stable IDs, localized names, and Kural ranges.
`GET /api/chapters?section={1\|2\|3}`	List chapters, optionally filtered by section, with localized names and Kural ranges.
`GET /api/daily`	Get the date-based Kural of the day.
`GET /api/random`	Get a random Kural.
`GET /api/random?section={1\|2\|3}`	Get a random Kural from a section.
`GET /api/random?chapter={1..133}`	Get a random Kural from a chapter. `chapter` takes precedence over `section`.

Examples

# Get Kural 1
curl https://kural.codewithram.dev/api/kural/1

# Search for Kurals containing a keyword
curl 'https://kural.codewithram.dev/api/kural?q=அறம்&page=1&limit=5'

# Get a random Kural from the Virtue section
curl 'https://kural.codewithram.dev/api/random?section=1'

# Get today's Kural
curl https://kural.codewithram.dev/api/daily

Section ranges are 1 — அறத்துப்பால் / Virtue (1–380), 2 — பொருட்பால் / Wealth (381–1080), and 3 — காமத்துப்பால் / Love (1081–1330).

Taxonomy is stored in public/data/sections.json and public/data/chapters.json as explicit records rather than positional strings. Each record has a stable numeric id, a language-keyed names object, and inclusive firstKural/lastKural boundaries. Add a locale by adding a key to names without changing IDs or Kural records. Kural responses expose structured section and chapter taxonomy references. The source records keep canonical IDs internally for validation and filtering; the IDs are available through these references.

Each Kural also includes a two-item transliteration array corresponding to the two Tamil couplet lines. The current reader-friendly Latin transliterations are sourced from the transliteration1 and transliteration2 fields in the public Thirukkural dataset.

For the complete maintainer workflow, including the required taxonomy updates, interpretation-file format, manifest fields, and validation commands, see Adding a language.

The English chapter labels are based on the ordered chapter metadata in the public Thirukkural dataset; the Tamil labels and Kural ranges remain aligned with this project’s source data.

The meaning.en field is the existing English translation. The meaning.en_modern field is a plain-language modern interpretation and practical takeaway; it is not a literal translation or a quotation from Thiruvalluvar. Modern interpretations are included in keyword search and should be treated as explanatory editorial content.

The complete contract is available in public/openapi/openapi.yaml. The OpenAPI file currently focuses on the core Kural endpoints; search and chat are documented above and in the source route handlers.

Optional AI chat

The /chat page and POST /api/chat route support two providers:

Ollama for local development
OpenRouter for hosted models

Create .env.local (never commit credentials) and configure the provider you want. See .env.example for the repository defaults.

Variable	Required	Purpose
`LLM_PROVIDER`	Yes	`ollama` or `openrouter`.
`LLM_MODEL`	Yes	Model identifier to use.
`LLM_ALLOWED_MODELS`	No	Comma-separated allowlist for server-approved models.
`OLLAMA_BASE_URL`	For Ollama	Ollama server URL.
`LLM_API_KEY`	For OpenRouter	Server-only OpenRouter API key.
`OPENROUTER_SITE_URL`	No	Optional OpenRouter HTTP referer.
`OPENROUTER_APP_NAME`	No	Optional OpenRouter application title.
`OPENROUTER_REASONING`	No	Set to `true` to re-enable full reasoning on OpenRouter models that support it (slower).
`OPENROUTER_PROVIDER_SORT`	No	One of `throughput` (default), `latency`, or `price` — OpenRouter provider routing.
`OPENROUTER_REQUIRE_PARAMETERS`	No	Defaults to `true`; restricts routing to providers supporting the request parameters, including tools.
`OPENROUTER_QUANTIZATIONS`	No	Optional comma-separated quantization allowlist, such as `fp8,bf16`; unset allows all.
`OPENROUTER_IGNORE_PROVIDERS`	No	Optional comma-separated provider slugs to skip when a backend is unreliable.

Example local Ollama configuration:

LLM_PROVIDER=ollama
LLM_MODEL=mistral
OLLAMA_BASE_URL=http://localhost:11434
LLM_ALLOWED_MODELS=mistral

The chat API validates messages, limits context size, and exposes Kural lookup tools so the assistant can answer with source-backed content. Keep LLM_API_KEY server-side and rotate any key that may have been exposed.

To remain on OpenRouter's free tier, use LLM_MODEL=openrouter/free or an explicit model ID ending in :free, and keep LLM_ALLOWED_MODELS aligned with that value. OPENROUTER_REQUIRE_PARAMETERS=true is recommended for this application because the chat exposes Kural tools; set it to false only as an emergency availability fallback. Leave OPENROUTER_QUANTIZATIONS and OPENROUTER_IGNORE_PROVIDERS empty initially, then populate them only after checking the provider and model metadata for the free route you use. These filters can improve consistency but can also reduce free-provider availability.

OpenRouter usage accounting is enabled by the server model resolver. Completed chat requests emit metadata-only chat_generation_usage logs containing request ID, configured provider/model, streaming mode, duration, finish reason, aggregated input/output/total tokens, and—when OpenRouter provides them—the selected provider slug and usage/cost fields. chat_tool_activity step logs include the corresponding per-step token and provider metadata. Prompts, assistant output, tool arguments/results, reasoning details, and API keys are not logged, and provider metadata is not returned to clients. Usage or cost fields may be absent when the upstream free route does not report them.

Prefer a faster, self-graded experience without any AI round-trip? Try the /quiz multiple-choice game, which checks answers instantly using the existing /api/random endpoint.

Project layout

app/
├── api/                 # REST and chat route handlers
├── chat/                # AI chat page
├── quiz/                # Self-graded multiple-choice Kural quiz
├── domain/              # Kural data types and data access
├── service/             # Kural, daily, random, and search services
└── components/          # Shared UI components
lib/ai/                  # Model resolution, policy, and chat tools
public/data/             # Chapters, sections, and 1,330 Kurals
public/openapi/          # OpenAPI YAML and Swagger UI

Developer workflow

npm run lint           # ESLint
npm run typecheck      # TypeScript project check
npm run format:check   # Prettier check
npm run security:check # High-severity npm audit check
npm run verify         # Run the full repository verification suite

npm test is currently a placeholder that exits unsuccessfully because no automated test suite has been wired in yet. Add tests before changing that behavior.

Deploy to Vercel

The app is designed for Vercel. Import the repository into a Vercel project, set the environment variables required by the optional chat feature, and deploy. For CLI deployment:

npm install -g vercel
vercel login
vercel

Set NEXT_PUBLIC_SITE_URL to your canonical public URL when deploying a custom domain so generated metadata and robots configuration can use it.

Contributing

Contributions, corrections, and ideas are welcome. A typical workflow is:

For application bugs, Kural data or translation corrections, and feature ideas, please use the GitHub issue chooser and select the matching template.

Fork the repository and create a focused branch: git checkout -b feature/my-improvement.
Make the change and update documentation when behavior changes.
Run npm run verify (or the relevant checks while developing).
Open a pull request with a clear summary and testing notes.

Please do not commit .env.local, API keys, generated build output, or unrelated formatting changes.

License and credits

The source code in this repository is licensed under the MIT License, which permits free use, modification, and redistribution, including for commercial purposes, subject to the license terms.

The Thirukkural source text, translations, meanings, images, fonts, and other third-party assets may have separate copyright or license terms. Review the applicable attribution and license notices before redistributing those materials.

Built with Next.js, React, TypeScript, and Vercel.

Questions or suggestions? Connect with Ramachandran Nellaiyappan or choose an issue template.

If this project helps you, consider giving it a ⭐ on GitHub.

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.claude/skills		.claude/skills
.github		.github
app		app
components		components
docs		docs
lib		lib
public		public
scripts		scripts
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmrc		.npmrc
.prettierrc.json		.prettierrc.json
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
components.json		components.json
eslint.config.mts		eslint.config.mts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
renovate.json		renovate.json
skills-lock.json		skills-lock.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository navigation

About

Repository files navigation

Thirukkural API

Why this project?

Highlights

Quick start

Requirements

Run locally

API at a glance

Examples

Optional AI chat

Project layout

Developer workflow

Deploy to Vercel

Contributing

License and credits

About

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Thirukkural API

Why this project?

Highlights

Quick start

Requirements

Run locally

API at a glance

Examples

Optional AI chat

Project layout

Developer workflow

Deploy to Vercel

Contributing

License and credits

About

Topics

Resources

Stars

Watchers

Forks

Used by

Contributors

Languages