Back to Docs

Hosted Vedic AI Chat

Hosted Vedic AI Chat

POST/api/v2/vedic/chat

Ask a concise Vedic astrology question and receive a hosted model answer grounded in FreeAstroAPI's deterministic Vedic tools.

Authentication: send x-api-key. Hosted Vedic Chat is metered separately from ordinary API requests: Free includes 20 one-time trial messages, Entry includes 100 messages per month, and High includes 2,000 messages per month.

Full URL

https://api.freeastroapi.com/api/v2/vedic/chat
Safe retries with Idempotency-Key

Authenticated, billable astrology POST requests accept the optional header Idempotency-Key: <client-generated unique operation key>. Reuse the same key only when retrying the exact same method, path, query string, and JSON body after a timeout or network failure.

A completed replay returns the first response with Idempotency-Replayed: true, does not rerun the calculation, and does not consume extra quota. Keys are retained for about 24 hours.

Reusing a key with a changed request returns 409 idempotency_key_reused. A duplicate while the first request is still running returns 409 request_in_progress with Retry-After.

What It Returns

A short Vedic chat answer, the conversation id for follow-up context, the internal Vedic MCP tools used for deterministic facts, model latency, and hosted-chat message quota state when a complete chart-based answer is metered.

Metering and Limits

One hosted message includes one user turn, one model answer, and up to three scoped Vedic MCP tool calls. These internal calls do not consume the customer's ordinary API request quota.

PlanIncluded Hosted ChatOverage
Free20 messages, one-time trialNot available
Entry100 messages / monthDisabled by default
High2,000 messages / month$10 / 1,000-message pack

Request limits are 4,000 characters for message, 120 characters for conversation_id, and 12 client-provided history items.

Developers who want to run their own Gemini, OpenAI, Anthropic, or local model should use the hosted MCP server with scope=vedic-bot instead of this endpoint.

Errors and Retries

StatusMeaningClient action
400Invalid Idempotency-KeyUse a non-empty key no longer than 255 characters.
409Request in progress or key reused with a different requestFor an in-progress request, wait for Retry-After and resend the identical body with the same key. Use a new key for a new message.
422Request validation failedCorrect the request body before retrying.
429Monthly chat quota or burst limit exceededHonor Retry-After for burst limits; otherwise wait for quota reset or add capacity.
503Hosted model capacity or retry-safety storage unavailableThe request is not metered. Wait for Retry-After, then retry the identical request with the same key.

A successful replay returns Idempotency-Replayed: true and the original response without consuming another hosted chat message.

Example Request

curl -X POST "https://api.freeastroapi.com/api/v2/vedic/chat" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -H "Idempotency-Key: UNIQUE_KEY_PER_USER_MESSAGE" \
 -d '{
  "message": "What dasha am I in, and how should I use this period?",
  "conversation_id": "vedic-chat-demo-001",
  "memory": "thread",
  "locale": "en",
  "tone": "clear",
  "reference_date": "2026-07-08",
  "profile": {
    "name": "Example native",
    "year": 1990,
    "month": 1,
    "day": 15,
    "hour": 10,
    "minute": 30,
    "city": "New Delhi",
    "lat": 28.6139,
    "lng": 77.209,
    "tz_str": "Asia/Kolkata",
    "ayanamsha": "lahiri",
    "house_system": "whole_sign",
    "node_type": "mean"
  },
  "history": [
    {
      "role": "user",
      "content": "Please keep the answer practical."
    }
  ],
  "debug": false
}'

Request Parameters

For chart-grounded answers, provide profile.city or both profile.lat and profile.lng. Coordinates are recommended for stable production results. Compatibility questions also use partner_profile.

Field
message
Type
string
Required
Yes
Description
User's Vedic astrology question. Maximum 4,000 characters.
Field
conversation_id
Type
string
Required
No
Description
Stable thread id for remembered context. Omit it to start a new conversation. Maximum 120 characters.
Field
memory
Type
string
Required
No
Description
Use thread to remember recent turns, or request for a stateless answer. Defaults to thread.
Field
profile
Type
object
Required
No
Description
Primary birth profile for the person asking the question (the main subject or 'you'). Required for chart-specific answers; omitted or incomplete profiles return needs_birth_data=true without using a hosted chat credit.
Field
profile.name
Type
string
Required
No
Description
Optional display name used only for natural chat wording, not astrology calculations. Maximum 80 characters.
Field
profile.year
Type
integer
Required
No
Description
Birth year.
Field
profile.month
Type
integer
Required
No
Description
Birth month, 1-12.
Field
profile.day
Type
integer
Required
No
Description
Birth day.
Field
profile.hour
Type
integer
Required
No
Description
Birth hour, 0-23.
Field
profile.minute
Type
integer
Required
No
Description
Birth minute, 0-59.
Field
profile.city
Type
string
Required
No
Description
Birth city. Optional when profile.lat and profile.lng are provided.
Field
profile.lat / profile.lng
Type
float
Required
No
Description
Birth coordinates. Recommended for stable production answers.
Field
profile.tz_str
Type
string
Required
No
Description
Timezone: AUTO or an IANA timezone. Defaults to AUTO.
Field
profile.ayanamsha
Type
string
Required
No
Description
Vedic ayanamsha. Defaults to lahiri.
Field
profile.house_system
Type
string
Required
No
Description
House system. Defaults to whole_sign.
Field
profile.node_type
Type
string
Required
No
Description
Lunar node type. Defaults to mean.
Field
partner_profile
Type
object
Required
No
Description
Comparison person's birth profile for match and compatibility questions. It uses the same birth fields as profile and should be resent on relevant follow-up requests.
Field
partner_profile.name
Type
string
Required
No
Description
Optional first name or display label for the comparison person. It is not used in chart calculations.
Field
history
Type
array<object>
Required
No
Description
Client-provided recent turns. Each item has role=user|assistant and content. Maximum 12 items.
Field
locale
Type
string
Required
No
Description
Preferred answer locale. Maximum 16 characters; defaults to en.
Field
tone
Type
string
Required
No
Description
Answer tone: clear, gentle, or technical. Defaults to clear.
Field
reference_date
Type
string
Required
No
Description
Optional local YYYY-MM-DD date for daily, dasha, or gochar questions.
Field
debug
Type
boolean
Required
No
Description
When true, include tool_trace for development. Defaults to false.

Response Shape

Field
reply
Type
string
Required
n/a
Description
Concise hosted model answer grounded in FreeAstroAPI Vedic tool facts.
Field
conversation_id
Type
string
Required
n/a
Description
Conversation id to send on the next request when memory=thread.
Field
needs_birth_data
Type
boolean
Required
n/a
Description
True when the endpoint needs birth date, time, and city or coordinates before it can answer chart-specific questions.
Field
required_profile
Type
string
Required
n/a
Description
Returned with needs_birth_data=true. Identifies whether primary or partner birth data is needed.
Field
required_fields
Type
array<string>
Required
n/a
Description
Returned with needs_birth_data=true. Lists the missing birth_date, birth_time, and/or birth_place input groups.
Field
used_tools
Type
array<string>
Required
n/a
Description
Internal scoped MCP tool names used for deterministic Vedic facts.
Field
latency_ms
Type
integer
Required
n/a
Description
Server-side orchestration latency in milliseconds.
Field
model
Type
string
Required
n/a
Description
Hosted model used for the answer. Usually gemini-2.5-flash or gemini-2.5-flash-lite.
Field
quota
Type
object
Required
n/a
Description
Hosted Vedic Chat message usage after this turn, returned for metered chat answers.
Field
quota.tier
Type
string
Required
n/a
Description
Resolved subscription tier used for chat metering.
Field
quota.limit
Type
integer
Required
n/a
Description
Included hosted chat messages for the current period or Free trial.
Field
quota.used
Type
integer
Required
n/a
Description
Hosted chat messages used after this request.
Field
quota.remaining
Type
integer
Required
n/a
Description
Hosted chat messages remaining after this request.
Field
quota.period_key
Type
string
Required
n/a
Description
trial for Free, or YYYY-MM for paid monthly quotas.
Field
quota.reset_at
Type
string
Required
n/a
Description
Monthly reset timestamp for paid tiers. Null for the one-time Free trial.
Field
tool_trace
Type
object
Required
n/a
Description
Returned only when debug=true. Includes internal tool name, arguments, and facts preview.

Sample Request Example

This sample asks a dasha question with thread memory enabled. Send the returned conversation_id on follow-up messages, and use a new Idempotency-Key for each new user message.

{
  "message": "What dasha am I in, and how should I use this period?",
  "conversation_id": "vedic-chat-demo-001",
  "memory": "thread",
  "locale": "en",
  "tone": "clear",
  "reference_date": "2026-07-08",
  "profile": {
    "name": "Example native",
    "year": 1990,
    "month": 1,
    "day": 15,
    "hour": 10,
    "minute": 30,
    "city": "New Delhi",
    "lat": 28.6139,
    "lng": 77.209,
    "tz_str": "Asia/Kolkata",
    "ayanamsha": "lahiri",
    "house_system": "whole_sign",
    "node_type": "mean"
  },
  "history": [
    {
      "role": "user",
      "content": "Please keep the answer practical."
    }
  ],
  "debug": false
}

Sample Response Example

V2

This representative sample shows the hosted-chat response shape and quota fields. Actual answer text depends on the chart facts, question, context, and hosted model response.

{
  "reply": "You are in a Rahu period with Shravana Moon context shaping the timing. Use this phase for learning, technical work, foreign or unconventional opportunities, and disciplined experimentation. Keep decisions evidence-based, avoid impulsive promises, and review major commitments before acting.",
  "conversation_id": "vedic-chat-demo-001",
  "needs_birth_data": false,
  "used_tools": [
    "v2_vedic_dasha"
  ],
  "latency_ms": 1280,
  "model": "gemini-2.5-flash",
  "quota": {
    "tier": "Entry",
    "limit": 100,
    "used": 12,
    "remaining": 88,
    "period_key": "2026-07",
    "reset_at": "2026-08-01T00:00:00+00:00"
  }
}

Related Docs

Hosted MCP / BYOMVimshottari dashaFull Vedic calculatePricing

FAQ

What is the Hosted Vedic AI Chat API?

It is a hosted orchestration endpoint that combines a managed AI model with FreeAstroAPI's deterministic Vedic calculations. Instead of returning only raw chart data, it selects the relevant Vedic tool, interprets the resulting facts, and returns a concise natural-language answer with conversation, model, latency, and quota metadata.

Is Hosted Vedic AI Chat the same as MCP?

No. This endpoint runs FreeAstroAPI's hosted model layer and consumes the separate hosted-chat message allowance. MCP is the bring-your-own-model path: your application connects Gemini, OpenAI, Anthropic, or another model to the vedic-bot MCP scope, pays that model provider directly, and consumes normal FreeAstroAPI request quota for tool calls.

What kinds of Vedic astrology questions can users ask?

The endpoint supports personal questions about natal themes, Vimshottari dasha, gochar and timing, career, money, relationships, marriage, compatibility, daily guidance, and the Moon. The orchestrator chooses a scoped Vedic tool based on the question. Answers are astrology-oriented interpretations rather than guarantees about future events.

When is birth data required?

General educational questions may be answered without a chart, but personal predictions and timing questions require the primary profile's birth date, birth time, and birth city or coordinates. If required data is absent, the response sets needs_birth_data=true and identifies required_profile and required_fields. That clarification response does not consume a hosted-chat message.

How does remembered conversation context work?

Use memory=thread and send the same conversation_id on each follow-up to reuse recent user and assistant turns. Use memory=request for a stateless request, or send up to 12 history items when the client manages context itself. Thread memory stores conversation turns, not birth profiles, so profile data should be sent again with chart-specific follow-ups.

How do two-person compatibility questions work?

Send the main person or person asking as profile and the comparison person as partner_profile. Names are optional display labels; birth date, time, and place drive the calculations. Send both profiles again on compatibility follow-ups because conversation memory does not persist either birth profile.

How should I handle questions such as 'this month' or 'today'?

Send reference_date as the user's local YYYY-MM-DD date when reproducibility matters, especially for daily, dasha, gochar, money-timing, or relationship-timing questions. Include a reliable profile timezone or coordinates so date-sensitive Vedic calculations use the intended local context.

Can I control the answer language and tone?

Yes. Set locale to the preferred answer locale and choose tone=clear, gentle, or technical. These options affect presentation only; they do not change the underlying chart calculations or tool facts.

When does a hosted chat message count?

One complete hosted answer includes one user turn, one model reply, and up to three internal Vedic tool calls. Missing-birth-data clarification responses are not metered as hosted answers. For a metered response, inspect quota.limit, quota.used, quota.remaining, period_key, and reset_at to show current allowance in your application.

How should I retry a timed-out chat request?

Send a client-generated Idempotency-Key with the first request and reuse that key only for an exact retry of the same method, path, query, and JSON body. A completed replay returns Idempotency-Replayed: true and does not consume another hosted-chat message. Generate a new key for every new user message.

What should the client do for quota or temporary capacity errors?

A 429 means the monthly hosted-chat allowance or per-second burst limit was exceeded. Honor Retry-After for burst limits; otherwise wait for the quota reset or add capacity. A 503 means hosted-model capacity or retry-safety storage is temporarily unavailable, the request is not metered, and the identical request can be retried with the same Idempotency-Key after Retry-After.

Can I inspect which model and Vedic tools were used?

Every completed response exposes used_tools, latency_ms, and model. Set debug=true during development to include tool_trace with internal tool arguments and a facts preview. Leave debug=false in user-facing production clients unless that diagnostic information is intentionally protected.

Should the answer be treated as financial, medical, or legal advice?

No. Deterministic Vedic tools ground the chart facts and reduce unsupported model claims, but the final prose remains an AI-generated astrology interpretation. Present it as reflective or spiritual guidance, avoid certainty language, and do not use it as a substitute for qualified financial, medical, legal, or safety-critical advice.