# Crystals and Healing Stones API

> Production-ready crystal healing API + hosted MCP for AI agents and developers. Connect Claude Code, Cursor, VS Code in seconds, no local setup. Look up 80 healing crystals and gemstones with spiritual, emotional, and physical healing properties. Filter by chakra (Root through Crown), zodiac sign, or element. Search by keyword, browse birthstones by month, discover crystal pairings, and get random or daily crystal picks. Includes Mohs hardness ratings, numerological vibrations, planetary associations, and crystal pairing recommendations. Built for wellness apps, crystal shop platforms, chakra balancing tools, astrology integrations, and AI-powered spiritual advisors.

The definitive crystal healing API. Build a wellness app this weekend.

- Product page: https://roxyapi.com/products/crystals-api
- OpenAPI spec: https://roxyapi.com/api/v2/crystals/openapi.json
- Remote MCP server: https://roxyapi.com/mcp/crystals
- Authentication: `X-API-Key` header on every request
- Pricing: https://roxyapi.com/pricing (all domains included in every plan)

## Stats

- latency: <50ms
- uptime: 99.9%
- endpoints: 12

## Features

- Complete crystal database covering 80 healing crystals and gemstones with authoritative spiritual, emotional, and physical healing interpretations
- Filter by chakra, zodiac sign, element, color, or planet for building personalized crystal recommendation engines and healing apps
- Crystal pairing recommendations for every stone showing which crystals work best together for enhanced healing combinations and grid building
- Birthstone mappings for all 12 months plus daily and random crystal endpoints for discovery, push notifications, and wellness widgets
- Rich metadata per crystal: Mohs hardness, numerological vibration, planetary ruler, elemental associations, color varieties, and affirmation
- Sub-20ms response times with structured JSON responses optimized for chatbot integration, LLM consumption, and MCP tool calls
- Multi-language responses in 8 languages (EN, TR, DE, ES, HI, PT, FR, RU) via ?lang= query parameter

## Use Cases

- Crystal shop and e-commerce platforms: enrich product listings with authoritative healing properties, chakra associations, zodiac connections, and pairing suggestions to increase engagement and conversion
- Wellness and meditation apps: integrate daily crystal guidance, chakra-based crystal recommendations, and healing property lookups for personalized spiritual wellness experiences
- AI chatbots and spiritual advisors: power crystal recommendation conversations with structured healing data across spiritual, emotional, and physical dimensions for comprehensive readings
- Astrology and birth chart apps: combine zodiac-based crystal recommendations with natal chart data for personalized crystal prescriptions based on planetary placements and sign energies
- Crystal journal and collection apps: let users explore crystal meanings, track their collection, discover pairings, and receive daily crystal guidance based on their spiritual practice
- Yoga and chakra balancing platforms: recommend crystals for specific chakra work, energy healing sessions, and meditation practices with detailed metaphysical properties

## Endpoints

- `GET /api/v2/crystals/zodiac/{sign}` Crystals by Zodiac Sign
- `GET /api/v2/crystals/chakra/{chakra}` Crystals by Chakra
- `GET /api/v2/crystals/element/{element}` Crystals by Element
- `GET /api/v2/crystals/birthstone/{month}` Birthstone Crystals by Month
- `GET /api/v2/crystals/search` Search Crystals
- `GET /api/v2/crystals/pairings/{id}` Crystal Pairings
- `POST /api/v2/crystals/daily` Daily Crystal
- `GET /api/v2/crystals/random` Random Crystal
- `GET /api/v2/crystals/colors` List Crystal Colors
- `GET /api/v2/crystals/planets` List Crystal Planets
- `GET /api/v2/crystals` List All Crystals
- `GET /api/v2/crystals/{id}` Get Crystal Healing Properties

### Crystals and Healing Stones (`/crystals/`)
- `GET /crystals/zodiac/{sign}` — Crystals paired with a zodiac sign.
- `GET /crystals/chakra/{chakra}` — Chakra stones. Path is case-insensitive, space-separated: `Heart`, `Root`, `Sacral`, `Solar Plexus` (URL-encoded `Solar%20Plexus`), `Throat`, `Third Eye` (`Third%20Eye`), `Crown`.
- `GET /crystals/birthstone/{month}` — Birthstones by month (1 to 12).
- `GET /crystals/search?q=` — Free-text crystal search.

## Example Response

```
GET /api/v2/crystals/amethyst
```

```json
{
  "name": "Amethyst",
  "id": "amethyst",
  "imageUrl": "https://roxyapi.com/img/crystals/amethyst.jpg",
  "description": "Amethyst is a powerful purple quartz prized for protection, intuition, and spiritual growth. It is used for breaking bad habits, deepening meditation, and connecting with higher consciousness. Amethyst vibrates at a high frequency, creating a field of spiritual protection that transmutes negative energy into loving vibrations. It has been treasured since ancient times as a stone of royalty and sobriety, and remains one of the most popular healing crystals worldwide. Found primarily in Brazil, Uruguay, and Zambia, Amethyst rates 7 on the Mohs hardness scale, making it ideal for both jewelry and energy work.",
  "meaning": {
    "spiritual": "Amethyst is thought to provide a protective shield against negative energies, transmuting them into loving, positive vibrations. It is also traditionally associated with clarity of thought, intuition, and inspiration. Amethyst is said to help foster moderation, supporting self-discipline and clarity in daily choices. Amethyst is traditionally believed to support overall vitality and holistic well-being. Crystal enthusiasts associate its energy with enhancing hormone balance, tuning the endocrine system, and strengthening the immune system. It is thought to help reduce physical discomfort and assist the body in combating conditions that affect energy and resilience.",
    "emotional": "Its calming energy supports emotional balance, encourages spiritual awareness, and promotes mindfulness. It encourages mental focus, memory, motivation, and dream recall, while assisting in maintaining inner calm and spiritual wisdom. Amethyst is also believed to support tissue regeneration, cleanse the blood, and alleviate physical, emotional, and psychological stress. Its calming influence can ease headaches, tension, bruising, swelling, and injuries, while promoting overall balance and harmony in hearing, respiratory, skin, and digestive functions.",
    "physical": "Amethyst is traditionally believed to support overall vitality and holistic well-being. Crystal enthusiasts associate its energy with enhancing hormone balance, tuning the endocrine system, and strengthening the immune system. It is thought to help reduce physical discomfort and assist the body in combating conditions that affect energy and resilience. Amethyst is also believed to support tissue regeneration, cleanse the blood, and alleviate physical, emotional, and psychological stress. Its calming influence can ease headaches, tension, bruising, swelling, and injuries, while promoting overall balance and harmony in hearing, respiratory, skin, and digestive functions."
  },
  "chakras": [
    "Third Eye",
    "Crown"
  ],
  "zodiacSigns": [
    "Virgo",
    "Sagittarius",
    "Capricorn",
    "Aquarius",
    "Pisces"
  ],
  "planet": "Jupiter",
  "elements": [
    "Air",
    "Water"
  ],
  "colors": [
    "violet",
    "purple"
  ],
  "hardness": 7,
  "numericalVibration": 3,
  "keywords": [
    "Nobility",
    "Spiritual Awareness",
    "Psychic Abilities",
    "Inner Peace",
    "Healing of Body, Mind & Soul",
    "Positive Transformation",
    "Meditation",
    "Balance",
    "Stress Relief"
  ],
  "birthMonth": 2,
  "affirmation": "I am filled with nobility.",
  "pairsWith": [
    "citrine",
    "rose-quartz",
    "clear-quartz",
    "smoky-quartz",
    "black-tourmaline"
  ]
}
```

## SDK Quick Start

```typescript
// npm install @roxyapi/sdk
import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);
const { data, error } = await roxy.crystals.getCrystalsByZodiac({ path: { sign: 'aries' } });
```

```python
# pip install roxy-sdk
import os
from roxy_sdk import create_roxy
roxy = create_roxy(api_key=os.environ["ROXY_API_KEY"])
result = roxy.crystals.get_crystals_by_zodiac(sign="aries")
```

```php
// composer require roxyapi/sdk (PHP 8.2+, built on Saloon)
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->crystals->getCrystalsByZodiac(sign: 'aries');
```

Method names come from OpenAPI `operationId` (camelCase in TS and PHP, snake_case in Python). TS returns `{ data, error, response }` — check `error` first. Python raises `RoxyAPIError`; PHP throws `RoxyApiException` (catch and switch on `$e->errorCode`).

## MCP Tool Naming

Each REST endpoint has a matching MCP tool on `https://roxyapi.com/mcp/crystals`. Tool name convention is `{http_method_lowercase}_{path_with_slashes_as_underscores_kebab_replaced_with_underscores_braces_stripped}`:

```
GET  /crystals/zodiac/{sign}                  -> get_crystals_zodiac_sign
GET  /crystals/chakra/{chakra}                -> get_crystals_chakra_chakra
GET  /crystals/element/{element}              -> get_crystals_element_element
```

`tools/list` is free and public (no auth). `tools/call` requires `X-API-Key` (same billing as REST — 1 request per call).

## Field Formats (agent gotchas)

Fields LLMs most often get wrong. Copy the format exactly.

| Field | Format | Good | Bad |
|-------|--------|------|-----|
| `sign` (Western horoscope path) | Lowercase zodiac | `aries`, `taurus`, ... `pisces` | `"Aries"`, zodiac symbols, numbers |
| `chakra` | Case-insensitive, space-separated (URL-encode spaces) | `Heart`, `heart`, `Third Eye` (`Third%20Eye`), `Solar Plexus` (`Solar%20Plexus`), `Crown`, `Root`, `Sacral`, `Throat` | `third-eye`, `third_eye`, `thirdEye` |
| `month` (birthstone) | Integer 1-12 | `1`, `12` | `"January"`, `"01"` |

**Path hygiene:** no trailing slashes on any endpoint.

## Multi-language Support

Append `?lang=` to translated endpoints. Supported on this domain: `en, de, es, fr, hi, pt, ru, tr`. English is the default. The `lang` param is ignored on endpoints that have no translatable text.

## Error Contract

Success returns clean JSON, no wrapper. Errors return `{ "error": string, "code": string }`. Switch on `code` (stable):

- `validation_error` (400, returns `issues[]` with all field errors at once)
- `api_key_required` (401), `invalid_api_key` (401)
- `subscription_inactive` (403), `subscription_not_found` (404)
- `not_found` (404; PATH-routing 404s carry a fuzzy `suggestion` field)
- `rate_limit_exceeded` (429)
- `internal_error` (500)

Do not retry on 4xx. Do retry on 429 and 5xx with exponential backoff.

## Related Surfaces

- **Guide:** [Crystals integration guide](https://roxyapi.com/docs/guides/crystals.md)
- **Starter app:** [AI Astrology Chatbot](https://github.com/RoxyAPI/astrology-ai-chatbot) — clone, add an API key, deploy.

## Full Reference

For complete request and response schemas, fetch the OpenAPI spec at https://roxyapi.com/api/v2/crystals/openapi.json. Master agent manifest at https://roxyapi.com/llms.txt. Execution playbook at https://roxyapi.com/AGENTS.md.