Numerology Api

Numerology API

Numerology API

Life Path number from any birth date. Pythagorean reduction with automatic Master Number and Karmic Debt detection. One key covers 18+ spiritual domains. MCP-first, no local setup required.

Get API Key Try Live Master Numbers MCP Server SDK

What is Numerology API

The RoxyAPI numerology endpoint calculates the Life Path number, the single most important number in a numerology chart, from a birth date using Pythagorean reduction. It reduces month, day, and year independently, then automatically detects Master Numbers (11, 22, 33) and Karmic Debt numbers (13, 14, 16, 19) that surface during the reduction. Every response carries a step-by-step calculation string plus a 300 to 500 word interpretation covering personality, strengths, challenges, career, relationships, and spirituality. One RoxyAPI subscription covers 18+ spiritual domains, so the same numerology API key also reaches Western astrology, Vedic astrology, tarot, biorhythm, and more.

Why this API

Property	Value
Coverage	18+ spiritual domains in one subscription
Calculation	Pythagorean reduction with master and karmic detection
Numbers	Life Path, Expression, Soul Urge, Personality, Personal Year, Compatibility, and more
MCP server	https://roxyapi.com/mcp/numerology (Streamable HTTP, no local setup)
SDKs	TypeScript on npm @roxyapi/sdk, Python on PyPI roxy-sdk, PHP on Packagist roxyapi/sdk, C# on NuGet RoxyApi.Sdk, Go github.com/RoxyAPI/sdk-go, WordPress plugin roxyapi
Pricing	One key, flat per call, from $39/mo
Licensing	Personal and commercial use, including closed source apps. No AGPL or GPL entanglement. Full terms
Last verified	2026-Q3

Quick start

1. Get a key at roxyapi.com/pricing
2. Pick a language below
3. Copy the snippet, run, ship

cURL

curl -X POST https://roxyapi.com/api/v2/numerology/life-path \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":1990,"month":7,"day":15}'

Python

import os
from roxy_sdk import create_roxy

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

# Life Path number from a birth date. Master Numbers and Karmic Debt detected automatically.
result = roxy.numerology.calculate_life_path(year=1990, month=7, day=15)

print(result["number"])             # 5
print(result["type"])               # single | master
print(result["meaning"]["title"])   # The Adventurer
print(result["hasKarmicDebt"])      # True

JavaScript (Node)

import { createRoxy } from '@roxyapi/sdk';

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

// Life Path number, the most important number in Pythagorean numerology.
const { data, error } = await roxy.numerology.calculateLifePath({
  body: { year: 1990, month: 7, day: 15 },
});

if (error) throw new Error(error.error);

console.log('Life Path:', data.number, data.meaning.title);
console.log('Keywords:', data.meaning.keywords);
console.log('Karmic Debt:', data.hasKarmicDebt);

TypeScript

import { createRoxy } from '@roxyapi/sdk';

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

// Life Path number from a birth date. Returns the number, archetype, and full interpretation.
const { data, error } = await roxy.numerology.calculateLifePath({
  body: { year: 1990, month: 7, day: 15 },
});

if (error) throw new Error(error.error);

console.log('Number:', data.number);                 // 5
console.log('Type:', data.type);                      // single
console.log('Archetype:', data.meaning.title);        // The Adventurer
console.log('Karmic Debt number:', data.karmicDebtNumber);
console.log('Career guidance:', data.meaning.career);

Request schema

Field	Type	Required	Description
year	number	yes	Birth year between 100 and 2100. Supports historical figures like Einstein (1879) and Shakespeare (1564).
month	number	yes	Birth month (1-12).
day	number	yes	Birth day (1-31).

Response shape

{
  "number": 5,
  "calculation": "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",
  "type": "single",
  "hasKarmicDebt": true,
  "karmicDebtNumber": 14,
  "karmicDebtMeaning": {
    "description": "Karmic Debt of Abuse of Freedom",
    "challenge": "Past life misuse of personal freedom, possibly through excess or manipulation...",
    "resolution": "Learn balance, moderation, and responsible use of freedom..."
  },
  "meaning": {
    "title": "The Adventurer",
    "keywords": ["freedom", "adventure", "change", "versatility", "curiosity"],
    "description": "In the span of single-digit numbers 1-9, 5 is the number in the exact middle...",
    "strengths": ["Curious: ...", "Adaptable: ...", "Social: ..."],
    "challenges": ["Non-committal: ...", "Unreliable: ...", "Directionless: ..."],
    "career": "Life Path 5 thrives in careers that offer freedom, variety, and constant stimulation...",
    "relationships": "Life Path 5 individuals are exciting, charming, and freedom-loving partners...",
    "spirituality": "Five is the rebel, the traveler, the agent of change..."
  }
}

Field	Type	Description
number	number	The 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	string	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	string	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	boolean	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	number	The specific Karmic Debt number detected during reduction, if any. Each debt number represents a distinct past-life lesson requiring resolution.
karmicDebtMeaning	object	Detailed interpretation of the Karmic Debt number when present. Carries description, challenge, and resolution. Only returned when hasKarmicDebt is true.
meaning.title	string	Numerology archetype name for this Life Path number, such as "The Leader" for 1 or "The Master Builder" for 22.
meaning.keywords	array	Ten defining personality traits and energetic themes. Useful for quick personality snapshots, tag clouds, and compatibility matching.
meaning.description	string	In-depth 300 to 500 word interpretation covering personality, purpose, and life themes. Suitable for full-page readings and detailed reports.
meaning.strengths	array	Core strengths and positive qualities. Each entry names a trait followed by how it manifests in daily life.
meaning.challenges	array	Growth areas and shadow qualities. Each entry names the challenge and explains its root cause and how to work through it.
meaning.career	string	Tailored career guidance covering ideal industries, roles, and work environments, with specific job titles.
meaning.relationships	string	Love, friendship, and family dynamics, including romantic compatibility with other Life Path numbers.
meaning.spirituality	string	Spiritual path, soul lessons, and recommended practices for personal growth and inner alignment.

Common use cases

Use case	Endpoint flow
Life purpose discovery feature in a numerology app	POST /numerology/life-path with the user birth date, render the archetype and description
Birth chart calculator that reports Master Numbers	POST /numerology/life-path, branch on type to highlight 11, 22, 33
Karmic Debt insight screen in a personal development platform	POST /numerology/life-path, render karmicDebtMeaning when hasKarmicDebt is true
AI numerology chatbot answering "what is my life path number"	POST /numerology/life-path from an LLM tool call, format the meaning fields in the reply
Astrology service adding a numerology layer to its reports	POST /numerology/life-path alongside the natal chart call, one key covers both

Related endpoints in this domain

• POST /numerology/expression (calculateExpression) - Expression (Destiny) number from the full birth name, revealing natural talents and life goals
• POST /numerology/soul-urge (calculateSoulUrge) - Soul Urge (Heart Desire) number from the vowels in the birth name, revealing innermost desires and motivations
• POST /numerology/personal-year (calculatePersonalYear) - Personal Year number and annual forecast, the theme and opportunities for the current year

Use this in your AI agent

Connect Claude, GPT, Gemini, or Cursor to RoxyAPI through the remote MCP server. No Docker. No self hosting. The full MCP tool catalog for this domain is at https://roxyapi.com/mcp/numerology.

{
  "mcpServers": {
    "numerology": {
      "url": "https://roxyapi.com/mcp/numerology",
      "headers": { "X-API-Key": "$ROXY_API_KEY" }
    }
  }
}

See docs/mcp for Claude Desktop, Cursor, Windsurf, VS Code, and Claude Code setup.

For AI coding agents

This repo ships an AGENTS.md execution playbook. Cursor, Claude Code, Aider, Codex, Windsurf, RooCode, and Gemini CLI will pick it up automatically. Top level overview lives at roxyapi.com/AGENTS.md.

Resources

• Methodology and gold standard tests catalog-wide testing surface (Pythagorean reduction for numerology, JPL Horizons for the ephemeris-driven domains)
• Full API reference interactive Scalar UI
• TypeScript SDK on npm
• Python SDK on PyPI
• PHP SDK on Packagist
• C# SDK on NuGet
• Go SDK on pkg.go.dev
• WordPress plugin
• llms.txt full LLM citation index
• Top level AGENTS.md

Other RoxyAPI samples

KP Astrology API Kundli API Panchang API Natal Chart API Tarot API

License

MIT for this sample repo. See LICENSE.

Catalog licensing: Personal and commercial use, including closed source proprietary apps. No AGPL or GPL entanglement. RoxyAPI APIs and SDKs are safe to embed in commercial products. Full terms at roxyapi.com/policy/license.

Contact

• Site: roxyapi.com
• Status: roxyapi.com/api-reference