POST · AI

AI Chat (Text)

Base path POST https://starsapi.com/api/v3/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/v3/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. Single-chart: `career_expert`, `health_expert`, `love_guru`, `love_guru_male`, `transit_expert`, `numeromitra`, `western_natal`. Always send it — omitting it falls back to an internal default that is not part of the public contract and may change. The roster enabled for your account is shown in your dashboard.
`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. Derived from `year` when omitted.
`place`	string	No	Birth city name — display only. The chart is computed from `latitude`/`longitude`/`timezone`; this simply lets the astrologer say “born in Jaipur” instead of quoting coordinates. Aliases: `city`, `birth_place`, `location`.
`preferred_language`	string	No	Language of the greeting. Accepts `hinglish` (Hindi in Roman script) or any ISO 639-1 code — `en`, `hi`, `ta`, `te`, `mr`, `bn`, `ne`, `es`, `fr`, `ja`, `ar` and so on. Regional forms such as `pt-br` resolve to the base language. An unrecognised value silently falls back to English. 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/v3/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.

Turn numbering. The greeting is turn 1, so the first user message returns turn 2. preferred_language is not accepted here — from turn 2 onward the astrologer mirrors whatever language and script the user actually types, switching mid-conversation if they do.

Session errors. 404 SESSION_NOT_FOUND, 403 FORBIDDEN (the session belongs to a different API key) and 409 SESSION_CLOSED all mean the same thing for your UI: start a new session.

Start match session (two charts)

Endpoint POST /api/v3/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 two-chart persona: `matchmaking`, `numeromitra_match` or `western_synastry`. A single-chart key here will be priced and framed as a single-chart session — do not mix them.
`preferred_language`	string	No	Same values as `/start` — `hinglish` or any ISO 639-1 code. 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`.
`person1.place`	string	No	Birth city name, display only.
person2 (same fields as person1)

Match-start example body

{
  "astrologer": "matchmaking",
  "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
`status`	integer	Mirrors the HTTP status.
`success`	boolean	`true` on success.
data
`session_id`	string	32-character lowercase hex session identifier. Pass to `/message` for subsequent turns.
`turn`	integer	Turn count. `1` = greeting, `2`+ = conversation turns.
`pre_message`	string	Waiting-state copy to show while a reply is pending (“Arjun is studying your chart…”). `/start` only — not returned by `/match-start` or `/message`.
`match_summary`	object	`/match-start` only. Compatibility headline. Switch on `match_summary.system` — see the callout below.
data.astrologer
`key`	string	Astrologer identifier (e.g. `career_expert`).
`name`	string	Display name.
`avatar_emoji`	string	Emoji for UI rendering.
`astrology_system`	string	Primary system used (e.g. `vedic`).
data.new_messages
`role`	string	`assistant`.
`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, up to 4. Frequently empty — render nothing when it is, do not reserve space for chips.
data.billing — see the billing callout; may be absent
`cost_minor`	integer	Turn cost in minor units (paise for INR, cents for USD).
`currency`	string	`INR` or `USD`.
`wallet_balance_minor`	integer	Balance after this turn was debited. `null` on internal/test accounts.
`wallet_balance_human`	string	Formatted balance string. `null` on internal/test accounts.
meta — sibling of `data`, not inside it
`endpoint`	string	Path that served the request.
`version`	string	API version, `3.0`.
`response_time_ms`	integer	Server-side processing time.
`request_id`	string	Quote this when reporting an issue.

match_summary has three shapes. Read match_summary.system first, then the fields for that system. Vedic: total_points, max_points, percentage, verdict. Numerology: overall_score, max_score, score_label, verdict. Western: compatibility. Any individual value may be null if the underlying calculation did not produce it — render defensively.

Billing is per AI response, and the greeting counts. The session-start greeting is a full AI turn — chart computation plus generation — and is charged like any other turn. There are no free turns, and couple sessions cost more than single-chart ones. The billing block is not guaranteed: on /message it is absent for internal and test accounts, and absent if the wallet debit itself fails (you still get a normal 200 with the reply). Treat a missing billing key as “no charge information for this turn”, never as an error.

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 — and render nothing when the array is empty.
Use pre_message for the waiting state on /start; handle its absence elsewhere.
On user input → call /message with session_id + message. One request in flight per session.
Check billing.wallet_balance_minor when present, and warn on a low balance. Never break the UI when the block is missing.
Route 403 / 404 / 409 to “start a new session”.
Handle errors: show error.message to the user for validation failures.

Errors

HTTP	Code	Endpoint	Cause
400	`INVALID_JSON`	all	Body is not valid JSON.
400	`VALIDATION_ERROR`	all	Missing or invalid field, unknown astrologer key, malformed `session_id`. The message names the offending field — surface it.
401	`AUTH_ERROR`	all	Bad or missing API key.
403	`FORBIDDEN`	`/message`	Session belongs to a different API key.
404	`SESSION_NOT_FOUND`	`/message`	No session with that ID.
409	`SESSION_CLOSED`	`/message`	Session is no longer active.
402	`WALLET_INSUFFICIENT`	all	Wallet balance is below the cost of this turn. The message states the amount required and the amount available. Top up — the session survives.
403	`PLAN_FREE_TIER`	all	AI chat is not available on the free plan.
403	`PLAN_NO_AI_CHAT`	all	Your plan does not include AI chat.
403	`PLAN_EXPIRED`	all	Subscription has expired. The wallet balance is preserved.
403	`TRIAL_NO_AI`	all	AI services are not available during the trial period.
403	`ACCOUNT_SUSPENDED`	all	Account is not active.
500	`CALCULATION_ERROR`	`/start`, `/match-start`	Chart computation failed for the supplied birth data.
500	`CONFIG_ERROR`	`/message`	Astrologer config missing for a session already in progress.
500	`INTERNAL_ERROR`	all	Unexpected server-side failure.

Account and wallet rejections happen before any AI work. A free-tier plan, an expired subscription, a plan without AI chat, or an insufficient balance all stop the request at the gate — nothing is generated and nothing is charged. These arrive as 402 or 403 with a specific code, so route them to an account or top-up screen rather than to a generic error state. Only WALLET_INSUFFICIENT is recoverable in place: top up and the same session continues.

Never retry automatically. AI replies take 4–12 seconds; set a 120 s client timeout and show a typing indicator. A request that timed out on your side may still have completed and been billed. Within one session a repeated turn is not charged twice, but a retried /start creates a new session and is charged again. Let the user choose to resend.

# Step 1 — open a single-chart session
curl -X POST https://starsapi.com/api/v3/partner/ai/chat/start \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "astrologer": "career_expert",
    "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/v3/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/v3/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: "career_expert",
    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/v3/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": "career_expert",
    "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/v3/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': 'career_expert',
    '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/v3/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" => "career_expert",
        "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

{
  "status": 200,
  "success": true,
  "data": {
    "session_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "turn": 1,
    "astrologer": {
      "key": "career_expert",
      "name": "Arjun",
      "avatar_emoji": "💼",
      "astrology_system": "vedic"
    },
    "new_messages": [
      {
        "role": "assistant",
        "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": 200,
      "currency": "INR",
      "wallet_balance_minor": 48000,
      "wallet_balance_human": "₹480.00"
    },
    "pre_message": "Arjun is studying your chart..."
  },
  "meta": {
    "endpoint": "/api/v3/partner/ai/chat/start",
    "version": "3.0",
    "response_time_ms": 5366,
    "timestamp": "2026-08-16T23:07:13+05:30",
    "request_id": "3984a0cf5c2d15a9"
  }
}

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