AI Astrologers

Build conversational astrology experiences with AI astrologers that compute real Vedic birth charts before responding — no generic horoscopes. Two modes available: text-based Chat and real-time Voice calls. Both support single-chart (one person) and two-chart (compatibility/matching) sessions.

How it works

Every AI astrologer session is anchored to a real birth chart. When you open a session with birth details, the system computes a full Vedic kundli — planets, houses, dashas, transits, divisional charts — and the astrologer draws on that data for every response. The chart is computed once at session start and carried through the entire conversation automatically.

Session flow:

1. Call /start (or /match-start for two charts) with birth details + astrologer key.
2. Server computes the chart, returns a session_id and the astrologer’s opening greeting.
3. For each user message, call /message with the session_id — the chart context travels with the session.
4. Each response includes the reply, suggested follow-up prompts, and a billing summary.

Available astrologers

Pass the astrologer key when starting a session. Each astrologer has a distinct persona and specialization — it requests only the astrological data relevant to its domain, keeping responses focused and fast.

Chat vs Voice

Both modes share the same underlying astrological engine and session model. The difference is the transport and output format.

Full endpoint references: AI Chat documentation →  |  AI Voice documentation →

Authentication

All AI astrologer endpoints require an API key via the X-Api-Key header.

See authentication for security considerations and key rotation.

Billing

Every AI response includes a billing object reporting the cost of that turn and your remaining wallet balance. All monetary values are in minor units (paise for INR, cents for USD).

Language support

The astrologer picks its response language using a three-priority system:

Hinglish (mixed Hindi-English) is supported naturally — the astrologer matches the user’s register.

Common errors

Error response format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Unknown astrologer: xyz. Available: guruji, love_guru, career_expert, health_expert, transit_expert"
  }
}

Endpoint references

• AI Chat (Text) — start, message, match-start
• AI Voice (Call) — start, message, match-start, realtime-token