Crystal healing API guide

Ship a crystal-by-zodiac page, a chakra stone finder, or a daily crystal widget.

Crystal retail and metaphysical shops use this to build zodiac collections and chakra stone finders. The RoxyAPI crystal catalog covers properties, chakras, zodiac associations, colors, affirmations, and pairings. Present these associations as traditional or symbolic interpretations, without medical treatment claims.

What you can build

• Crystal recommendation features filtered by zodiac or chakra
• Birthstone pages by month for gifts and jewelry
• Crystal encyclopedia apps with search
• Wellness and meditation features that surface a stone of the day

Prerequisites

1. A RoxyAPI key. Get your API key.
2. A backend for authenticated API calls. Catalog lookups use GET; daily crystal selection uses POST.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

dotnet add package RoxyApi.Sdk

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

Call the endpoint

Start with a zodiac collection, such as crystals associated with Pisces. 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, error } = await roxy.crystals.getCrystalsByZodiac({
  path: { sign: 'pisces' },
});
if (error) throw error;

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

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var result = await roxy.Crystals.Zodiac["pisces"].GetAsync();

foreach (var c in result!.Crystals!)
    Console.WriteLine($"{c.Name}: {string.Join(", ", c.Colors ?? new())}");

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 crystal grid from @roxyapi/ui, <roxy-crystal-grid>, exposed in React as RoxyCrystalGrid. It renders any crystal list response as a photo gallery titled from the filter; pass the unwrapped data straight in. For one stone, <roxy-crystal-card> takes the GET /crystals/{id} response.

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

export function CrystalList({ data }: { data: GetCrystalsZodiacBySignResponse }) {
  return <RoxyCrystalGrid 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

GET /crystals/chakra/{chakra} returns stones for a given chakra. Path is case-insensitive and punctuation-insensitive: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, Crown. For the two-word chakras any spelling works, so Third Eye, third-eye, third_eye and Third%20Eye all resolve to the same chakra. Wellness and meditation content.

Birthstone by month

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, detail and saved collections

GET /crystals/search?q={term} is free-text lookup. Render the crystals summaries using id, name, colors and imageUrl, allowing for nullable colors and images. Use total, limit and offset for pagination.

Open GET /crystals/{id} for the complete entry, including meanings, associations, pairings and affirmation. Store favorites by crystal id in your app so a saved collection can reopen the same entry. For an offline collection, retain the fetched language and your application cache version with each saved entry, show when it was fetched, and refresh when connectivity returns. A failed refresh should preserve the last saved entry and show its age.

Daily crystal and optional reminders

POST /crystals/daily accepts optional seed and date fields. The same seed and date select the same crystal; an omitted date uses today in UTC. Use a pseudonymous seed rather than an email address. The response includes id, name, imageUrl, description, chakras, zodiacSigns and affirmation; fetch the detail entry by id when the reader opens it.

If your app offers daily reminders, let the reader choose a local delivery time and opt out. Present the crystal and affirmation as a reflective practice, without promises of health effects.

See the full list at the Crystals API reference.

Ready-made template

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

Gotchas

• Zodiac signs are lowercase, case-insensitive. pisces, Pisces, PISCES all work for /zodiac/{sign}.
• Chakra paths ignore case and punctuation. For the two-word chakras, Third Eye, third-eye, third_eye and Third%20Eye are all accepted and all mean the same thing. Same for Solar Plexus. Single-word chakras (Heart, Root, Sacral, Throat, Crown) work as-is in any case. The response always echoes the canonical spelling with a space.
• lang controls the content language. Crystal interpretations are translated into 10+ 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.