Astro ChatBot API
Introducing the Astro ChatBot API, a simple and reliable way to let users ask any astrology question in plain language and get one grounded, chart-based answer back. You send a question and the person's birth details; DivineAPI fetches and compresses their chart, and streams back an answer written for a reader, not a developer. This API is designed for websites, mobile apps, chatbots, CRM dashboards, or astrology portals that want a conversational astrology experience instead of static reports.
It supports seven endpoints: one to ask a question inside a stored conversation, four to manage and inspect those conversations and your account, and one liveness check.
API Endpoint
POST https://ask.divineapi.com/chatGuide: Ask a question inside a conversation DivineAPI stores for you. Send the birth details once and DivineAPI holds them for that session_id — every later message in the same session can omit them. Follow-ups like “and my career?” or “what about him?” resolve on their own because the thread is kept server-side. Charged only when an answer succeeds; failures and guardrail replies cost nothing.
Authentication
Every request requires two headers:
| Header | Description |
|---|---|
Authorization | Bearer {api_acc_token} - identifies the user |
x-api-key | Use api_key |
Supported Language Codes
This API supports a wide range of languages. Pass the language code in the language field in the request body.
| Code | Language |
|---|---|
auto | Detect automatically from the person's message |
| English | English (default) |
| Hindi | Hindi |
| Tamil | Tamil |
| Spanish | Spanish |
| ... | Any other language name — e.g. Bengali, Japanese, Arabic |
Guide: Leaving language unset defaults to English. Setting it to auto replies in whatever language and script the person wrote in — this suits a mixed audience but is a judgement the model makes per message rather than a guarantee.
Headers
| Name | Type | Description |
|---|---|---|
Content-Type* | String | application/json. Example: Content-Type: application/json |
Fields marked with * are mandatory.
Request Body
| Name | Type | Description |
|---|---|---|
user_id* | String | Your ID for the end user. Recorded on every request and used for usage reporting. |
session_id* | String | Your ID for this conversation. A new ID starts a fresh thread. |
message* | String | What the user typed, in any language. |
full_name | String | Used to address the person by name. Needed once per session. |
day* | String | Day of birth, 01 to 31. Needed once per session. |
month* | String | Month of birth, 01 to 12. Needed once per session. |
year* | String | Year of birth, e.g. 1996. Needed once per session. |
hour* | String | Hour of birth, 00 to 23, 24-hour clock. Needed once per session. |
min* | String | Minute of birth, 00 to 59. Needed once per session. |
sec | String | Second of birth, 00 to 59. Rarely needed. Default 0. |
gender* | String | male or female. Used by some traditional calculations. Needed once per session. |
place* | String | Birth city, e.g. New Delhi. Shown back to the user. Needed once per session. |
lat* | String | Latitude of the birth city, e.g. 28.7041. Needed once per session. |
lon* | String | Longitude of the birth city, e.g. 77.1025. Needed once per session. |
tzone* | String | Hours ahead of UTC at the time of birth, e.g. 5.5. Needed once per session. |
stream | Boolean | Stream the answer as it is written, rather than waiting for all of it. Default false. |
depth | String | quick, standard, or deep. How much of the chart is read before answering. 20, 30, 50 credits per answer respectively. Default standard. |
length_cap | String | short, medium, or full. Ceiling on how long the answer may be. Default medium. |
language | String | auto, or any language name, e.g. Hindi, Tamil, Spanish. Default English. |
school | String | western, vedic, kp, or lalkitab. Which tradition the reading follows. Default western. |
lens | String | general, career, love, health, money, or spiritual. Which area of life to read the chart through. Default general. |
confidence | String | balanced, definitive, or careful. How strongly claims are stated. Default balanced. |
sensitivity | String | standard or strict. Use strict for matrimony and relationship products. Default standard. |
tone | String | Free text, e.g. “calm and practical”, “playful, like a close friend”. How the astrologer sounds. Default warm, friendly. |
framing | String | Free text, e.g. “honest but hopeful”, “never sugar-coat it”. Its attitude to difficult placements. Default empowering. |
assistant_name | String | Free text, e.g. “Guru ji”, “Tara”. What your astrologer calls itself. |
brand_voice | String | Free text, e.g. “We speak plainly and never frighten people about their chart”. A line of personality in your brand's words. |
sign_off | String | Free text, e.g. “With light, Team Tara”. A closing line added to the end of every answer. |
style_notes | String | Free text, max 500 chars. Anything the parameters above do not cover — e.g. “Never name Sade Sati directly.” |
200: OK Answered Successfully
{
"request_id": "8f3c72b94f714ef5",
"answer": "Your most promising job window is from late October 2026 through early 2027, with applications and interviews gaining traction from October onward. Your progressed Moon in Virgo in the 7th house favors one-to-one interviews and agreements, while your natal Moon in Leo in the 11th house points to referrals, networking, and professional connections.\n\nThere may be some delay or extra requirements because transiting Saturn is square your natal Jupiter in the 4th house, but this can lead to a more stable role. Focus especially on referrals, former colleagues, and direct conversations rather than relying only on online applications.",
"band": "standard",
"credits_charged": 30,
"credits_remaining": 92020
}
Example Code Implementations
Below are example implementations in various programming environments.
cURL
curl --location 'https://ask.divineapi.com/chat' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {api_acc_token}' \
--header 'x-api-key: {api-key}' \
--data '{
"user_id": "u_8812dwqdq",
"session_id": "session090091",
"message": "When will I get job?",
"depth": "standard",
"full_name": "Priya Sharma",
"day": "24",
"month": "05",
"year": "1996",
"hour": "14",
"min": "40",
"gender": "female",
"place": "New Delhi",
"lat": "28.7041",
"lon": "77.1025",
"tzone": "5.5"
}'Notes and Best Practices
Always send the correct timezone so the API can match the correct day to the user’s region.
Send birth details once per session_id and reuse that ID for every follow-up message in the same conversation — do not resend them each time.
Do not invent a birth time if the user doesn't know theirs. Birth time changes the ascendant, the houses and every dasha date; a guessed time produces a confident and wrong answer rather than an honest error.
You can keep api_key server-side and reuse the same wallet across all your users — it is not per-user.