---
title: "Hosted Vedic Chat (v2)"
method: POST
path: "/api/v2/vedic/chat"
tags: ["Vedic v2"]
---

# Hosted Vedic Chat (v2)

`POST /api/v2/vedic/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/vedic/chat`
- Auth: none declared

Hosted Vedic Chat orchestration.

This endpoint uses FreeAstroAPI's scoped Vedic MCP tools for deterministic
chart facts, then generates a concise answer through the hosted model layer.
Developers who bring their own model should use `/mcp/vedic-bot` directly.

## 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

- VedicChatRequest
  - `message` string, required: User's Vedic astrology question.
  - `conversation_id` string, nullable: Stable thread id for remembered context.
  - `memory` 'thread' | 'request': thread stores recent turns; request is stateless.
  - `profile` VedicChatProfile
    - `name` string, nullable: Optional display name for natural chat replies. It is not used in astrology calculations.
    - `year` integer, nullable: Astronomical birth year (0-2399; 0 = 1 BCE).
    - `month` integer, nullable: Birth month.
    - `day` integer, nullable: Birth day.
    - `hour` integer, nullable: Birth hour.
    - `minute` integer, nullable: Birth minute.
    - `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.
    - `ayanamsha` string: Ayanamsha.
    - `house_system` string: House system.
    - `node_type` string: Node type.
  - `partner_profile` VedicChatProfile
    - `name` string, nullable: Optional display name for natural chat replies. It is not used in astrology calculations.
    - `year` integer, nullable: Astronomical birth year (0-2399; 0 = 1 BCE).
    - `month` integer, nullable: Birth month.
    - `day` integer, nullable: Birth day.
    - `hour` integer, nullable: Birth hour.
    - `minute` integer, nullable: Birth minute.
    - `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.
    - `ayanamsha` string: Ayanamsha.
    - `house_system` string: House system.
    - `node_type` string: Node type.
  - `history` VedicChatHistoryItem[]: 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, date, nullable: Optional local reference date for daily, dasha, or gochar questions.
  - `debug` boolean: Include tool trace for development.

## Response `200`

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

- VedicChatResponse
  - `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` VedicChatQuota
    - `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 Idempotency-Key.
- `409`: The Idempotency-Key is already in progress or was reused with a different request.
- `422`: Validation Error
- `429`: Hosted-chat monthly message quota or per-second burst limit exceeded.
- `503`: Hosted-chat capacity or retry-safety storage is temporarily unavailable. The request is not metered.

---

[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)