---
title: "Natal Chart Crystal Recommendations"
method: POST
path: "/v1/crystals/recommend/natal"
tags: ["Crystals"]
---

# Natal Chart Crystal Recommendations

`POST /v1/crystals/recommend/natal`

## Request

- Base URL: `https://api.asterwise.com`
- URL: `https://api.asterwise.com/v1/crystals/recommend/natal`
- Auth: HTTP bearer

Recommend crystals from the natal chart's functional benefics, using the same rule as POST /v1/astro/gemstones (BPHS Ch.34 lordship, whole-sign from the lagna). Recommended: the lagna lord (always auspicious) = Life Stone (+5), the Yogakaraka = supreme benefic (+5), the 9th lord = Fortune Stone (+4), the 5th lord = Lucky Stone (+3). A 5th/9th lord that also owns a Dusthana (6, 8, 12) is still recommended, with that Dusthana named in warnings[]. Contraindicated (natal_context.contraindicated_lords, never returned): Dusthana lords that own no Trikona, and debilitated or combust planets. Kendra-only and 2nd/3rd/11th lords are neither recommended nor contraindicated. Only crystals with Vedic assignments (Navaratna or Uparatna) are returned. Dangerous gem combinations are flagged in warnings[].

## Request body

- NatalCrystalRequest: Natal crystal recommendations: birth details with the exact birth time (the houses, and so the lordships, depend on it).
  - `location` string, nullable: City name to resolve to lat/lon/tz automatically. Example: 'Mumbai' or 'New Delhi, India'. If provided, latitude, longitude and timezone are not required.
  - `name` string: Person name associated with the birth record
  - `date` string, required: Birth date in YYYY-MM-DD format
  - `time` string, required: Birth time in HH:MM 24-hour format. Required: this endpoint has no sunrise fallback.
  - `latitude` number, nullable: Latitude. Required if location not provided.
  - `longitude` number, nullable: Longitude. Required if location not provided.
  - `timezone` string, nullable: IANA timezone. Required if location not provided (unless utc_offset is given). For dates before the zone adopted a standard time, the birthplace's local mean time (longitude / 15 hours) is used.
  - `utc_offset` string, nullable: Optional explicit UTC offset of the birth time, as ±HH:MM or ±HH:MM:SS (e.g. '+04:51:31' for Bombay mean time). Overrides the offset `timezone` would give. Use it when the birth record states the offset, or for historical local times the IANA database cannot represent.
  - `ayanamsa` 'lahiri' | 'raman' | 'kp' | 'tropical': Sidereal ayanamsa mode used in calculations

## Response `200`

Successful Response

- ApiResponseNatalCrystalResponse
  - `success` boolean: True if the request succeeded
  - `message` string: Human-readable status message
  - `data` NatalCrystalResponse, required
    - `birth_time_provided` boolean: True when a birth time was supplied. False when it was not: house, Ascendant and Moon-dependent results then carry the accuracy limits of an unknown birth time.
    - `natal_context` NatalCrystalContext, required
      - `lagna_sign` string, required: Ascendant sign (English).
      - `lagna_lord` string, required: Lord of the 1st house.
      - `fifth_sign` string, required: 5th house sign (English).
      - `fifth_lord` string, required: Lord of the 5th house (Panchamesh — Lucky Stone).
      - `ninth_sign` string, required: 9th house sign (English).
      - `ninth_lord` string, required: Lord of the 9th house (Bhagyesh — Fortune Stone).
      - `yogakaraka` string, nullable: Yogakaraka planet — lords both a non-1st Kendra and a non-1st Trikona. Null if none for this Lagna.
      - `contraindicated_lords` string[], required: Planets whose gems are contraindicated in this chart: Dusthana (6/8/12) lords that own no Trikona, plus debilitated or combust planets. Same rule as POST /v1/astro/gemstones.
      - `ayanamsa` string: Ayanamsa the chart was cast with: the request's `ayanamsa` (until 2026-10 this always read "lahiri").
    - `total` integer, required
    - `crystals` NatalCrystalEntry[], required
      - `slug` string, required
      - `name` string, required
      - `colors` string[], required
      - `hardness_mohs` number, required
      - `chakras` string[], required
      - `element` string, required
      - `zodiac_signs` string[], required
      - `vedic_planet` string, nullable, required
      - `vedic_correspondence` string, required
      - `western_planet` string, nullable, required
      - `keywords` string[], required
      - `healing_physical` string, required
      - `healing_emotional` string, required
      - `healing_spiritual` string, required
      - `description` string, required
      - `origins` string[], required
      - `affirmation` string, required
      - `caution` string, nullable, required
      - `match_score` integer, required: Gemstone match score based on house lordship.
      - `match_reasons` string[], required: Classical factors — which house lordship triggered this recommendation.
      - `warnings` string[]: Classical cautions for this specific chart context.

## Other responses

- `401`: Authentication failed
- `403`: Authorization failed
- `404`: Resource not found
- `413`: Payload too large
- `422`: Validation error
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream provider error
- `503`: Service unavailable

---

[API](https://skmtc.dev/asterwise/apis/asterwise-api.md) · [All operations](https://skmtc.dev/asterwise/apis/asterwise-api/llms.txt) · [OpenAPI document](https://skmtc.dev/asterwise/apis/asterwise-api/revisions/3c4bbb1194e2?raw)