Skip to main content

​
GET /api/daily

Get a personalized daily verse for the authenticated user. The system intelligently selects verses based on what the user has already seen, preferring unseen verses.

​
Authentication

Requires Clerk authentication. Include authentication headers with the request.

​
Query Parameters

​
tz
string
User’s timezone (e.g., “America/New_York”, “Asia/Kolkata”). Defaults to “UTC” if not provided. Used to determine what “today” means for the user.

​
How It Works

  1. Checks if a daily verse has already been generated for the user today (based on their timezone)
  2. If cached, returns the cached verse
  3. If not cached:
    • Analyzes the user’s query history to find seen verses
    • Selects a random unseen verse (or any random verse if all have been seen)
    • Fetches the full verse details from the backend
    • Caches the result for the rest of the day

​
Response

​
chapter
integer
Chapter number (1-18)
​
verse
integer
Verse number
​
translation
string
English translation of the verse
​
summarized_commentary
string
Commentary or summary for the verse
​
cached
boolean
Whether this verse was retrieved from cache (true) or newly generated (false)

​
Response Example

{
  "chapter": 6,
  "verse": 5,
  "translation": "One must deliver oneself through one's own efforts, not degrade oneself. The mind is both friend and enemy of the self.",
  "summarized_commentary": "This verse emphasizes self-reliance and the dual nature of the mind in spiritual practice.",
  "cached": false
}

​
Cached Response Example

{
  "chapter": 6,
  "verse": 5,
  "translation": "One must deliver oneself through one's own efforts, not degrade oneself. The mind is both friend and enemy of the self.",
  "summarized_commentary": "This verse emphasizes self-reliance and the dual nature of the mind in spiritual practice.",
  "cached": true
}

​
Error Responses

Status CodeDescription
401Unauthorized - authentication required
429Rate limit exceeded (10 requests per minute)
500Failed to get daily verse
503Database not configured

​
Rate Limiting

10 requests per minute per client

​
Code Examples

curl -X GET "https://gitachat.org/api/daily?tz=America/New_York" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Smart Verse Selection

The daily verse feature uses intelligent selection:
  • Prioritizes unseen verses: Checks user’s query history to avoid repetition
  • Falls back gracefully: If all 703 verses have been seen, randomly selects any verse
  • Timezone-aware: Same “today” across all requests from the same timezone
  • Cached per day: Once generated, the same verse is returned for the entire day (in user’s timezone)

​
Caching Behavior

  • Verses are cached in the daily_verse table
  • Cache key: user_id + date (formatted as YYYY-MM-DD in user’s timezone)
  • Cache duration: Until midnight in the user’s timezone
  • The cached field indicates if the verse was retrieved from cache

​
Use Cases

  • Daily meditation or reflection apps
  • Morning/evening verse notifications
  • Spiritual practice tracking
  • Progressive learning through the Gita (preferring unseen verses)

​
Performance Notes

  • First request of the day: ~15 seconds (fetches from backend)
  • Subsequent requests: less than 100ms (retrieved from cache)
  • Backend timeout: 15 seconds
  • Uses abort controller to prevent hanging requests

Build docs developers (and LLMs) love

Get started for freeTalk to us