Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Roxy Crystals and Healing Stones API
version: 2.0.0
description: '# RoxyAPI: AI-Native Insight Infrastructure
> **Base URL:** `https://roxyapi.com/api/v2`
> All endpoint paths below are relative to this base URL.'
contact:
name: RoxyAPI Support
url: https://roxyapi.com/contact
license:
name: Proprietary
url: https://roxyapi.com/policy/terms
servers:
- url: /api/v2
description: Production API v2
security:
- apiKey: []
tags:
- name: Crystals and Healing Stones
description: Crystal healing API covering the most popular and widely-searched healing crystals and gemstones, from Amethyst and Rose Quartz to Moldavite and Selenite, each with its spiritual, emotional, and physical properties.
paths:
/crystals/zodiac/{sign}:
get:
operationId: getCrystalsByZodiac
tags:
- Crystals and Healing Stones
summary: Crystals by Zodiac Sign
description: Get healing crystals and gemstones associated with a specific zodiac sign. Returns summary data for each crystal. Use the /crystals/{id} detail endpoint for full healing properties. Supports all 12 zodiac signs from Aries through Pisces. Perfect for personalized crystal recommendations based on astrological birth chart data.
security:
- apiKey: []
parameters:
- schema:
type: string
enum:
- aries
- taurus
- gemini
- cancer
- leo
- virgo
- libra
- scorpio
- sagittarius
- capricorn
- aquarius
- pisces
example: pisces
description: 'Zodiac sign name, case-insensitive (e.g., pisces, Pisces, PISCES all work). Valid: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces.'
required: true
description: 'Zodiac sign name, case-insensitive (e.g., pisces, Pisces, PISCES all work). Valid: aries, taurus, gemini, cancer, leo, virgo, libra, scorpio, sagittarius, capricorn, aquarius, pisces.'
name: sign
in: path
- schema:
type: string
enum:
- en
- tr
- de
- es
- hi
- pt
- fr
- ru
- zh-Hans
- zh-Hant
default: en
example: en
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
required: false
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
name: lang
in: query
- schema:
type: integer
minimum: 1
maximum: 30
default: 20
example: 20
description: 'Maximum items to return per page. Range: 1-30, default 20.'
required: false
description: 'Maximum items to return per page. Range: 1-30, default 20.'
name: limit
in: query
- schema:
type:
- integer
- 'null'
minimum: 0
default: 0
example: 0
description: Number of items to skip for pagination. Default 0.
required: false
description: Number of items to skip for pagination. Default 0.
name: offset
in: query
responses:
'200':
description: Paginated list of crystals associated with the zodiac sign
content:
application/json:
schema:
type: object
properties:
sign:
type: string
example: Pisces
description: The zodiac sign that was queried.
total:
type: number
example: 9
description: Total number of crystals associated with this zodiac sign.
limit:
type: number
example: 20
description: Maximum crystals returned per page.
offset:
type: number
example: 0
description: Number of crystals skipped.
crystals:
type: array
items:
type: object
properties:
name:
type: string
example: Amethyst
description: Crystal display name.
id:
type: string
example: amethyst
description: URL-safe crystal identifier for detail lookup.
imageUrl:
type:
- string
- 'null'
example: https://roxyapi.com/img/crystals/amethyst.jpg
description: URL to crystal photograph for visual identification.
colors:
type:
- array
- 'null'
items:
type: string
example:
- violet
- purple
description: Primary colors of this crystal variety. Null when color data is unavailable.
required:
- name
- id
- imageUrl
- colors
description: Crystal summaries for this zodiac sign. Call /crystals/{id} for full healing properties.
required:
- sign
- total
- limit
- offset
- crystals
'400':
description: Validation error. `issues[]` lists every failed field.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: First issue summary.
code:
type: string
enum:
- validation_error
issues:
type: array
description: Every validation failure. Use this to rebuild a valid request.
items:
type: object
properties:
path:
type: string
description: Dot-separated field path, or "(root)" for top-level.
message:
type: string
code:
type: string
description: Zod issue code (invalid_type, too_small, too_big, invalid_string, ...).
expected:
type: string
description: Expected type for invalid_type.
minimum:
description: Minimum bound for too_small issues.
oneOf:
- type: number
- type: string
maximum:
description: Maximum bound for too_big issues.
oneOf:
- type: number
- type: string
inclusive:
type: boolean
format:
type: string
description: Format name for string issues (regex, email, url, uuid).
pattern:
type: string
description: Regex pattern when format is regex.
required:
- path
- message
required:
- error
- code
- issues
'401':
description: Invalid or missing API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'405':
description: Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
headers:
Allow:
description: Comma-separated list of allowed methods (RFC 9110).
schema:
type: string
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
enum:
- method_not_allowed
allow:
type: array
items:
type: string
description: Allowed HTTP methods for this path. Mirrors the Allow response header.
docs:
type: string
description: Link to the product page for this domain.
required:
- error
- code
- allow
'429':
description: Monthly rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
/crystals/chakra/{chakra}:
get:
operationId: getCrystalsByChakra
tags:
- Crystals and Healing Stones
summary: Crystals by Chakra
description: 'Get healing crystals and gemstones that resonate with a specific chakra energy center. Returns summary data for each crystal. Use the /crystals/{id} detail endpoint for full healing properties. Supports all 7 primary chakras: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, and Crown. Essential for crystal grid building, chakra balancing, and energy healing applications.'
security:
- apiKey: []
parameters:
- schema:
type: string
enum:
- Root
- Sacral
- Solar Plexus
- Heart
- Throat
- Third Eye
- Crown
example: Heart
description: 'Chakra name, case-insensitive (e.g., heart, Heart, HEART all work). Valid: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, Crown.'
required: true
description: 'Chakra name, case-insensitive (e.g., heart, Heart, HEART all work). Valid: Root, Sacral, Solar Plexus, Heart, Throat, Third Eye, Crown.'
name: chakra
in: path
- schema:
type: string
enum:
- en
- tr
- de
- es
- hi
- pt
- fr
- ru
- zh-Hans
- zh-Hant
default: en
example: en
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
required: false
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
name: lang
in: query
- schema:
type: integer
minimum: 1
maximum: 30
default: 20
example: 20
description: 'Maximum items to return per page. Range: 1-30, default 20.'
required: false
description: 'Maximum items to return per page. Range: 1-30, default 20.'
name: limit
in: query
- schema:
type:
- integer
- 'null'
minimum: 0
default: 0
example: 0
description: Number of items to skip for pagination. Default 0.
required: false
description: Number of items to skip for pagination. Default 0.
name: offset
in: query
responses:
'200':
description: Paginated list of crystals for the specified chakra
content:
application/json:
schema:
type: object
properties:
chakra:
type: string
example: Heart
description: The chakra energy center that was queried.
total:
type: number
example: 33
description: Total number of crystals associated with this chakra.
limit:
type: number
example: 20
description: Maximum crystals returned per page.
offset:
type: number
example: 0
description: Number of crystals skipped.
crystals:
type: array
items:
type: object
properties:
name:
type: string
example: Amethyst
description: Crystal display name.
id:
type: string
example: amethyst
description: URL-safe crystal identifier for detail lookup.
imageUrl:
type:
- string
- 'null'
example: https://roxyapi.com/img/crystals/amethyst.jpg
description: URL to crystal photograph for visual identification.
colors:
type:
- array
- 'null'
items:
type: string
example:
- violet
- purple
description: Primary colors of this crystal variety. Null when color data is unavailable.
required:
- name
- id
- imageUrl
- colors
description: Crystal summaries for this chakra. Call /crystals/{id} for full healing properties.
required:
- chakra
- total
- limit
- offset
- crystals
'400':
description: Validation error. `issues[]` lists every failed field.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: First issue summary.
code:
type: string
enum:
- validation_error
issues:
type: array
description: Every validation failure. Use this to rebuild a valid request.
items:
type: object
properties:
path:
type: string
description: Dot-separated field path, or "(root)" for top-level.
message:
type: string
code:
type: string
description: Zod issue code (invalid_type, too_small, too_big, invalid_string, ...).
expected:
type: string
description: Expected type for invalid_type.
minimum:
description: Minimum bound for too_small issues.
oneOf:
- type: number
- type: string
maximum:
description: Maximum bound for too_big issues.
oneOf:
- type: number
- type: string
inclusive:
type: boolean
format:
type: string
description: Format name for string issues (regex, email, url, uuid).
pattern:
type: string
description: Regex pattern when format is regex.
required:
- path
- message
required:
- error
- code
- issues
'401':
description: Invalid or missing API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'405':
description: Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
headers:
Allow:
description: Comma-separated list of allowed methods (RFC 9110).
schema:
type: string
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
enum:
- method_not_allowed
allow:
type: array
items:
type: string
description: Allowed HTTP methods for this path. Mirrors the Allow response header.
docs:
type: string
description: Link to the product page for this domain.
required:
- error
- code
- allow
'429':
description: Monthly rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
/crystals/element/{element}:
get:
operationId: getCrystalsByElement
tags:
- Crystals and Healing Stones
summary: Crystals by Element
description: 'Get healing crystals and gemstones associated with a specific natural element. Returns summary data for each crystal. Use the /crystals/{id} detail endpoint for full healing properties. Supports five elements: Earth, Water, Fire, Air, and Storm. Essential for elemental crystal selection, nature-based healing, and element-themed crystal grid applications.'
security:
- apiKey: []
parameters:
- schema:
type: string
enum:
- Earth
- Water
- Fire
- Air
- Storm
example: Water
description: 'Element name, case-insensitive (e.g., water, Water, WATER all work). Valid: Earth, Water, Fire, Air, Storm.'
required: true
description: 'Element name, case-insensitive (e.g., water, Water, WATER all work). Valid: Earth, Water, Fire, Air, Storm.'
name: element
in: path
- schema:
type: string
enum:
- en
- tr
- de
- es
- hi
- pt
- fr
- ru
- zh-Hans
- zh-Hant
default: en
example: en
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
required: false
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
name: lang
in: query
- schema:
type: integer
minimum: 1
maximum: 30
default: 20
example: 20
description: 'Maximum items to return per page. Range: 1-30, default 20.'
required: false
description: 'Maximum items to return per page. Range: 1-30, default 20.'
name: limit
in: query
- schema:
type:
- integer
- 'null'
minimum: 0
default: 0
example: 0
description: Number of items to skip for pagination. Default 0.
required: false
description: Number of items to skip for pagination. Default 0.
name: offset
in: query
responses:
'200':
description: Paginated list of crystals for the specified element
content:
application/json:
schema:
type: object
properties:
element:
type: string
example: Water
description: The element that was queried.
total:
type: number
example: 29
description: Total number of crystals associated with this element.
limit:
type: number
example: 20
description: Maximum crystals returned per page.
offset:
type: number
example: 0
description: Number of crystals skipped.
crystals:
type: array
items:
type: object
properties:
name:
type: string
example: Amethyst
description: Crystal display name.
id:
type: string
example: amethyst
description: URL-safe crystal identifier for detail lookup.
imageUrl:
type:
- string
- 'null'
example: https://roxyapi.com/img/crystals/amethyst.jpg
description: URL to crystal photograph for visual identification.
colors:
type:
- array
- 'null'
items:
type: string
example:
- violet
- purple
description: Primary colors of this crystal variety. Null when color data is unavailable.
required:
- name
- id
- imageUrl
- colors
description: Crystal summaries for this element. Call /crystals/{id} for full healing properties.
required:
- element
- total
- limit
- offset
- crystals
'400':
description: Validation error. `issues[]` lists every failed field.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: First issue summary.
code:
type: string
enum:
- validation_error
issues:
type: array
description: Every validation failure. Use this to rebuild a valid request.
items:
type: object
properties:
path:
type: string
description: Dot-separated field path, or "(root)" for top-level.
message:
type: string
code:
type: string
description: Zod issue code (invalid_type, too_small, too_big, invalid_string, ...).
expected:
type: string
description: Expected type for invalid_type.
minimum:
description: Minimum bound for too_small issues.
oneOf:
- type: number
- type: string
maximum:
description: Maximum bound for too_big issues.
oneOf:
- type: number
- type: string
inclusive:
type: boolean
format:
type: string
description: Format name for string issues (regex, email, url, uuid).
pattern:
type: string
description: Regex pattern when format is regex.
required:
- path
- message
required:
- error
- code
- issues
'401':
description: Invalid or missing API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'405':
description: Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
headers:
Allow:
description: Comma-separated list of allowed methods (RFC 9110).
schema:
type: string
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
enum:
- method_not_allowed
allow:
type: array
items:
type: string
description: Allowed HTTP methods for this path. Mirrors the Allow response header.
docs:
type: string
description: Link to the product page for this domain.
required:
- error
- code
- allow
'429':
description: Monthly rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
/crystals/birthstone/{month}:
get:
operationId: getBirthstones
tags:
- Crystals and Healing Stones
summary: Birthstone Crystals by Month
description: Get the traditional birthstone crystals for a given birth month. Returns summary data for each crystal. Use the /crystals/{id} detail endpoint for full healing properties. Based on GIA-authoritative birthstone assignments. Perfect for birthday gift recommendations, personalized crystal suggestions, and birthstone jewelry applications.
security:
- apiKey: []
parameters:
- schema:
type: integer
minimum: 1
maximum: 12
example: 2
description: Birth month as a number from 1 (January) to 12 (December).
required: true
description: Birth month as a number from 1 (January) to 12 (December).
name: month
in: path
- schema:
type: string
enum:
- en
- tr
- de
- es
- hi
- pt
- fr
- ru
- zh-Hans
- zh-Hant
default: en
example: en
# --- truncated at 32 KB (119 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/roxyapi/refs/heads/main/openapi/roxyapi-crystals-and-healing-stones-api-openapi.yml