Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Roxy Numerology 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: Numerology
description: Numerology API to calculate life path, expression, soul urge, personality, and maturity numbers, with Pinnacle and Challenge life-phase timing, Hidden Passion, Subconscious Self, and Cornerstone and Capstone name analysis.
paths:
/numerology/life-path:
post:
operationId: calculateLifePath
tags:
- Numerology
summary: Calculate Life Path number - Most important numerology calculation
description: Calculate your Life Path number from your birth date using Pythagorean numerology. This is the most significant number in your numerology chart, revealing your life purpose, natural talents, and destiny path. Automatically detects Master Numbers (11, 22, 33) and Karmic Debt numbers (13, 14, 16, 19). Returns comprehensive interpretation including personality traits, strengths, challenges, career guidance, relationship compatibility, and spiritual insights. Perfect for numerology apps, birth chart calculators, life purpose discovery tools, personal development platforms, and astrology services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33.
security:
- apiKey: []
parameters:
- 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
requestBody:
content:
application/json:
schema:
type: object
properties:
year:
type: integer
minimum: 100
maximum: 2100
example: 1990
description: Birth year between 100 and 2100. Supports historical figures like Einstein (1879) and Shakespeare (1564).
month:
type: integer
minimum: 1
maximum: 12
example: 7
description: Birth month (1-12)
day:
type: integer
minimum: 1
maximum: 31
example: 15
description: Birth day (1-31)
required:
- year
- month
- day
responses:
'200':
description: Successfully calculated Life Path number with detailed interpretation
content:
application/json:
schema:
type: object
properties:
number:
type: number
example: 5
description: Your Life Path number, the single most important number in Pythagorean numerology. Values range from 1 to 9 for single digits, or 11, 22, 33 for Master Numbers.
calculation:
type: string
example: 'Month: 7, Day: 15 → 1+5 = 6, Year: 1990 → 1+9+9+0 = 19 → 1+9 = 10 → 1+0 = 1 → 7+6+1=14 → 5'
description: Full step-by-step breakdown of the 3-Cycle Pythagorean reduction. Shows how month, day, and year each reduce independently before combining into the final Life Path number.
type:
type: string
enum:
- single
- master
example: single
description: Whether this is a standard single-digit number (1 to 9) or a Master Number (11, 22, 33). Master Numbers carry amplified spiritual significance and are never reduced further.
hasKarmicDebt:
type: boolean
example: false
description: Indicates whether a Karmic Debt number (13, 14, 16, or 19) appeared during the reduction chain. Karmic Debt reveals past-life challenges carried into this lifetime.
karmicDebtNumber:
type: number
example: 14
description: The specific Karmic Debt number detected during reduction, if any. Each debt number (13, 14, 16, 19) represents a distinct past-life lesson requiring resolution.
karmicDebtMeaning:
type: object
properties:
description:
type: string
example: Karmic Debt of Abuse of Freedom
description: Title describing the karmic debt theme and core past-life pattern.
challenge:
type: string
example: Past life misuse of personal freedom, possibly through excess or manipulation.
description: The specific challenge or pattern from past lives that must be confronted.
resolution:
type: string
example: Learn balance, moderation, and responsible use of freedom.
description: Practical guidance for resolving the karmic debt and transforming the challenge into growth.
required:
- description
- challenge
- resolution
description: Detailed interpretation of the Karmic Debt number when present. Only returned when hasKarmicDebt is true.
meaning:
type: object
properties:
title:
type: string
example: The Adventurer
description: Numerology archetype name for this Life Path number. Encapsulates the core identity and energy in a single phrase, such as "The Leader" for 1 or "The Master Builder" for 22.
keywords:
type: array
items:
type: string
example:
- adventurous
- freedom
- versatile
- dynamic
- curious
description: Ten defining personality traits and energetic themes associated with this number. Useful for quick personality snapshots, tag clouds, and compatibility matching.
description:
type: string
example: In the span of single-digit numbers 1 to 9, 5 is the number in the exact middle. It acts as a go-between and a pivotal point of change...
description: In-depth 300 to 500 word interpretation covering personality, purpose, and life themes. Written by numerology experts with decades of practice. Suitable for full-page readings and detailed reports.
strengths:
type: array
items:
type: string
example:
- Curious
- Adaptable
- Social
description: Core strengths and positive qualities. Each entry includes a trait name followed by a detailed explanation of how it manifests in daily life.
challenges:
type: array
items:
type: string
example:
- Non-committal
- Unreliable
- Directionless
description: Growth areas and shadow qualities to be aware of. Each entry names the challenge and explains its root cause and how to work through it constructively.
career:
type: string
example: Life Path 5 thrives in careers that offer freedom, variety, and constant stimulation...
description: Tailored career guidance covering ideal industries, roles, and work environments. Includes specific job titles and explains why certain professional paths align with this number.
relationships:
type: string
example: Life Path 5 individuals are exciting, charming, and freedom-loving partners...
description: Love, friendship, and family dynamics. Covers romantic compatibility with other Life Path numbers, communication style, and the key relationship lessons for this number.
spirituality:
type: string
example: Five is the rebel, the traveler, the agent of change. It vibrates with adventure and liberation...
description: Spiritual path, soul lessons, and recommended practices. Explores the deeper purpose behind this number and offers guidance for personal growth and inner alignment.
required:
- title
- keywords
- description
- strengths
- challenges
- career
- relationships
- spirituality
required:
- number
- calculation
- type
- hasKarmicDebt
- meaning
'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
/numerology/expression:
post:
operationId: calculateExpression
tags:
- Numerology
summary: Calculate Expression number - Natural talents and life goals
description: Calculate your Expression (Destiny) number from your full birth name using Pythagorean numerology. This number reveals your natural talents, abilities, and life goals. It shows what you came here to do and what tools you have to accomplish your life purpose. Returns comprehensive interpretation including personality traits, career paths, relationship dynamics, and spiritual insights. Automatically detects Master Numbers (11, 22, 33). Perfect for name numerology apps, career guidance tools, personal development platforms, and talent assessment services. Get detailed 300-500 word meanings for all numbers 1-9, 11, 22, and 33.
security:
- apiKey: []
parameters:
- 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
requestBody:
content:
application/json:
schema:
type: object
properties:
fullName:
type: string
minLength: 1
maxLength: 200
example: John William Smith
description: Full birth name (first, middle, last)
required:
- fullName
responses:
'200':
description: Successfully calculated Expression number with detailed interpretation
content:
application/json:
schema:
type: object
properties:
number:
type: number
example: 7
description: 'Expression number (also called Destiny number) derived from all letters in the full birth name. Reveals natural talents, abilities, and the goals you are meant to achieve. Values: 1 to 9, 11, 22, or 33.'
calculation:
type: string
example: 1+6+8+5 + 5+9+3+3+9+1+4 + 1+4+9+2+8 = 78 → 7+8 = 15 → 1+5 = 6
description: Full Pythagorean letter-to-number conversion showing every letter value in the birth name, grouped by word, then summed and reduced to the final Expression number.
type:
type: string
enum:
- single
- master
example: single
description: Single-digit (1 to 9) or Master Number (11, 22, 33). Master Numbers in the Expression position indicate extraordinary innate talent that demands conscious development.
hasKarmicDebt:
type: boolean
example: false
description: Whether a Karmic Debt number (13, 14, 16, 19) appeared during the name reduction. Indicates inherited challenges embedded in your given name.
karmicDebtNumber:
type: number
example: 14
description: Specific Karmic Debt number found during reduction. Each debt (13, 14, 16, 19) points to a distinct lesson woven into the talents your name bestows.
karmicDebtMeaning:
type: object
properties:
description:
type: string
example: Karmic Debt of Abuse of Freedom
description: Title describing the karmic debt theme. Identifies the core past-life pattern that this debt number carries forward.
challenge:
type: string
example: Past life misuse of personal freedom, possibly through excess or manipulation.
description: The specific challenge or pattern from past lives that must be confronted. Explains the root cause of recurring obstacles.
resolution:
type: string
example: Learn balance, moderation, and responsible use of freedom.
description: Practical guidance for resolving the karmic debt. Actionable steps for transforming the inherited challenge into growth.
required:
- description
- challenge
- resolution
description: Detailed interpretation of the Karmic Debt number when present. Includes the debt theme, the inherited challenge, and guidance for resolution. Only returned when hasKarmicDebt is true.
meaning:
type: object
properties:
title:
type: string
example: The Seeker
description: Numerology archetype for this Expression number. Captures the essence of your natural abilities, such as "The Communicator" for 3 or "The Master Intuitive" for 11.
keywords:
type: array
items:
type: string
example:
- analytical
- spiritual
- wise
- introspective
- perfectionist
description: Defining traits and talent themes for this Expression number. Ideal for personality profiles, compatibility engines, and talent-matching features.
description:
type: string
example: People with a 7 Expression number have a natural gift for analysis and investigation...
description: Expert-written 300 to 500 word interpretation of the natural abilities, life mission, and destiny encoded in your birth name. Covers how these talents manifest across life stages.
strengths:
type: array
items:
type: string
example:
- Deep thinking
- Intuition
- Research ability
- Spiritual insight
description: Natural talents and innate gifts. Each strength includes a detailed explanation of how it shows up in work, relationships, and personal growth.
challenges:
type: array
items:
type: string
example:
- Aloofness
- Over-analysis
- Skepticism
description: Shadow side of your talents and areas requiring conscious effort. Each challenge explains its root cause and practical strategies for transformation.
career:
type: string
example: Life Path 7 excels in careers that reward deep thinking, research, and intellectual exploration...
description: Professional guidance aligned with your natural Expression talents. Covers ideal industries, specific roles, and the work environments where you will thrive.
relationships:
type: string
example: Life Path 7 individuals are introspective, thoughtful partners who seek deep connections...
description: How your Expression number shapes love, friendship, and family bonds. Includes compatibility insights with other numbers and communication patterns.
spirituality:
type: string
example: Seven is on a great quest for truth and meaning, the most spiritual of all numbers...
description: The spiritual dimension of your Expression energy. Explores soul lessons, recommended practices, and the deeper purpose your talents are meant to serve.
required:
- title
- keywords
- description
- strengths
- challenges
- career
- relationships
- spirituality
required:
- number
- calculation
- type
- hasKarmicDebt
- meaning
'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
/numerology/bridge:
post:
operationId: calculateBridgeNumbers
tags:
- Numerology
summary: Calculate Bridge Numbers - Harmonize different aspects of personality
description: 'Calculate three Bridge Numbers that reveal the adjustments needed to create harmony between different aspects of your numerology profile. Bridge Numbers are the absolute difference between pairs of core numbers: Life Path and Expression, Expression and Personality, Expression and Soul Urge. A Bridge of 0 means the two aspects are already aligned. Higher bridges (1 to 8) indicate greater tension and provide specific guidance on what changes to make. Bridge Numbers are essential for personal development, coaching applications, self-improvement platforms, and AI-powered personality analysis tools. Requires both a full birth name and birth date to calculate all four core numbers (Life Path, Expression, Soul Urge, Personality) internally before deriving the bridges.'
security:
- apiKey: []
parameters:
- 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
requestBody:
content:
application/json:
schema:
type: object
properties:
fullName:
type: string
minLength: 1
maxLength: 200
example: John William Smith
description: Full legal birth name as it appears on the birth certificate. Used to calculate Expression, Soul Urge, and Personality numbers. Include first, middle, and last names separated by spaces.
year:
type: integer
minimum: 100
maximum: 2100
example: 1990
description: Birth year between 100 and 2100. Used to calculate the Life Path number via Pythagorean reduction.
month:
type: integer
minimum: 1
maximum: 12
example: 7
description: Birth month (1 to 12)
day:
type: integer
minimum: 1
maximum: 31
# --- truncated at 32 KB (333 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/roxyapi/refs/heads/main/openapi/roxyapi-numerology-api-openapi.yml