API reference · v1

AI Guide

A chat endpoint grounded in the querent's chart: intent-aware replies, optional AI depth, and conversation history — the building block for astrology copilots.

2 endpoints · 1 credit per call

Endpoints

Every ai guide endpoint

Parameters, copy-paste examples in three languages, and response shapes.

POST/api/v1/guide/chat

Chat with the Guide

Send a message to the astrology Guide. Replies are grounded in chart context with deterministic intent handling; AI depth is used when available. Pass conversation history for multi-turn context.

2 credits per call

Parameters

Name	Type	In	Required	Description
message	string	body	required	User message, 1–2000 chars
language	string	body	optional	Two-letter language code (default en)
history	array	body	optional	Prior turns: [{role, content}]

Example request

cURL

curl -X POST "https://api-rho-eight-42.vercel.app/api/v1/guide/chat" \
  -H "X-API-Key: kundli_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
  "message": "What does today hold for my career?",
  "language": "en",
  "history": [
    {
      "role": "user",
      "content": "Tell me about my strengths"
    }
  ]
}'

Example response

JSON

{
  "reply": "With Saturn transiting your 10th house, today rewards patient, visible work...",
  "intent": "career",
  "grounded": true,
  "is_ai": true,
  "remaining_free": 4
}

Try it — paste your own key from Developers → API Keys in place of kundli_abc123... and run the snippet against https://api-rho-eight-42.vercel.app.

GET/api/v1/guide/chat/history

Chat history

Retrieve the stored conversation history for the authenticated identity — roles, intents and timestamps.

1 credit per call

Parameters

No parameters — call it as-is.

Example request

cURL

curl "https://api-rho-eight-42.vercel.app/api/v1/guide/chat/history" \
  -H "X-API-Key: kundli_abc123..."

Example response

JSON

{
  "history": [
    {
      "role": "user",
      "content": "Tell me about my strengths",
      "intent": "self",
      "is_ai": false
    },
    {
      "role": "guide",
      "content": "Your chart shows a strong 10th house...",
      "intent": "self",
      "is_ai": true
    }
  ]
}

Try it — paste your own key from Developers → API Keys in place of kundli_abc123... and run the snippet against https://api-rho-eight-42.vercel.app.

Need a key?

Create one from your dashboard and paste it into any example above — every snippet is ready to run.

Get an API key