✋ Palmistry API and 🎧 Audio Reports API are now live. Ship them in your app today.

Guides

Integrate Astro Chat into your app

Astro Chat turns a saved birth profile into a personalized Kundli, Western, or compatibility conversation. Your product sends a question, receives an answer, and keeps the returned session ID for follow-ups.

Choose the conversation type

ExperienceProfileWhen to use it
Kundli Chatap: KUNDLI, ac: VEDICA personalized Vedic conversation for one person.
Western Chatap: KUNDLI, ac: WESTERNA personalized Western astrology conversation for one person.
Compatibility Chatap: MATCHINGA relationship conversation using two birth profiles.
Chat calls use an access token, not the User ID and API key pair used by subscription endpoints. Keep that token on your server. Never send it to a browser or mobile client. See the access token usage guide before you begin.

New accounts receive test credits. The token belongs in an environment variable such as ASTROLOGYAPI_TOKEN, and your server adds it as the x-astrologyapi-keyheader. A browser, mobile bundle, or public repository is never a safe place for this token.

How the flow works

  1. Collect or load a saved birth profile.
  2. Send the profile and question from your backend to the Chat API.
  3. Store the returned sid against the user's chat session.
  4. Send the same sid on the next question to continue the conversation.

Step 1: make your first request

All chat types use POST https://json-chat.astrologyapi.com/api/chat. For a personalized chart conversation, set ap to KUNDLI, then choose VEDIC or WESTERN with ac.

curl --location 'https://json-chat.astrologyapi.com/api/chat' \
  --header 'Content-Type: application/json' \
  --header 'x-astrologyapi-key: <YOUR_ACCESS_TOKEN>' \
  --data '{
    "language": "en",
    "name": "David",
    "day": 1,
    "month": 11,
    "year": 2005,
    "hour": 19,
    "min": 45,
    "place": "Mumbai",
    "lat": "19.17",
    "lon": "73.7",
    "tzone": "5.5",
    "gender": "male",
    "country": "INDIA",
    "ap": "KUNDLI",
    "ac": "VEDIC",
    "ep": "STANDARD",
    "sid": "",
    "q": "What does my Moon sign say about me?"
  }'

Read the response

Render response as the assistant reply. Savesession_id; it is the server-issued key that carries the conversation forward.

{
  "success": true,
  "session_id": "5ec38d54-6f24-4efc-b8ba-30b36cdd6591",
  "message_id": 1,
  "query": "What does my Moon sign say about me?",
  "response": "Based on your birth details, your Sun is in Scorpio..."
}
FieldPurpose
qThe user's question.
languageThe response language code, such as en.
name, gender, countryThe person's basic details for a one-person conversation.
day, month, year, hour, minBirth date and time. Use the 24-hour clock for hour.
sidEmpty for the first message; reuse the returned value afterward.
epExpertise level: STANDARD, ADVANCED, ULTRA_FAST or EXPERT.
lat, lon, tzoneThe birth location and decimal timezone offset.

Step 2: persist the session ID

The response contains the answer in response and a conversation ID in session_id. Persist that value with the selected profile and send it with every follow-up question. Create a new session when the user changes profile or starts a new topic. For specialist chat, save the selected ap with the session and start a new session when switching personas.

  1. First question: send an empty sid.
  2. Save the returned ID with the selected user and profile.
  3. Follow-up: send the exact same ID with the new q.
  4. New person or deliberately fresh chat: discard the old ID and start empty.

Step 3: call the API from your backend

Your frontend should call your own route, which validates the request and forwards it with the server-held token. This compact Node 18+ example returns only the response fields your chat UI needs.

// Node 18+ route handler. Keep the token on your server.
const CHAT_URL = 'https://json-chat.astrologyapi.com/api/chat'

export async function askAstroChat({ question, sid = '', profile }) {
  const response = await fetch(CHAT_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-astrologyapi-key': process.env.ASTROLOGYAPI_TOKEN,
    },
    body: JSON.stringify({
      ...profile,
      ap: 'KUNDLI',
      ac: 'VEDIC',
      ep: 'STANDARD',
      sid,
      q: question,
    }),
  })

  const data = await response.json()
  if (!response.ok || !data.success) throw new Error('Chat service unavailable')

  return { reply: data.response, sid: data.session_id }
}

Connect the frontend

Keep the session ID in client state while the chat is open. Your backend should still own the token and the final profile validation.

let sid = ''

async function sendMessage(question, profile) {
  const response = await fetch('/api/my-astro-chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ question, sid, profile }),
  })

  const data = await response.json()
  if (!response.ok) throw new Error(data.error || 'Chat failed')

  sid = data.sid // send this on the next message
  return data.reply
}
Use per-user rate limits on this route. Chat usage draws from your wallet, so rate limiting protects your balance as well as your users' experience.

Step 4: add compatibility chat

For relationship questions, set ap to MATCHING and send both birth profiles using the f_ and m_ fields. The same session-ID pattern applies.

Do not turn two individual readings into a scientific compatibility score. Use the conversation to explain similarities, contrasts, and traditional relationship themes with clear entertainment-oriented framing.

{
  "ap": "MATCHING",
  "sid": "",
  "q": "What should we understand about this relationship?",
  "f_first_name": "Asha",
  "f_day": 10,
  "f_month": 5,
  "f_year": 1994,
  "f_hour": 9,
  "f_minute": 30,
  "f_latitude": 19.07,
  "f_longitude": 72.88,
  "f_timezone": 5.5,
  "f_place": "Mumbai",
  "m_first_name": "Rohan",
  "m_day": 3,
  "m_month": 8,
  "m_year": 1992,
  "m_hour": 18,
  "m_minute": 15,
  "m_latitude": 28.61,
  "m_longitude": 77.21,
  "m_timezone": 5.5,
  "m_place": "Delhi"
}

Specialist personas — One chart. Twelve experts.

Pick a focused astrologer for your user's question. Each persona reads only the parts of the Vedic chart that matter for its topic and answers with chart evidence and a date window.

These are 12 new values for ap. The endpoint, access-token authentication, pd birth-profile structure and response format stay the same.

apTitleCovers
CAREERCareer & EmploymentBest-fit work, job change, promotion, career timing
WEALTHWealth & MoneyIncome sources, savings, dhana yogas, money timing
LOVELove & DatingAttraction patterns, partner needs, compatibility
MARRIAGEMarriageMarriage timing, spouse nature, Manglik, Ashtakoot match
EDUCATIONEducation & StudiesLearning style, subject fit, higher / foreign study
REMEDIESRemedies & DoshasActive doshas, gemstones, Lal Kitab and Vedic remedies
PERSONALITYPersonalityStrengths, blind spots, how others see you
CREATIVITYCreativityCreative medium, blocks, creativity as income
EMOTIONALEmotional PatternsMoon-based emotional nature, today's mood
PAST_LIFEPast Life & KarmaSymbolic reading of Ketu, 12th house, D60
SPIRITUALITYSpirituality & PurposeSpiritual path, dharma, inner-shift timing
DASHA_TRANSITDashas & TransitsCurrent / next dasha, Sade Sati, eclipses

Persona rules

  • Vedic only. Send ac: "VEDIC" or leave ac out. WESTERN returns 400 for specialist personas.
  • Partner chart. pd.partner is used by LOVE and MARRIAGE only.
  • One persona per session. Keep the same ap for a sid. Start a new session to switch personas. Off-topic questions get a redirect to the right persona.
  • Gender is strongly recommended. Include gender in pd. It changes marriage and matching readings.

Send a specialist question

Send this body to the same Chat API endpoint with the same server-held access token. This example omits ac to use Vedic. Keep birth details inside pd.

{
  "q": "Which field suits me best?",
  "ap": "CAREER",
  "pd": {
    "name": "Sita Devi",
    "gender": "female",
    "language": "en",
    "day": 15,
    "month": 8,
    "year": 1990,
    "hour": 10,
    "min": 30,
    "lat": 28.6139,
    "lon": 77.209,
    "tzone": 5.5,
    "place": "New Delhi"
  }
}

Reuse the returned session_id as sid and keep ap: CAREER for follow-up questions. Read the answer from response as before.

Handle production cases

  • Missing or invalid token: return a friendly authentication message; never expose the token or upstream response body.
  • Invalid birth details: validate every required field before calling the API and keep the user's draft intact for correction.
  • Upstream failure: check both the HTTP status and success in the response body before displaying a reply.
  • Wallet protection: rate-limit per user and record each call, especially before opening chat to anonymous traffic.
  • Privacy: explain why birth data is collected, who can access it, and how a user can delete a saved profile.

Get birth data right

An incorrect timezone changes the computed chart behind the conversation. Resolve the place into coordinates and the correct decimal offset instead of asking users to type them. Follow the birth time and timezone guide for the required handling of DST and historical birth dates.

Where to go next