AstroSage API: Build an AstroSage-Like Astrology Chat App or Bot

If you are searching for an AstroSage API, you are usually trying to build one of three products:

1. An astrology chat app that answers birth chart questions.
2. A WhatsApp, Telegram, Discord, or website astrology bot.
3. A full astrology platform with Vedic chart, dasha, Panchang, match making, horoscope, and compatibility features.

FreeAstroAPI is not affiliated with AstroSage. The useful point for builders is architectural: our Vedic and astrology endpoints were calibrated to return production-grade structured results, with quality and coverage suitable for AstroSage-like user experiences.

That means you do not need to make an LLM invent chart math. Use the API for deterministic astrology data, then use your AI layer to explain that data in a conversational voice.

Why an AstroSage-like app needs structured astrology data

Astrology chat products fail when the bot tries to calculate everything from a prompt. The model may sound confident while getting the ascendant, Moon Nakshatra, Vimshottari dasha, Panchang, or compatibility details wrong.

A better production pattern is:

1. Resolve the user's city, timezone, latitude, and longitude.
2. Call astrology endpoints for chart, dasha, Panchang, transit, or compatibility data.
3. Store the structured response as the source of truth.
4. Let the chat model explain only what the API returned.
5. Keep citations or internal references to the exact endpoint payload used.

This gives your app the feeling of an intelligent astrology assistant while keeping calculations deterministic and repeatable.

Best endpoints for an AstroSage-style chat app

For an AstroSage-like Vedic bot, start with these endpoints:

Use POST /api/v2/vedic/calculate when you want one compact onboarding payload. Use the specialized endpoints when a chat turn needs one focused answer, such as "What dasha am I in?" or "Is today good for starting something?"

Recommended MCP chat pipeline

If you are building the app as an AI agent, use the hosted MCP layer or your own tool-calling layer instead of wiring every endpoint directly into the prompt.

The pipeline should look like this:

1. Analyze the user's question and decide what astrology fact is needed.
2. Check whether the needed JSON already exists in cache.
3. If not cached, choose the right MCP tool or API endpoint.
4. Call the tool with the user's stored birth data and the current question context.
5. Cache the raw JSON response with the endpoint, input hash, user id, and generated timestamp.
6. Give the AI the user's question plus only the relevant cached JSON.
7. Ask the AI to write the final answer from that JSON, without inventing missing chart facts.

In practice, the first AI pass is a router. It should not answer the user yet. It should return a small tool plan:

{
  "intent": "current_dasha_question",
  "needs_tool": true,
  "tool": "vedic_dasha",
  "cache_key": "user_123:vedic_dasha:2026-04-24:lahiri",
  "reason": "The user asked which dasha is active today."
}

Then your backend executes the tool call, stores the JSON, and makes a second AI call to write the user-facing response.

User question:
{question}

Tool JSON:
{cached_or_fresh_json}

Instruction:
Answer only from the Tool JSON. If the JSON does not contain the requested fact, say what additional tool or birth detail is needed.

This design is more reliable than asking the model to decide, calculate, and explain in one pass.

Cache strategy

Cache by user, endpoint, normalized input, and date or date range.

Always store the full raw JSON. You can also store a smaller "facts" object for retrieval, but keep the original response for debugging and answer audits.

Follow-up handling

Follow-up messages should reuse context before calling another tool. A good router checks the previous user question, the last tool JSON, and the new message.

The key is to separate three things: conversation memory, cached astrology facts, and fresh tool calls. Follow-ups often need memory and cached facts, not another API request.

All public astrology endpoints

These are the main endpoints you can combine when building an astrology assistant, horoscope bot, chart app, or AstroSage-like experience.

Vedic astrology endpoints

Western astrology endpoints

Chart rendering and visual endpoints

Astrocartography endpoints

Horoscope and simple sign endpoints

Chinese astrology endpoints

Utility and platform endpoints

Step-by-step: build the chat app

Step 1: collect birth data once

Your onboarding form should collect:

• Name
• Date of birth
• Time of birth
• Birth city
• Latitude and longitude when available
• Timezone, or AUTO

For production, coordinates are better than city names because many cities share the same name. Use city search to help users choose the right place.

curl -G "https://api.freeastroapi.com/api/v2/geo/search" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "q=Mumbai" \
  --data-urlencode "country=IN" \
  --data-urlencode "limit=5"

Step 2: create the user's core Vedic profile

Call the full calculate endpoint after onboarding. Store the response in your database as the user's astrological profile.

curl -X POST "https://api.freeastroapi.com/api/v2/vedic/calculate" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "year": 1994,
    "month": 8,
    "day": 11,
    "hour": 6,
    "minute": 42,
    "city": "Mumbai",
    "lat": 19.0760,
    "lng": 72.8777,
    "tz_str": "AUTO",
    "ayanamsha": "lahiri",
    "vargas": [1, 9, 10],
    "include_yogas": true,
    "include_panchang": true,
    "include_shadbala": true,
    "include_ashtakavarga": true,
    "dasha_levels": 3
  }'

This gives the chat app enough structured data for common questions like:

• "What is my Lagna?"
• "What is my Moon Nakshatra?"
• "Which dasha am I running?"
• "Do I have strong career yogas?"
• "What does my D9 say about marriage?"

Step 3: route each user question to the right endpoint

Do not call every endpoint on every chat message. Classify the intent first.

This keeps latency and cost under control.

Step 4: pass structured facts into the LLM

The prompt should tell the LLM to explain the API payload, not recalculate it.

You are an astrology assistant for a Vedic astrology app.
Use only the structured API facts below.
Do not invent planetary positions, dashas, Nakshatras, yogas, or compatibility scores.
If the needed fact is missing, ask for the missing input or say that this endpoint was not called.

User question:
{user_message}

FreeAstroAPI facts:
{json_from_relevant_endpoint}

For better answers, use fact endpoints such as dasha insights and Gochar timeline insights. These payloads are already shaped for retrieval, ranking, and explanation.

Step 5: add memory without changing the chart

Separate permanent chart facts from conversation memory.

• Permanent facts: birth data, chart positions, dasha timeline, vargas, Panchang at birth.
• Session memory: preferred language, tone, current goal, relationship context, recent questions.
• Fresh facts: today's Panchang, current dasha, current Gochar, daily horoscope.

This avoids a common bug where the assistant starts treating a previous interpretation as if it were a new chart fact.

Step 6: build safe answer templates

For user trust, every chat answer should have a predictable shape:

1. Direct answer in one or two sentences.
2. Evidence from the API payload.
3. Practical interpretation.
4. Optional next question or action.

Example:

You are currently in Moon Mahadasha and Saturn Antardasha.
The API dasha payload shows Moon as the active Mahadasha lord and Saturn as the active sub-period lord for the selected reference date.
This usually focuses the reading on emotional security, home, responsibility, and long-term discipline.
If you want, I can compare this dasha with your current Gochar timeline.

Suggested app architecture

Use a small backend between your frontend and FreeAstroAPI.

User interface
  -> Your backend chat route
  -> Intent classifier
  -> FreeAstroAPI endpoint call
  -> Structured payload store
  -> LLM response generation
  -> Chat answer with endpoint-backed facts

Never expose your API key directly in browser JavaScript. Keep x-api-key on your server and call your own backend from the client.

Minimal Node.js server example

const API_BASE = "https://api.freeastroapi.com";

async function getVedicProfile(birthData: Record<string, unknown>) {
  const response = await fetch(`${API_BASE}/api/v2/vedic/calculate`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.FREEASTROAPI_KEY || "",
    },
    body: JSON.stringify({
      ...birthData,
      tz_str: "AUTO",
      ayanamsha: "lahiri",
      vargas: [1, 9, 10],
      include_yogas: true,
      include_panchang: true,
      include_shadbala: true,
      include_ashtakavarga: true,
      dasha_levels: 3,
    }),
  });

  if (!response.ok) {
    throw new Error(`FreeAstroAPI request failed: ${response.status}`);
  }

  return response.json();
}

SEO title and content strategy for your astrology bot

If you are publishing your app publicly, create landing pages around real search intent:

• "AstroSage API alternative"
• "Vedic astrology API"
• "Kundli API for developers"
• "Dasha API"
• "Panchang API"
• "Astrology chatbot API"
• "Build an astrology bot"

Each page should explain the exact feature, show a live example, list the endpoint used, and link to the relevant documentation. Avoid vague AI astrology claims. Users and search engines both respond better to concrete features.

Common mistakes to avoid

1. Do not let the LLM calculate charts from raw birth data.
2. Do not ignore timezone and historical location handling.
3. Do not call expensive endpoints on every message.
4. Do not mix Western and Vedic concepts without labeling the system.
5. Do not present generated interpretation as deterministic chart data.
6. Do not store only the final text response. Store the API payload too.

Start building your AstroSage-like app

FreeAstroAPI gives you the calculation layer for Vedic charts, dasha, Panchang, compatibility, Gochar, horoscopes, Western charts, synastry, moon data, and chart rendering.

Start with the Vedic calculate endpoint, add dasha and Panchang chat intents, then expand into compatibility, Gochar, and daily horoscope features.