POST · AI

AI Chat (Text)

Base path POST https://starsapi.com/api/v2/partner/ai/chat/

Text-based AI astrologer sessions. Open a session with birth details, get a greeting, then keep sending messages. Three endpoints: /start (single chart), /match-start (two charts), and /message (follow-up turns). All return the same response envelope.

Start session

Endpoint POST /api/v2/partner/ai/chat/start

Opens a new single-chart session. Computes the user’s Vedic chart, selects the astrologer, and returns the AI’s opening greeting in new_messages.

Request body

Field	Type	Required	Description
`astrologer`	string	Yes	Astrologer key: `guruji`, `love_guru`, `career_expert`, `health_expert`, `transit_expert`.
`year`	integer	Yes	Birth year, 4-digit.
`month`	integer	Yes	Birth month, `1`–`12`.
`day`	integer	Yes	Day of month, `1`–`31`.
`hour`	integer	Yes	Hour in 24-hour local clock time, `0`–`23`.
`minute`	integer	Yes	Minute, `0`–`59`.
`latitude`	number	Yes	Signed decimal degrees, −90…90. Positive = North.
`longitude`	number	Yes	Signed decimal degrees, −180…180. Positive = East.
`timezone`	string	Yes	IANA timezone identifier (e.g. `Asia/Kolkata`).
`name`	string	No	User’s name. Used to personalize the astrologer’s responses.
`gender`	string	No	`male` or `female`.
`age`	integer	No	User’s age.
`preferred_language`	string	No	Response language code: `en`, `hi`, etc. Default: `en`.

Use the local clock time of birth. Pass the wall-clock time as recorded on the birth certificate together with the IANA timezone of the birth place. Do not pre-convert to UTC.

Send message

Endpoint POST /api/v2/partner/ai/chat/message

Send a follow-up message in an active session. The server loads the chart context and conversation history automatically from the session_id. Returns the astrologer’s reply in the same envelope as /start.

Request body

Field	Type	Required	Description
`session_id`	string	Yes	The 32-character session ID from the `/start` response.
`message`	string	Yes	The user’s message text.

Start match session (two charts)

Endpoint POST /api/v2/partner/ai/chat/match-start

Opens a matchmaking session with two birth charts loaded simultaneously. Used for compatibility analysis — Ashtakoot, Mangal Dosha, synastry, relationship counsel. Both charts remain in scope for the entire conversation. Subsequent turns use the same /message endpoint.

Request body

Send two person objects. The preferred field names are person1 and person2. Legacy names boy / girl are also accepted.

Field	Type	Required	Description
`astrologer`	string	Yes	Use a matching-capable astrologer, e.g. `guruji` or `love_guru`.
`preferred_language`	string	No	Response language. Default: `en`.
person1 (object)
`person1.name`	string	No	Name of person 1.
`person1.year`	integer	Yes	Birth year.
`person1.month`	integer	Yes	Birth month.
`person1.day`	integer	Yes	Birth day.
`person1.hour`	integer	Yes	Birth hour (24h).
`person1.minute`	integer	Yes	Birth minute.
`person1.latitude`	number	Yes	Signed decimal latitude.
`person1.longitude`	number	Yes	Signed decimal longitude.
`person1.timezone`	string	Yes	IANA timezone.
`person1.gender`	string	No	`male` or `female`.
person2 (same fields as person1)

Match-start example body

{
  "astrologer": "love_guru",
  "preferred_language": "en",
  "person1": {
    "name": "Ravi",
    "year": 1990, "month": 6, "day": 15,
    "hour": 14, "minute": 30,
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139, "longitude": 77.2090,
    "gender": "male"
  },
  "person2": {
    "name": "Priya",
    "year": 1992, "month": 3, "day": 22,
    "hour": 9, "minute": 15,
    "timezone": "Asia/Kolkata",
    "latitude": 19.0760, "longitude": 72.8777,
    "gender": "female"
  }
}

Response shape

All three endpoints return the same envelope. The data object contains the session state, the astrologer’s reply, and billing.

Field	Type	Description
`success`	boolean	`true` on success.
data
`session_id`	string	32-character session identifier. Pass to `/message` for subsequent turns.
`turn`	integer	Turn count. `1` = greeting, `2`+ = conversation turns.
data.astrologer
`key`	string	Astrologer identifier (e.g. `guruji`).
`name`	string	Display name.
`tagline`	string	Short description.
`avatar`	string	Emoji or avatar identifier for UI rendering.
`astrology_system`	string	Primary system used (e.g. `vedic`).
data.new_messages
`role`	string	`astrologer`.
`message`	array of strings	Reply text split into reading-sized chunks. Render each as a separate chat bubble.
data.suggested_followups
	array of strings	AI-generated quick-reply prompts. Surface as tappable chips in your UI.
data.billing
`cost_minor`	integer	Turn cost in minor units.
`currency`	string	`INR` or `USD`.
`wallet_balance_minor`	integer	Remaining balance after debit.
`wallet_balance_human`	string	Formatted balance string.

Message chunking. The message field is an array of strings, not a single string. Each element is one “bubble” — render them separately in your chat UI for a natural conversational feel. Optionally add a short delay between bubbles.

Integration checklist

Call /start with birth details + astrologer key → save session_id.
Render new_messages[0].message as separate chat bubbles.
Show suggested_followups as tappable chips below the last bubble.
On user input → call /message with session_id + message.
Check billing.wallet_balance_minor and warn the user when balance is low.
Handle errors: show error.message to the user for validation failures.

Errors

HTTP	Code	Cause
400	`VALIDATION_ERROR`	Missing/invalid fields or unknown astrologer key.
400	`MISSING_FIELD`	A required field is absent.
400	`INVALID_DATE`	Date values out of range.
400	`INVALID_TIME`	Hour/minute out of range.
400	`INVALID_TIMEZONE`	Non-IANA timezone value.
400	`INVALID_COORDINATE`	Latitude/longitude out of range.
400	`INVALID_SESSION`	Session ID not found or expired.
401	`AUTH_MISSING_KEY`	No API key in request.
402	`INSUFFICIENT_BALANCE`	Wallet balance too low.
405	`METHOD_NOT_ALLOWED`	Non-POST request.

# Step 1 — open a single-chart session
curl -X POST https://starsapi.com/api/v2/partner/ai/chat/start \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "astrologer": "guruji",
    "year": 1990, "month": 6, "day": 15,
    "hour": 14, "minute": 30,
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139, "longitude": 77.2090,
    "name": "Ravi", "gender": "male",
    "preferred_language": "en"
  }'

# Step 2 — send a follow-up message
curl -X POST https://starsapi.com/api/v2/partner/ai/chat/message \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "message": "Will I get the promotion this year?"
  }'

const BASE    = "https://starsapi.com/api/v2/partner/ai/chat";
const headers = { "X-Api-Key": API_KEY, "Content-Type": "application/json" };

// Step 1 — open the session
const start = await fetch(`${BASE}/start`, {
  method:  "POST",
  headers,
  body: JSON.stringify({
    astrologer: "guruji",
    year: 1990, month: 6, day: 15,
    hour: 14, minute: 30,
    timezone: "Asia/Kolkata",
    latitude: 28.6139, longitude: 77.2090,
    name: "Ravi", gender: "male",
    preferred_language: "en",
  }),
}).then(r => r.json());

const sessionId = start.data.session_id;

// Render greeting as chat bubbles
for (const chunk of start.data.new_messages[0].message) {
  renderBubble({ role: "astrologer", text: chunk });
}

// Step 2 — send a user message
async function sendMessage(text) {
  const r = await fetch(`${BASE}/message`, {
    method: "POST", headers,
    body: JSON.stringify({ session_id: sessionId, message: text }),
  }).then(r => r.json());

  for (const chunk of r.data.new_messages[0].message) {
    renderBubble({ role: "astrologer", text: chunk });
  }
  return r.data;
}

import requests

BASE    = "https://starsapi.com/api/v2/partner/ai/chat"
HEADERS = {"X-Api-Key": API_KEY, "Content-Type": "application/json"}

# Step 1 — open the session
start = requests.post(f"{BASE}/start", headers=HEADERS, json={
    "astrologer": "guruji",
    "year": 1990, "month": 6, "day": 15,
    "hour": 14, "minute": 30,
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139, "longitude": 77.2090,
    "name": "Ravi", "gender": "male",
    "preferred_language": "en",
}).json()

session_id = start["data"]["session_id"]

for chunk in start["data"]["new_messages"][0]["message"]:
    render_bubble(role="astrologer", text=chunk)

# Step 2 — follow-up message
def send_message(text: str) -> dict:
    r = requests.post(f"{BASE}/message", headers=HEADERS, json={
        "session_id": session_id,
        "message": text,
    }).json()
    for chunk in r["data"]["new_messages"][0]["message"]:
        render_bubble(role="astrologer", text=chunk)
    return r["data"]

import 'package:http/http.dart' as http;
import 'dart:convert';

const BASE = 'https://starsapi.com/api/v2/partner/ai/chat';
final headers = {
  'X-Api-Key': API_KEY,
  'Content-Type': 'application/json',
};

// Step 1 — open the session
final startResp = await http.post(
  Uri.parse('$BASE/start'),
  headers: headers,
  body: jsonEncode({
    'astrologer': 'guruji',
    'year': 1990, 'month': 6, 'day': 15,
    'hour': 14, 'minute': 30,
    'timezone': 'Asia/Kolkata',
    'latitude': 28.6139, 'longitude': 77.2090,
    'name': 'Ravi', 'gender': 'male',
    'preferred_language': 'en',
  }),
);
final start = jsonDecode(startResp.body)['data'];
final sessionId = start['session_id'];

for (final chunk in start['new_messages'][0]['message']) {
  addBubble(role: 'astrologer', text: chunk);
}

// Step 2 — send a user message
Future<Map> sendMessage(String text) async {
  final r = await http.post(
    Uri.parse('$BASE/message'),
    headers: headers,
    body: jsonEncode({'session_id': sessionId, 'message': text}),
  );
  return jsonDecode(r.body)['data'];
}

<?php
$BASE = "https://starsapi.com/api/v2/partner/ai/chat";
$headers = ["X-Api-Key: YOUR_KEY", "Content-Type: application/json"];

// Step 1 — open the session
$ch = curl_init("$BASE/start");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => json_encode([
        "astrologer" => "guruji",
        "year" => 1990, "month" => 6, "day" => 15,
        "hour" => 14, "minute" => 30,
        "timezone" => "Asia/Kolkata",
        "latitude" => 28.6139, "longitude" => 77.2090,
        "name" => "Ravi", "gender" => "male",
        "preferred_language" => "en",
    ]),
]);
$start = json_decode(curl_exec($ch), true);
curl_close($ch);

$sessionId = $start['data']['session_id'];

// Step 2 — send a follow-up message
$ch = curl_init("$BASE/message");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => json_encode([
        "session_id" => $sessionId,
        "message"    => "Will I get the promotion this year?",
    ]),
]);
$reply = json_decode(curl_exec($ch), true);
curl_close($ch);

200 RESPONSE

{
  "success": true,
  "data": {
    "session_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "turn": 1,
    "astrologer": {
      "key": "guruji",
      "name": "Guruji",
      "tagline": "Your Vedic guide",
      "avatar": "🕉️",
      "astrology_system": "vedic"
    },
    "new_messages": [
      {
        "role": "astrologer",
        "message": [
          "Namaste, Ravi! I see your chart has a Leo Ascendant — a powerful placement that speaks of leadership and creativity.",
          "With Moon in Virgo under Hasta nakshatra, you have a natural gift for detail and craftsmanship. What brings you here today — career, relationships, or something else on your mind?"
        ]
      }
    ],
    "suggested_followups": [
      "Tell me about my career",
      "How is my love life looking?",
      "What are my current dashas?"
    ],
    "billing": {
      "cost_minor": 2000,
      "currency": "INR",
      "wallet_balance_minor": 48000,
      "wallet_balance_human": "₹480.00"
    }
  }
}

AI Chat (Text)

Start session

Request body

Send message

Request body

Start match session (two charts)

Request body

Match-start example body

Response shape

Integration checklist

Errors

See also