# Crystals API, what to build and how to call it

> Ship a crystal-by-zodiac page, a chakra stone finder, or a daily crystal widget in under 15 minutes.

Crystal retail and metaphysical shops use this to build "crystals for [zodiac]" and "[chakra] chakra stones" pages. Those two URL patterns are the highest-volume crystal queries on Google. The Roxy crystal catalog covers properties, chakras, zodiac associations, colors, affirmations, and pairings across 80+ stones.

## What you can build

- Crystal recommendation features filtered by zodiac or chakra
- Birthstone pages by month (evergreen gift and jewelry SEO)
- Crystal encyclopedia apps with search
- Wellness and meditation features that surface a stone of the day

## Prerequisites

1. A Roxy API key. Get one on the [pricing page](/pricing).
2. Nothing else. All crystal content is GET.

## Install


### npm
```bash
npm install @roxyapi/sdk
```

### Python
```bash
pip install roxy-sdk
```

### PHP
```bash
composer require roxyapi/sdk
```

Set the API key once at SDK construction. Detailed setup in [SDK install + usage](/docs/sdk).

## Call the endpoint

The #1 crystal call is by zodiac. `crystals for Pisces` and its 11 siblings drive the highest search volume in the domain. Pick a language.


### curl
```bash
curl "https://roxyapi.com/api/v2/crystals/zodiac/pisces" \
  -H "X-API-Key: $ROXY_API_KEY"
```

### TypeScript SDK
```typescript
import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data } = await roxy.crystals.getCrystalsByZodiac({
  path: { sign: 'pisces' },
});

data.crystals.forEach(c => console.log(c.name, (c.colors ?? []).join(', ')));
```

### Python SDK
```python
import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

result = roxy.crystals.get_crystals_by_zodiac(sign='pisces')
for c in result['crystals']:
    print(c['name'], ', '.join(c.get('colors') or []))
```

### PHP SDK
```php
<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$result = $roxy->crystals->getCrystalsByZodiac(sign: 'pisces');
foreach ($result['crystals'] as $c) {
    echo $c['name'], ' ', $c['imageUrl'], "\n";
}
```

### MCP
```bash
claude mcp add-json --scope user roxy-crystals '{"type":"http","url":"https://roxyapi.com/mcp/crystals","headers":{"X-API-Key":"YOUR_KEY"}}'
```

Then ask Claude, "which crystals are best for Pisces?" The agent returns a list with properties. Full setup for Cursor, Claude Desktop, Antigravity, and other clients: [MCP guide](/docs/mcp).

## Render the result

Use the generic `<roxy-data>` renderer from [`@roxyapi/ui`](/docs/ui), exposed in React as `RoxyData`. It accepts any RoxyAPI response and lays out the JSON for you, no per-field markup. Pass the unwrapped `data` straight in.

```tsx
'use client';
import { RoxyData } from '@roxyapi/ui-react';
import type { GetCrystalsZodiacBySignResponse } from '@roxyapi/sdk';

export function CrystalList({ data }: { data: GetCrystalsZodiacBySignResponse }) {
  return <RoxyData data={data} />;
}
```

`data` is the unwrapped SDK response (`const { data } = await roxy.crystals.getCrystalsByZodiac(...)`), typed by `GetCrystalsZodiacBySignResponse` from `@roxyapi/sdk`.

## Ship the rest

### By chakra, the second-highest query pattern

[`GET /crystals/chakra/{chakra}`](/api-reference#tag/crystals-and-healing-stones/GET/crystals/chakra/{chakra}) returns stones for a given chakra. Path is case-insensitive and space-separated: `Root`, `Sacral`, `Solar Plexus` (URL-encoded `Solar%20Plexus`), `Heart`, `Throat`, `Third Eye` (`Third%20Eye`), `Crown`. Wellness and meditation content.

### Birthstone by month, evergreen SEO

[`GET /crystals/birthstone/{month}`](/api-reference#tag/crystals-and-healing-stones/GET/crystals/birthstone/{month}) takes a month number (1 to 12) and returns the birthstone or birthstones for that month. Works for gift-guide and jewelry-app features.

### Search, chatbot-friendly

[`GET /crystals/search?q={term}`](/api-reference#tag/crystals-and-healing-stones/GET/crystals/search) is free-text lookup. Use this when an AI agent needs to find stones by intent ("crystals for anxiety", "crystals for luck").

See the full list at the [Crystals API reference](/api-reference#tag/crystals-and-healing-stones).

## Ready-made starter

The [/starters/astrology-ai-chatbot](/starters/astrology-ai-chatbot) (multi-domain, covers Crystals via Remote MCP) starter ships a working Crystals app you can clone, white-label, and deploy in 30 minutes. MIT licensed. For the render layer, see the component catalog in [@roxyapi/ui](/docs/ui).

## Gotchas

- **Zodiac signs are lowercase, case-insensitive.** `pisces`, `Pisces`, `PISCESS` all work for `/zodiac/{sign}`.
- **Chakra paths are space-separated, case-insensitive.** Use `Third Eye` (URL-encoded `Third%20Eye`) or `third eye`, NOT `third-eye` (kebab fails validation). Same for `Solar Plexus`. Single-word chakras (`Heart`, `Root`, `Sacral`, `Throat`, `Crown`) work as-is in any case.
- **`lang` controls the content language.** Crystal interpretations are translated into 8 languages, pass `?lang=tr` for Turkish, `?lang=es` for Spanish.
- **List endpoints return `{ crystals: [], ... }`.** The top-level object has pagination fields, the array is in `crystals`.

## What to build next

Pair crystals with astrology for a full personality reading in the [AI chatbot tutorial](/docs/tutorials/ai-chatbot). The [SDK guide](/docs/sdk) covers typed access across all filters.