/v1/chat/respondChat · Respond API
Generate an emotionally intelligent, astrology-grounded response.
About the engine
Part of the AI Astrologer engine
A conversational layer over the astrology engine. Every response is anchored in a deterministic chart context - not a generic chatbot - and gated by a defense-in-depth safety layer that intercepts medical, financial, and self-harm prompts. Multi-turn memory keyed on caller-owned conversation_id; tone + confidence labels; a structured `practices` array on every reply. Streaming variant available for token-by-token UI.
Request
Try it from the command line
curl -X POST 'https://api.astronode.dev/v1/chat/respond' \
-H 'Authorization: Bearer aie_test_REPLACE_WITH_YOUR_API_KEY' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
--data '{
"conversation_id": "playground-demo",
"user": {
"date": "1993-07-04",
"time": "09:27:11",
"tz_offset_minutes": 330,
"lat": 31.7473,
"lng": 77.7754
},
"message": "I keep second-guessing my career decisions. What'\''s that about?"
}'Paste and run - this is the exact payload our live playground sends to this endpoint, so it is valid against the current schema. Every AstroNode endpoint needs a bearer token from your dashboard. Test keys (aie_test_*) work on the free tier - 1,000 requests / month, no card.
Request schema
Fields POST /v1/chat/respond accepts
| Field | Type | Notes |
|---|---|---|
conversation_idrequired | string | Caller-owned conversation identifier. Reusing the same id replays the most recent turns into the prompt for multi-turn continuity. pattern ^[A-Za-z0-9_\-:.]+$ · len 3..120 |
userrequired | object | Birth tuple of the user the message is from. |
user.daterequired | string | ISO date in YYYY-MM-DD form (Gregorian). pattern ^\d{4}-\d{2}-\d{2}$ e.g. |
user.timerequired | string | Local time at place of birth, 24-hour HH:mm or HH:mm:ss. pattern ^\d{2}:\d{2}(:\d{2})?$ e.g. |
user.latrequired | number | Latitude of the place of birth, in degrees (-90..90). -90..90 e.g. |
user.lngrequired | number | Longitude of the place of birth, in degrees (-180..180, east positive). -180..180 e.g. |
user.tz_offset_minutesrequired | integer | Offset from UTC in minutes for the local time at place of birth (e.g., 330 for IST, -300 for EST). -840..840 e.g. |
user.gender | enum | Optional. For Ashtakoot Gun Milan, orders the caller into the classical groom/bride (boy/girl) slot - a female caller reads as the bride. Omitted → caller-first ordering. Numerica… male | female |
partner | object | Optional partner birth tuple. Omit for an individual / chart-only read. When present, the service additionally computes Ashtakoot Gun Milan compatibility and surfaces a relationsh… |
partner.daterequired | string | ISO date in YYYY-MM-DD form (Gregorian). pattern ^\d{4}-\d{2}-\d{2}$ e.g. |
partner.timerequired | string | Local time at place of birth, 24-hour HH:mm or HH:mm:ss. pattern ^\d{2}:\d{2}(:\d{2})?$ e.g. |
partner.latrequired | number | Latitude of the place of birth, in degrees (-90..90). -90..90 e.g. |
partner.lngrequired | number | Longitude of the place of birth, in degrees (-180..180, east positive). -180..180 e.g. |
partner.tz_offset_minutesrequired | integer | Offset from UTC in minutes for the local time at place of birth (e.g., 330 for IST, -300 for EST). -840..840 e.g. |
partner.gender | enum | Optional. For Ashtakoot Gun Milan, orders the caller into the classical groom/bride (boy/girl) slot - a female caller reads as the bride. Omitted → caller-first ordering. Numerica… male | female |
report | object | Optional Cosmic Blueprint deluxe report for the user (structured sections and/or a text digest). When present, the chat draws on it as authoritative background for deeper, more pe… |
report.sections | object[] | Structured report sections. Preferred over `text`: the prompt keeps whole sections when trimming to the token budget. |
report.sections[].titlerequired | string | Section heading, e.g. 'Relationship Blueprint'. len 1..200 |
report.sections[].bodyrequired | string | The section's text. Flatten paragraphs/bullets into plain prose before sending. len 1..8000 |
report.text | string | A pre-rendered plain-text digest of the report. Used when `sections` is absent. len 1..20000 |
focus | enum | Optional topic lens (career / love / money / health / growth). Biases the reading toward that life area's houses + karakas. `general` or omitted = no bias. Ignored for greetings/s… general | career | love | money | health | growth |
language | enum | Reply language. `hi` → the assistant writes the message + follow-ups in Hindi (Devanagari); common astrology terms stay in their usual form. Omitted / `en` → English. Structured f… en | hi |
birth_time_confidence | object | Optional Birth Time Refinement™ signal. When present, the chat calibrates how literally it reads time-sensitive points and may note birth-time confidence. Computed by the caller;… |
birth_time_confidence.refined_timerequired | string | len 1..12 |
birth_time_confidence.confidencerequired | number | 0..100 |
birth_time_confidence.bandrequired | string | len 1..16 |
birth_time_confidence.event_count | integer | 0..9007199254740991 |
birth_time_confidence.guidancerequired | string | len 1..400 |
messagerequired | string | The user's message - capped at 2000 characters. len 1..2000 |
client_turn_id | string | Optional caller-owned idempotency key for ONE logical turn. When a client retries the same turn - e.g. the consumer's SSE→non-stream fallback - it MUST send the SAME value on both… pattern ^[A-Za-z0-9_\-:.]+$ · len 1..80 |
Generated from the same OpenAPI 3.1 document the API validates against, so this table cannot drift from the endpoint without the build failing.
Response
What you get back
Every AstroNode response uses the same envelope: request_id, data (the endpoint-specific payload), interpretation (optional narrative block), and meta (engine version + computed_at timestamp). This endpoint documents 200, 400, 401, 422, 429, 500, 502, 504.
The data payload for POST /v1/chat/respond is not yet broken out field by field in the published schema. The fastest way to see its exact shape is to run the call - the playground returns a live response with no signup, and the API reference carries the full document.
Engine highlights
What the AI Astrologer engine ships
- Bounded reasoning - every reply grounded in the user's deterministic chart context
- Multi-turn memory keyed on caller-owned `conversation_id`
- Defense-in-depth safety layer on input + output (medical / financial / self-harm)
- Structured `practices` array on every response (planet, kind, summary)
- Tone (supportive | reflective | grounded | calm | neutral) and confidence (low | moderate | high) labels
- Optional `partner` block triggers compatibility-aware reasoning
- Strict JSON-schema response enforcement on Gemini + Groq + OpenAI providers
- Streaming variant for token-by-token UI
- Conversation history endpoints for resume + per-user transcripts
Ready to call POST /v1/chat/respond?
Free tier covers 1,000 requests / month. Razorpay-billed, GST-compliant invoices when you upgrade.
Informational, not predictive. Not medical, legal, or financial advice.