Old words.
Fresh perspective.

Your first request

Use GET with the full URL below. No account or key is needed on a public deployment. The ID uses chapter.verse: 10.15 means chapter 10, verse 15.

/api/v1/verses/10.15

1. Open the URL in a browser, or call it with fetch().
2. Parse the JSON and read payload.data.
3. Display text.lines_ta, text.meaning_ta and text.english_meaning.

Prefer a page? Open /read/10.15. Prefer plain text? Add ?format=text to a single-verse or daily endpoint. Keep the slash between your domain and /api.

Understand the response

Standard JSON responses contain data and meta. The location of the verses depends on the endpoint; use the shape column in the reference below.

{
  "data": {
    "id": "10.15",
    "chapter": 10,
    "verse": 15,
    "text": {
      "transliteration_ta": "…",
      "meaning_ta": "…",
      "lines_ta": ["…", "…"],
      "english_meaning": "People can share a chapter of life and then go their separate ways, like birds leaving the same tree in the morning. Appreciate the time together; moving on is natural, even when it hurts."
    },
    "topics": ["resilience"]
  },
  "meta": {
    "api_version": "1.2.0",
    "dataset_version": "…",
    "developed_by": "Shyam"
  }
}

Parse JSON before displaying it. Use the line array for verse layout and textContent for safe HTML insertion.

Complete endpoint reference

Every API request below uses GET. Paths are relative to this website's domain. “Try” runs a real example in the playground.

Website routes: / is the homepage; /docs and /api/docs show this guide; /read/{id} opens a verse reader. Use the chapter index to find valid IDs; unavailable numbers return 404.

Parameters, defaults and limits

“Filters” means chapter, topic and review. Combine them on browse, daily, random and export endpoints.

Use only the parameters listed for an endpoint. Unsupported names, duplicate parameters and invalid values return 400. Integers must be positive whole numbers. Search is case-insensitive keyword matching, not semantic search; related verses share topic tags.

/api/v1/verses?chapter=1&topic=money&page=1&limit=5
/api/v1/verses?q=learning%20patience&match=any&limit=5
/api/v1/daily?date=2026-10-08&topic=resilience
/api/v1/random?chapter=10&count=2

Copy-and-run examples

cURL — get a verse

curl '/api/v1/verses/10.15'

JavaScript — render Tamil and English

Add <div id="verse"></div> to your HTML. This example checks errors and inserts text safely.

JavaScript — search with encoded query values

Python — print a verse

Uses Python's standard library. On Windows, use a UTF-8 terminal for Tamil.

Pagination and downloads

Browse and chapter responses return page, limit, total, pages and has_next in data.pagination. Start at page 1, increment the page, and stop when has_next is false. Keep the same query and filters between pages. Zero matches give an empty results array and pages: 0.

For the whole collection, request /api/v1/export. The JSON download uses records, not data. Add filters to export a subset. For NDJSON, split the response into nonempty lines and parse each line individually.

Errors, access and caching

{
  "error": {
    "code": "VERSE_NOT_FOUND",
    "message": "Requested verse number is unavailable.",
    "request_id": "…"
  }
}

Using an optional key

If the owner enables a key, all /api/v1 requests require it. The homepage, guide, image and health endpoint stay public. Keep a private key on your server.

Browser access

CORS allows any origin by default; an owner can restrict allowed origins. Use URLSearchParams to encode Tamil queries. The API does not use cookies.

Conditional requests

Most public responses have a short cache lifetime and an ETag. Save the ETag and send it as If-None-Match; a 304 has no JSON body. Random, health and key-protected responses use no-store. HEAD returns the same headers as GET without the body. The response header x-request-id helps identify a request.