---
title: "Hosted Western Astrology Chat (v2)"
method: POST
path: "/api/v2/western/chat"
tags: ["Western v2"]
---

# Hosted Western Astrology Chat (v2)

`POST /api/v2/western/chat`

## Request

- Base URL: `https://api.freeastroapi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.freeastroapi.com/api/v2/western/chat`
- Auth: none declared

Generate a grounded Western astrology answer from the scoped Western MCP tools.

## Headers

- `x-api-key` string, nullable
- `Idempotency-Key` string, nullable: Optional client-generated operation key for safe retries. Reuse it only with the exact same request for up to 24 hours. A replay does not consume another hosted chat message.

## Request body

- WesternChatRequest
  - `message` string, required: User's Western astrology question.
  - `conversation_id` string, nullable: Stable thread id for remembered context.
  - `memory` 'thread' | 'request': thread stores recent turns; request is stateless.
  - `profile` WesternChatProfile
    - `name` string, nullable: Optional display name for natural chat replies.
    - `year` integer, nullable: Birth year.
    - `month` integer, nullable: Birth month.
    - `day` integer, nullable: Birth day.
    - `hour` integer, nullable: Birth hour when known.
    - `minute` integer, nullable: Birth minute when known.
    - `time_known` boolean: Set false when the exact birth time is unknown.
    - `city` string, nullable: Birth city or place label.
    - `lat` number, nullable: Birth latitude.
    - `lng` number, nullable: Birth longitude.
    - `tz_str` string: Timezone: AUTO or an IANA timezone.
    - `house_system` string: Western house system.
    - `zodiac_type` 'tropical' | 'sidereal': Western zodiac type.
  - `partner_profile` WesternChatProfile
    - `name` string, nullable: Optional display name for natural chat replies.
    - `year` integer, nullable: Birth year.
    - `month` integer, nullable: Birth month.
    - `day` integer, nullable: Birth day.
    - `hour` integer, nullable: Birth hour when known.
    - `minute` integer, nullable: Birth minute when known.
    - `time_known` boolean: Set false when the exact birth time is unknown.
    - `city` string, nullable: Birth city or place label.
    - `lat` number, nullable: Birth latitude.
    - `lng` number, nullable: Birth longitude.
    - `tz_str` string: Timezone: AUTO or an IANA timezone.
    - `house_system` string: Western house system.
    - `zodiac_type` 'tropical' | 'sidereal': Western zodiac type.
  - `history` WesternChatHistoryItem[]: Client-provided recent chat context.
    - `role` 'user' | 'assistant', required
    - `content` string, required
  - `locale` string: Preferred answer locale.
  - `tone` 'clear' | 'gentle' | 'technical': Answer tone.
  - `reference_date` string, nullable: Optional YYYY-MM-DD date for daily or transit-sensitive questions.
  - `debug` boolean: Include tool trace for development.

## Response `200`

Hosted Western Chat response. An idempotent replay returns the original response.

- WesternChatResponse
  - `reply` string, required
  - `conversation_id` string, required
  - `needs_birth_data` boolean, required
  - `required_profile` 'primary' | 'partner', nullable
  - `required_fields` string[], nullable
  - `used_tools` string[], required
  - `latency_ms` integer, required
  - `model` string, nullable
  - `quota` WesternChatQuota
    - `tier` string, required
    - `limit` integer, required
    - `used` integer, required
    - `remaining` integer, required
    - `period_key` string, required
    - `reset_at` string, nullable
  - `tool_trace` object, nullable

## Other responses

- `400`: Invalid request, profile, or Idempotency-Key.
- `409`: An Idempotency-Key is in progress or was reused with a different request.
- `422`: Validation Error
- `429`: Hosted-chat monthly message quota or burst limit exceeded.
- `503`: Hosted model capacity, provider rate limit, or retry-safety storage is unavailable.

---

[API](https://skmtc.dev/freeastroapi/apis/astroservice-api.md) · [All operations](https://skmtc.dev/freeastroapi/apis/astroservice-api/llms.txt) · [OpenAPI document](https://skmtc.dev/freeastroapi/apis/astroservice-api/revisions/0c9b4a759522?raw)