ChatBot API
Introducing the 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.
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 |
|---|---|---|
| api_key* | String | Your API key from the DivineAPI dashboard. |
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. Rs 0.30, Rs 0.90, Rs 3.00 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
{
"answer": "Your chart points to a meaningful marriage window active now, especially from August through November 2026, while Venus mahadasha and Mercury antardasha are running...",
"request_id": "req_9f21ab",
"charged_inr": 0.9,
"wallet_inr": 286.7,
"band": "standard",
"grounding": "ok",
"chart_cache": {
"hits": 1,
"misses": 0
},
"latency_ms": {
"chart_fetch": 210,
"time_to_first_token": 640,
"total": 1980
},
"usage": {
"input_tokens": 812,
"output_tokens": 340,
"cached_tokens": 512
}
}
// stream: true
data: {"delta": "Your chart points"}
data: {"done": true, ...}
// guardrail reply — HTTP 200, free
{
"answer": "That is not something I can read from a birth chart...",
"blocked": true,
"charged_inr": 0.0
}Example Code Implementations
Below are example implementations in various programming environments.
cURL
curl https://ask.divineapi.com/chat \
-H "Content-Type: application/json" \
-d '{
"api_key": "Your API Key",
"user_id": "u_8812",
"session_id": "s_5f21",
"message": "When will I get married?",
"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.