Copy page

Copy page as Markdown for LLMs

View as Markdown

View this page as plain text


Open in ChatGPT

Ask ChatGPT about this page

Open in Claude

Ask Claude about this page

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/chat

Guide: 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

EnglishEnglish (default)
HindiHindi
TamilTamil
SpanishSpanish
...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

NameTypeDescription

Content-Type*

String

application/json.  Example: Content-Type: application/json

Fields marked with * are mandatory.


Request Body

NameTypeDescription
api_key*StringYour 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

StringUsed 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.

curl -X POST "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"
}'
const axios = require('axios');

const response = await axios.post(
  'https://ask.divineapi.com/chat',
  {
    '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",
  },
  {
  headers: {
      'Content-Type': "application/json",
    },
}
);

console.log(response.data);
import requests

url = "https://ask.divineapi.com/chat"
headers = {
    "Content-Type": "application/json",
}
payload = {
    "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",
}

response = requests.post(url, headers=headers, json=payload)

print(response.json())
const response = await fetch(
  'https://ask.divineapi.com/chat',
  {
    method: 'POST',
    headers: {
        'Content-Type': "application/json",
      },
    body: JSON.stringify({"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"}),
  }
);

const data = await response.json();
console.log(data);
<?php

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('POST', 'https://ask.divineapi.com/chat', [
    'headers' => [
        'Content-Type' => 'application/json',
    ],
    'json' => [
        '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',
    ],
]);

echo $response->getBody();
package main

import (
    "bytes"
    "fmt"
    "net/http"
    "io"
)

func main() {
    jsonBody := []byte(`{"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"}`)
    req, _ := http.NewRequest("POST", "https://ask.divineapi.com/chat", bytes.NewBuffer(jsonBody))
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body2, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body2))
}
import okhttp3.*;
import java.io.IOException;

public class Main {
    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();

        MediaType JSON = MediaType.get("application/json; charset=utf-8");
        String json = "{\"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\"}";
        RequestBody body = RequestBody.create(json, JSON);

        Request request = new Request.Builder()
            .url("https://ask.divineapi.com/chat")
            .post(body)
            .addHeader("Content-Type", "application/json")
            .build();

        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());
    }
}
import Foundation

let url = URL(string: "https://ask.divineapi.com/chat")!
var request = URLRequest(url: url)
request.httpMethod = "POST"

request.setValue("application/json", forHTTPHeaderField: "Content-Type")
let jsonBody = """{"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"}"""
request.httpBody = jsonBody.data(using: .utf8)

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let data = data {
        print(String(data: data, encoding: .utf8) ?? "")
    }
}
task.resume()
import okhttp3.*

fun main() {
    val client = OkHttpClient()

    val mediaType = "application/json".toMediaType()
    val body = "{\"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\"}".toRequestBody(mediaType)

    val request = Request.Builder()
        .url("https://ask.divineapi.com/chat")
        .post(body!!)
        .addHeader("Content-Type", "application/json")
        .build()

    client.newCall(request).execute().use { response ->
        println(response.body?.string())
    }
}
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program {
    static async Task Main() {
        using var client = new HttpClient();

using System.Text;
        var json = "{\"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\"}";
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await client.PostAsync("https://ask.divineapi.com/chat", content);
        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}