Back to Docs

Hosted Western AI Chat

Hosted Western AI Chat

POST/api/v2/western/chat

Ask a Western astrology question and receive a hosted AI answer grounded in FreeAstroAPI's natal, horoscope, transit, and synastry tools.

Authentication: send x-api-key. Hosted AI Chat is metered separately from ordinary API requests and shared across Western and Vedic Chat: 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/western/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 concise Western astrology answer, thread context for follow-ups, the scoped tools used for chart facts, model latency, and the shared Hosted AI Chat message quota after a metered answer.

Tool Coverage and Limits

One hosted message includes one user turn, one model answer, and up to three scoped Western tool calls. The orchestrator uses natal, daily or weekly horoscope, transit timeline, and synastry tools when the question needs chart facts. These internal calls do not consume ordinary API request quota.

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

To run your own model instead, use the hosted MCP server with scope=western-bot.

Example Request

curl -X POST "https://api.freeastroapi.com/api/v2/western/chat" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -H "Idempotency-Key: UNIQUE_KEY_PER_USER_MESSAGE" \
 -d '{
  "message": "What transit themes should I focus on this month?",
  "conversation_id": "western-avery-2026-07",
  "memory": "thread",
  "profile": {
    "name": "Avery",
    "year": 1990,
    "month": 1,
    "day": 15,
    "hour": 9,
    "minute": 30,
    "city": "New York",
    "tz_str": "America/New_York",
    "house_system": "placidus",
    "zodiac_type": "tropical"
  },
  "reference_date": "2026-07-21",
  "tone": "clear"
}'

Request Parameters

Provide profile.city or both profile.lat and profile.lng for personal chart questions. Birth time is required for houses, angles, and precise transit timing. Compatibility questions also require partner_profile.

Field
message
Type
string
Required
Yes
Description
The user message, up to 4,000 characters.
Field
conversation_id
Type
string
Required
No
Description
Thread id returned by an earlier request when memory=thread.
Field
memory
Type
string
Required
No
Description
request for stateless use, or thread to reuse recent turns. Default is request.
Field
profile
Type
object
Required
No
Description
Primary person's birth data. Required for chart-specific answers.
Field
profile.name
Type
string
Required
No
Description
Optional display name for the primary person.
Field
profile.year / month / day
Type
integer
Required
No
Description
Birth date. Required for personal chart answers.
Field
profile.hour / minute
Type
integer
Required
No
Description
Birth time. Required for houses, angles, and precise transit timing.
Field
profile.time_known
Type
boolean
Required
No
Description
Set false when the birth time is unknown. The assistant avoids house, angle, and exact-timing claims.
Field
profile.city
Type
string
Required
No
Description
Birth city. Provide city or both lat and lng.
Field
profile.lat / lng
Type
number
Required
No
Description
Birth coordinates. Recommended for stable production results.
Field
profile.tz_str
Type
string
Required
No
Description
Optional IANA timezone such as America/New_York.
Field
profile.house_system
Type
string
Required
No
Description
Western house system. Defaults to placidus.
Field
profile.zodiac_type
Type
string
Required
No
Description
tropical (default) or sidereal.
Field
partner_profile
Type
object
Required
No
Description
Second person's birth data for compatibility or synastry questions.
Field
history
Type
array<object>
Required
No
Description
Up to 12 client-managed conversation items when memory=request.
Field
locale
Type
string
Required
No
Description
Preferred answer locale.
Field
tone
Type
string
Required
No
Description
clear, gentle, or technical. It changes presentation, not chart facts.
Field
reference_date
Type
string
Required
No
Description
User-local YYYY-MM-DD date for reproducible daily, weekly, and timing questions.
Field
debug
Type
boolean
Required
No
Description
Returns a protected diagnostic tool trace. Keep false for normal end-user responses.

Response Shape

Field
reply
Type
string
Required
n/a
Description
Concise hosted AI answer grounded in scoped Western astrology 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 more birth data before a personal answer.
Field
required_profile
Type
string
Required
n/a
Description
primary or partner when needs_birth_data is true.
Field
required_fields
Type
array<string>
Required
n/a
Description
Missing input groups, such as birth_date, birth_time, or birth_place.
Field
used_tools
Type
array<string>
Required
n/a
Description
Scoped Western tool names used for deterministic 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.
Field
quota
Type
object
Required
n/a
Description
Shared Hosted AI Chat message usage after a metered answer.
Field
quota.tier / limit / used / remaining
Type
mixed
Required
n/a
Description
Resolved plan and current shared message allowance.
Field
quota.period_key / reset_at
Type
string
Required
n/a
Description
Free trial or monthly quota period and its reset timestamp.
Field
tool_trace
Type
object
Required
n/a
Description
Returned only when debug=true; contains protected internal diagnostics.

Sample Request Example

This sample asks a transit question with thread memory. Send the returned conversation_id on follow-ups, and generate a new Idempotency-Key for every new user message.

{
  "message": "What transit themes should I focus on this month?",
  "conversation_id": "western-avery-2026-07",
  "memory": "thread",
  "profile": {
    "name": "Avery",
    "year": 1990,
    "month": 1,
    "day": 15,
    "hour": 9,
    "minute": 30,
    "city": "New York",
    "tz_str": "America/New_York",
    "house_system": "placidus",
    "zodiac_type": "tropical"
  },
  "reference_date": "2026-07-21",
  "tone": "clear"
}

Sample Response Example

V2

This representative response documents the shape and quota fields. Reply text, tools, timing, and latency depend on the birth data, question, context, and hosted model response.

{
  "reply": "This month favors steady adjustments over dramatic commitments. Use the active transit themes to review priorities, communicate clearly, and pace decisions around the dates returned by the timeline.",
  "conversation_id": "western-avery-2026-07",
  "needs_birth_data": false,
  "used_tools": [
    "v1_western_transits_timeline"
  ],
  "latency_ms": 1180,
  "model": "gemini-2.5-flash",
  "quota": {
    "tier": "high",
    "limit": 2000,
    "used": 47,
    "remaining": 1953,
    "period_key": "2026-07",
    "reset_at": "2026-08-01T00:00:00Z"
  }
}

Related Docs

Hosted MCP / BYOMWestern natal chartTransit timelineSynastryPricing

FAQ

What is Hosted Western AI Chat?

It is a hosted orchestration endpoint that combines a managed AI model with deterministic Western astrology calculations. It selects the relevant scoped tool, interprets the returned chart facts, and returns concise natural-language guidance with conversation, latency, model, and quota metadata.

Is this different from the western-bot MCP scope?

Yes. Hosted Western AI Chat runs FreeAstroAPI's model layer and uses Hosted AI Chat messages. western-bot is the bring-your-own-model path: connect your own Gemini, OpenAI, Anthropic, or local model to MCP, pay that model provider directly, and use normal FreeAstroAPI quota for tool calls.

Can users ask personal questions without a birth time?

For broad natal or compatibility themes, send time_known=false with a birth date and city or coordinates. The assistant avoids houses, angles, and exact timing claims. Transit timing, house-based analysis, and angle-sensitive questions require an accurate birth time.

What does a relationship question need?

Send the person asking as profile and the other person as partner_profile. Names are optional display labels; birth data drives the calculations. The response describes themes and does not expose raw compatibility scores as a chat verdict.

Do Western and Vedic Chat have separate allowances?

No. They consume the same Hosted AI Chat message balance. This keeps billing simple: a completed hosted answer is one shared message regardless of whether its facts come from Western or Vedic tools.

How should a client retry a request?

Send a client-generated Idempotency-Key with the first request. Reuse it 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 AI Chat message.