POST/v1/crystals/recommend

Crystal recommendations

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 parameters

zodiac_signoptional

string | null

Western zodiac sign to filter by. Example: 'Taurus', 'Scorpio'.

chakraoptional

string | null

Chakra to filter by. One of: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, Crown.

intentionoptional

string | null

Intention keyword to match. Example: 'protection', 'love', 'abundance'.

limitoptional

integer

Maximum number of recommendations to return.

Response fields

success

boolean

True if the request succeeded

message

string

Human-readable status message

data

object

data.total

integer

Number of crystals returned.

data.filters_applied

object

The filters used for this recommendation.

data.crystals

array[object]

Recommended crystals sorted by match strength.

data.crystals[].slug

string

URL-safe identifier, e.g. 'amethyst', 'blue-sapphire'.

data.crystals[].name

string

Display name of the crystal.

data.crystals[].colors

array[string]

Primary colours of this crystal.

data.crystals[].hardness_mohs

number

Hardness on the Mohs scale (1-10).

data.crystals[].chakras

array[string]

Associated chakras.

data.crystals[].element

string

Classical element: Earth, Water, Fire, Air, or All.

data.crystals[].zodiac_signs

array[string]

Associated Western zodiac signs.

data.crystals[].vedic_planet

string | null

Vedic planetary correspondence. Null if no classical Vedic text assigns this stone.

data.crystals[].vedic_correspondence

string

'navaratna' (primary classical gem), 'uparatna' (substitute gem), or 'none_classical' (no Vedic text assigns this stone).

data.crystals[].western_planet

string | null

Western metaphysical planetary correspondence.

data.crystals[].keywords

array[string]

Primary energy keywords.

data.crystals[].healing_physical

string

Physical healing properties.

data.crystals[].healing_emotional

string

Emotional healing properties.

data.crystals[].healing_spiritual

string

Spiritual healing properties.

data.crystals[].description

string

Overview description.

data.crystals[].origins

array[string]

Primary geographic origins.

data.crystals[].affirmation

string

Affirmation for working with this crystal.

data.crystals[].caution

string | null

Important safety or usage cautions. Null if none.

Errors

authentication_failed

Missing or invalid API key.

ephemeris_unavailable

Upstream ephemeris service error.

insufficient_tier

API key tier does not include this endpoint.

internal_error

Unexpected server error.

ip_rate_limit_exceeded

Too many requests in a short window.

payload_too_large

Request body exceeds the size limit.

resource_not_found

Referenced resource was not found.

validation_error

Request body failed schema validation.

Related endpoints

• Single crystal lookup
• Crystals by Vedic planet
• Complete crystal database
• Crystal recommendations from Vedic natal chart

Request

POST·application/json

curl

curl -X POST "https://api.asterwise.com/v1/crystals/recommend" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"zodiac_sign":"Aries","chakra":"Heart","intention":"abundance","limit":3}'

Python

import asterwise
from asterwise.api.crystals_api import CrystalsApi
from asterwise.models.crystal_recommend_request import CrystalRecommendRequest

configuration = asterwise.Configuration(
    host="https://api.asterwise.com",
    access_token="YOUR_API_KEY",
)

request = CrystalRecommendRequest(
    zodiac_sign="Aries",
    chakra="Heart",
    intention="abundance",
    limit=3,
)

with asterwise.ApiClient(configuration) as client:
    api = CrystalsApi(client)
    result = api.crystals_recommend(crystal_recommend_request=request)
    print(result)

TypeScript

import { createClient, createConfig, crystalsRecommend } from 'asterwise';

const client = createClient(createConfig({
  baseUrl: 'https://api.asterwise.com',
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
}));

const result = await crystalsRecommend({
  client,
  body: {
      "zodiac_sign": "Aries",
      "chakra": "Heart",
      "intention": "abundance",
      "limit": 3
  },
});

console.log(result.data);

Response

200 OK·application/jsonsigned

{
  "success": true,
  "message": "success",
  "data": {
    "total": 3,
    "filters_applied": {
      "zodiac_sign": "Aries",
      "chakra": "Heart",
      "intention": "abundance"
    },
    "crystals": [
      {
        "slug": "bloodstone",
        "name": "Bloodstone",
        "colors": [
          "dark green with red spots"
        ],
        "hardness_mohs": 7.0,
        "chakras": [
          "Root",
          "Heart"
        ],
        "element": "Earth",
        "zodiac_signs": [
          "Aries",
          "Pisces"
        ],
        "vedic_planet": "Mars",
        "vedic_correspondence": "uparatna",
        "western_planet": "Mars",
        "keywords": [
          "courage",
          "resilience",
          "... and 3 more items"
        ],
        "healing_physical": "Supports blood purification, iron absorption, and immune function.",
        "healing_emotional": "Grants resilience and courage in times of extreme adversity.",
        "healing_spiritual": "Known as Heliotrope — the sun turner. Mars Uparatna in Jyotish.",
        "description": "Dark green chalcedony with red iron oxide spots. One of the oldest known gemstones, used in ancient Babylonia. Mars Upar…",
        "origins": [
          "India",
          "Brazil",
          "... and 2 more items"
        ],
        "affirmation": "I face all challenges with courage and am renewed by strength.",
        "caution": null
      },
      {
        "slug": "ruby",
        "name": "Ruby",
        "colors": [
          "red",
          "deep red",
          "... and 1 more item"
        ],
        "hardness_mohs": 9.0,
        "chakras": [
          "Root",
          "Heart"
        ],
        "element": "Fire",
        "zodiac_signs": [
          "Leo",
          "Aries"
        ],
        "vedic_planet": "Sun",
        "vedic_correspondence": "navaratna",
        "western_planet": "Sun",
        "keywords": [
          "leadership",
          "vitality",
          "... and 3 more items"
        ],
        "healing_physical": "Supports heart, blood, and adrenal function.",
        "healing_emotional": "Cultivates leadership, authority, radiant vitality, and immense self-confidence.",
        "healing_spiritual": "Manikya — the primary Navaratna gemstone for the Sun. Activates solar energy and kingly qualities.",
        "description": "Red corundum — the King of Gemstones. Manikya is the primary Sun gemstone in the classical nine Navaratna of Vedic tradi…",
        "origins": [
          "Burma (Myanmar)",
          "Sri Lanka",
          "... and 2 more items"
        ],
        "affirmation": "I lead with confidence and my inner light shines brilliantly.",
        "caution": "Wear only on qualified Jyotish recommendation. Strengthens the Sun — not suitable for those with malefic Sun placements…"
      },
      "... and 1 more item"
    ]
  }
}