---
title: "Crystal recommendations"
method: POST
path: "/v1/crystals/recommend"
tags: ["Crystals"]
---

# Crystal recommendations

`POST /v1/crystals/recommend`

## Request

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

Recommend crystals based on zodiac sign, chakra, or intention keyword. At least one filter must be provided. Providing multiple filters returns crystals that match the most criteria first. Valid chakras: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, Crown. Returns up to `limit` crystals (default 5, max 20).

## Request body

- CrystalRecommendRequest
  - `zodiac_sign` string, nullable: Western zodiac sign to filter by. Example: 'Taurus', 'Scorpio'.
  - `chakra` string, nullable: Chakra to filter by. One of: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, Crown.
  - `intention` string, nullable: Intention keyword to match. Example: 'protection', 'love', 'abundance'.
  - `limit` integer: Maximum number of recommendations to return.

## Response `200`

Successful Response

- ApiResponseCrystalRecommendResponse
  - `success` boolean: True if the request succeeded
  - `message` string: Human-readable status message
  - `data` CrystalRecommendResponse, required
    - `total` integer, required: Number of crystals returned.
    - `filters_applied` object, required: The filters used for this recommendation.
    - `crystals` CrystalEntry[], required: Recommended crystals sorted by match strength.
      - `slug` string, required: URL-safe identifier, e.g. 'amethyst', 'blue-sapphire'.
      - `name` string, required: Display name of the crystal.
      - `colors` string[], required: Primary colours of this crystal.
      - `hardness_mohs` number, required: Hardness on the Mohs scale (1-10).
      - `chakras` string[], required: Associated chakras.
      - `element` string, required: Classical element: Earth, Water, Fire, Air, or All.
      - `zodiac_signs` string[], required: Associated Western zodiac signs.
      - `vedic_planet` string, nullable: Vedic planet: the planet of a navaratna gem, or the planet an uparatna substitutes for. Null if the stone has no Vedic gem use.
      - `vedic_correspondence` string, required: 'navaratna' (primary classical gem, Phaladeepika table), 'uparatna' (substitute gem — includes common modern substitutes such as Tiger's Eye for Ketu; the description says when a substitute is not classical), or 'none_classical' (no Vedic gem use).
      - `western_planet` string, nullable: Western metaphysical planetary correspondence.
      - `keywords` string[], required: Primary energy keywords.
      - `healing_physical` string, required: Physical healing properties.
      - `healing_emotional` string, required: Emotional healing properties.
      - `healing_spiritual` string, required: Spiritual healing properties.
      - `description` string, required: Overview description.
      - `origins` string[], required: Primary geographic origins.
      - `affirmation` string, required: Affirmation for working with this crystal.
      - `caution` string, nullable: Important safety or usage cautions. Null if none.

## 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/e77850f7c569?raw)