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.
2. Nothing else. All crystal content is GET.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

Set the API key once at SDK construction. Detailed setup in SDK install + usage.

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 "https://roxyapi.com/api/v2/crystals/zodiac/pisces" \
  -H "X-API-Key: $ROXY_API_KEY"

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(', ')));

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

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";
}

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

Render the result

Use the generic <roxy-data> renderer from @roxyapi/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.

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

Ready-made starter

The /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.

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. The SDK guide covers typed access across all filters.