Ask Divine

API Reference

One question in, one grounded astrology answer out. You send a question and the person's birth details; we fetch and compress their chart, and stream back an answer written for a reader, not a developer.

POST	/chat	Ask a question inside a conversation we keep for you
POST	/ask	Ask a one-shot question, no session stored
GET	/sessions	List conversations under your key
GET	/session/{session_id}	Full history of one conversation
DELETE	/session/{session_id}	Erase one conversation
GET	/balance	Wallet balance and lifetime usage
GET	/usage	Usage broken down by day
GET	/health	Liveness check, no key needed

Authentication

Every request carries your api_key in the JSON body, or as a query parameter on the GET endpoints. There is no separate token to fetch and no expiry to handle.

Each answered question is charged to your wallet at the moment it succeeds. A request that fails, or that a guardrail blocks, costs nothing.

Keep the key server-side. It spends money, so it does not belong in a mobile app or in browser JavaScript.

# every call, one field
"api_key": "dk_live_..."

Quickstart

Send a question and the person's birth details. The birth fields go at the top level of the request, the same shape as every other DivineAPI endpoint. Send them once per conversation; we remember them for that session_id.

Birth details

Field	Example
BIRTH DETAILS · needed once per session
`full_name`	Priya Sharma	OPTIONAL
`day` `month` `year`	24 · 05 · 1996	REQUIRED
`hour` `min`	14 · 40, 24-hour clock	REQUIRED
`gender`	female	REQUIRED
`place`	New Delhi	REQUIRED
`lat` `lon`	28.7041 · 77.1025	REQUIRED
`tzone`	5.5, hours from UTC	REQUIRED

Birth time changes the ascendant, the houses and every dasha date. If your user does not know theirs, an invented time produces confident and wrong answers rather than an error.

curl https://ask.divineapi.com/chat \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "dk_live_...",
    "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"
  }'

POST/chat

Ask a question inside a conversation we store for you. Follow-ups like "and my career?" or "what about him?" resolve on their own, because the thread is kept server-side.

Send the birth fields once and we hold them for that session_id. Every later message in the same session can omit them.

Charged only when an answer succeeds. Failures and guardrail replies cost nothing.

// response
{
  "answer": "Your chart points to...",
  "charged_inr": 0.9,
  "wallet_inr": 286.7,
  "grounding": "ok"
}

// stream: true
data: {"delta": "Your chart points"}
data: {"done": true, ...}

Body

Parameter	Values	Default	Description
`api_key`	string	REQUIRED	Your key
`user_id`	string	REQUIRED	Your ID for the end user. Recorded on every request and used for usage reporting
`session_id`	string	REQUIRED	Your ID for this conversation. A new ID starts a fresh thread
`message`	string	REQUIRED	What the user typed, in any language
BIRTH DETAILS · needed once per session
`full_name`	string	none	Used to address the person by name
`day`	`01` to `31`	REQUIRED	Day of birth
`month`	`01` to `12`	REQUIRED	Month of birth
`year`	e.g. `1996`	REQUIRED	Year of birth
`hour`	`00` to `23`	REQUIRED	Hour of birth on a 24-hour clock
`min`	`00` to `59`	REQUIRED	Minute of birth
`sec`	`00` to `59`	`0`	Rarely needed
`gender`	`male` · `female`	REQUIRED	Used by some traditional calculations
`place`	e.g. `New Delhi`	REQUIRED	Birth city, shown back to the user
`lat`	e.g. `28.7041`	REQUIRED	Latitude of the birth city
`lon`	e.g. `77.1025`	REQUIRED	Longitude of the birth city
`tzone`	e.g. `5.5`	REQUIRED	Hours ahead of UTC at the time of birth
`stream`	`true` · `false`	`false`	Stream the answer as it is written, rather than waiting for all of it
PRICED
`depth`	`quick` · `standard` · `deep`	`standard`	How much of the chart we read before answering. Rs 0.30, Rs 0.90, Rs 3.00 per answer
`length_cap`	`short` · `medium` · `full`	`medium`	Ceiling on how long the answer may be
STYLE, FREE
`language`	`auto`, or any language name e.g. `Hindi` · `Tamil` · `Spanish`	`English`	Defaults to `English`. Set `auto` to reply in whatever language and script the person wrote in, which suits a mixed audience but is a judgement the model makes per message rather than a guarantee
`school`	`western` · `vedic` · `kp` · `lalkitab`	`western`	Which tradition the reading follows
`lens`	`general` · `career` · `love` · `health` · `money` · `spiritual`	`general`	Which area of life to read the chart through
`confidence`	`balanced` · `definitive` · `careful`	`balanced`	How strongly claims are stated
`sensitivity`	`standard` · `strict`	`standard`	Use `strict` for matrimony and relationship products
`tone`	free text e.g. “calm and practical” “playful, like a close friend”	warm, friendly	How the astrologer sounds
`framing`	free text e.g. “honest but hopeful” “never sugar-coat it”	empowering	Its attitude to difficult placements
WHITE LABEL, FREE
`assistant_name`	free text e.g. “Guru ji” “Tara”	none	What your astrologer calls itself
`brand_voice`	free text e.g. “We speak plainly and never frighten people about their chart”	none	A line of personality in your brand's words
`sign_off`	free text e.g. “With light, Team Tara”	none	A closing line added to the end of every single answer, including each reply in a chat. Natural on a report; on a chat it can read as repetitive, so most chat products leave it empty
`style_notes`	free text, max 500 chars e.g. “Never name Sade Sati directly.” “Explain any Sanskrit term the first time you use it.” “Do not suggest gemstones or paid remedies, we do not sell them.”	none	Anything the parameters above do not cover

Response

Field	Description
`answer`	The reply, ready to show your user
`request_id`	Identifier for this request, useful in support queries
`charged_inr`	What this answer cost. `0.0` if a guardrail replied
`wallet_inr`	Balance remaining after the charge
`band`	Price band that applied: `simple`, `standard` or `deep`
`grounding`	`ok`, or `flagged` when a claim did not match the chart data
`chart_cache`	Hits and misses on the chart fetch. All hits means no upstream call was needed
`latency_ms`	Chart fetch, time to first token, and total
`usage`	Input, output and cached token counts
`blocked`	Present only when a guardrail replied instead. Nothing is charged

POST/ask

One question, one answer, nothing stored. Use it for report pages, daily cards, push notifications, or anywhere the answer is not part of a back-and-forth.

length_cap behaves differently here. On /ask it is a target, so a report page gets a full block of prose every time. On /chat it is a ceiling and the answer sizes itself to the question.

The response is identical to /chat.

curl https://ask.divineapi.com/ask \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "dk_live_...",
    "question": "What does my chart say about career?",
    "depth": "deep",
    "length_cap": "full",
    "day": "24", "month": "05", "year": "1996", ...
  }'

Body

Parameter	Values	Default	Description
`api_key`	string	REQUIRED	Your key
`question`	string	REQUIRED	The question, in any language
BIRTH DETAILS · needed once per session
`full_name`	string	none	Used to address the person by name
`day`	`01` to `31`	REQUIRED	Day of birth
`month`	`01` to `12`	REQUIRED	Month of birth
`year`	e.g. `1996`	REQUIRED	Year of birth
`hour`	`00` to `23`	REQUIRED	Hour of birth on a 24-hour clock
`min`	`00` to `59`	REQUIRED	Minute of birth
`sec`	`00` to `59`	`0`	Rarely needed
`gender`	`male` · `female`	REQUIRED	Used by some traditional calculations
`place`	e.g. `New Delhi`	REQUIRED	Birth city, shown back to the user
`lat`	e.g. `28.7041`	REQUIRED	Latitude of the birth city
`lon`	e.g. `77.1025`	REQUIRED	Longitude of the birth city
`tzone`	e.g. `5.5`	REQUIRED	Hours ahead of UTC at the time of birth
`history`	array	`[]`	`[{"role": "user", "text": "..."}]` if you keep the thread on your side
`stream`	`true` · `false`	`false`	Stream the answer as it is written
PRICED
`depth`	`quick` · `standard` · `deep`	`standard`	How much of the chart we read before answering. Rs 0.30, Rs 0.90, Rs 3.00 per answer
`length_cap`	`short` · `medium` · `full`	`medium`	Ceiling on how long the answer may be
STYLE, FREE
`language`	`auto`, or any language name e.g. `Hindi` · `Tamil` · `Spanish`	`English`	Defaults to `English`. Set `auto` to reply in whatever language and script the person wrote in, which suits a mixed audience but is a judgement the model makes per message rather than a guarantee
`school`	`western` · `vedic` · `kp` · `lalkitab`	`western`	Which tradition the reading follows
`lens`	`general` · `career` · `love` · `health` · `money` · `spiritual`	`general`	Which area of life to read the chart through
`confidence`	`balanced` · `definitive` · `careful`	`balanced`	How strongly claims are stated
`sensitivity`	`standard` · `strict`	`standard`	Use `strict` for matrimony and relationship products
`tone`	free text e.g. “calm and practical” “playful, like a close friend”	warm, friendly	How the astrologer sounds
`framing`	free text e.g. “honest but hopeful” “never sugar-coat it”	empowering	Its attitude to difficult placements
WHITE LABEL, FREE
`assistant_name`	free text e.g. “Guru ji” “Tara”	none	What your astrologer calls itself
`brand_voice`	free text e.g. “We speak plainly and never frighten people about their chart”	none	A line of personality in your brand's words
`sign_off`	free text e.g. “With light, Team Tara”	none	A closing line added to the end of every single answer, including each reply in a chat. Natural on a report; on a chat it can read as repetitive, so most chat products leave it empty
`style_notes`	free text, max 500 chars e.g. “Never name Sade Sati directly.” “Explain any Sanskrit term the first time you use it.” “Do not suggest gemstones or paid remedies, we do not sell them.”	none	Anything the parameters above do not cover

GET/sessions

Every conversation under your key, most recent first.

Query		Description
`api_key`	REQUIRED	Your key

Each entry carries the session ID, message count, when it started, when it was last active, and whether birth details are on file.

curl "https://ask.divineapi.com/sessions?api_key=dk_live_..."

GET/session/{session_id}

The full history of one conversation, for restoring a chat screen.

Returns every message in order with its role and timestamp, plus the birth details stored against the session. Returns 404 if the session has neither.

{
  "session_id": "s_5f21",
  "messages": [
    { "role": "user", "text": "When will I marry?" },
    { "role": "assistant", "text": "Your chart..." }
  ],
  "birth_details": { ... }
}

DELETE/session/{session_id}

Erase one conversation: its messages and its stored birth details.

Takes api_key as a query parameter. Permanent, and intended as the path you call when a user asks you to delete their data.

curl -X DELETE \
  "https://ask.divineapi.com/session/s_5f21?api_key=dk_live_..."

GET/balance

Wallet balance and lifetime usage. No question is asked and nothing is charged.

Returns your account name, remaining balance in rupees, total requests, total charged, and how many were blocked by a guardrail and therefore free.

{
  "name": "Pilot",
  "wallet_inr": 286.7,
  "total_requests": 529,
  "total_charged_inr": 778.2,
  "blocked_free": 0
}

GET/usage

Usage broken down by day, for reconciling your own billing.

Takes api_key as a query parameter.

curl "https://ask.divineapi.com/usage?api_key=dk_live_..."

GET/health

Liveness check. No key needed, nothing charged.

Use it for uptime monitoring.

{ "ok": true }

Errors

Code	Meaning
`401`	Unknown `api_key`
`402`	Wallet empty. The message names your balance and what the answer needed
`404`	Unknown `session_id`
`422`	A parameter is outside its allowed values, or `style_notes` is too long. The message lists what is allowed
`429`	Rate limit for your key. Retry after a short pause
`502`	Chart data or the model was unreachable. Nothing is charged

Guardrails are not errors. A question we will not answer, such as one asking for a date of death, returns 200 with a kind reply, blocked: true, and charged_inr: 0.0.

// 402
{ "detail": "wallet empty (balance Rs0.12, need Rs0.90). Top up to continue." }

// guardrail, HTTP 200, free
{
  "answer": "That is not something I can read...",
  "blocked": true,
  "charged_inr": 0.0
}