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 planet: the planet of a navaratna gem, or the planet an uparatna substitutes for. Null if the stone has no Vedic gem use.

data.crystals[].vedic_correspondence

string

'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).

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

api_key_invalid

Invalid API key format.

api_key_missing

API key is missing. Include it in the Authorization header as 'Bearer YOUR_KEY'.

api_key_not_found

The provided API key was not found. Verify the key in your Asterwise dashboard.

api_key_revoked

This API key has been revoked.

burst_limit_exceeded

Too many requests per minute. Please slow down.

internal_error

Something went wrong on our end. Please try again, or contact [email protected] if the problem persists. Include your request_id when contacting support.

ip_rate_limit_exceeded

Too many requests from this IP address. Please slow down.

monthly_usage_limit_exceeded

Monthly API call limit reached. Upgrade your plan to continue.

payload_too_large

Request body exceeds maximum allowed size of 64KB.

subscription_expired

Your subscription has expired. Please renew at asterwise.com/dashboard to continue.

validation_error

The request couldn't be processed. See the 'details' field for specific field-level issues.

Related endpoints

• Single crystal lookup
• Crystals by Vedic planet
• Complete crystal database
• Natal Chart Crystal Recommendations

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": "red-spinel",
        "name": "Red Spinel",
        "colors": [
          "red",
          "pinkish red",
          "... and 1 more item"
        ],
        "hardness_mohs": 8.0,
        "chakras": [
          "Root",
          "Heart"
        ],
        "element": "Fire",
        "zodiac_signs": [
          "Leo",
          "Aries"
        ],
        "vedic_planet": "Sun",
        "vedic_correspondence": "uparatna",
        "western_planet": "Sun",
        "keywords": [
          "vitality",
          "confidence",
          "... and 2 more items"
        ],
        "healing_physical": "Traditionally linked with vitality, the heart, and circulation.",
        "healing_emotional": "Associated with renewed confidence and steady personal drive.",
        "healing_spiritual": "A traditional Uparatna (substitute) for Ruby (Manikya, Sun) in Jyotish practice.",
        "description": "Magnesium aluminium oxide (MgAl2O4). Historically called balas ruby and long mistaken for ruby. Used in Jyotish as an ac…",
        "origins": [
          "Myanmar",
          "Sri Lanka",
          "... and 2 more items"
        ],
        "affirmation": "I renew my energy and act with quiet confidence.",
        "caution": "Wear only on qualified Jyotish recommendation as Sun substitute."
      },
      "... and 1 more item"
    ]
  }
}