Skip to content

AGENTS.md

Latest commit

 

History

History
67 lines (55 loc) · 3.79 KB

AGENTS.md

File metadata and controls

67 lines (55 loc) · 3.79 KB

AGENTS.md for Numerology API

This repo teaches AI coding agents (Cursor, Claude Code, Aider, Codex, Windsurf, RooCode, Gemini CLI) how to use the RoxyAPI Life Path numerology endpoint.

Endpoint

  • Method: POST
  • URL: https://roxyapi.com/api/v2/numerology/life-path
  • Auth: X-API-Key header
  • Domain: numerology (one of 12 in the RoxyAPI catalog)
  • Operation ID: calculateLifePath matches the SDK method name in camelCase
  • MCP tool: post_numerology_life_path on https://roxyapi.com/mcp/numerology

TypeScript SDK

import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);
const { data, error } = await roxy.numerology.calculateLifePath({
  body: { year: 1990, month: 7, day: 15 },
});

Python SDK

import os
from roxy_sdk import create_roxy
roxy = create_roxy(os.environ["ROXY_API_KEY"])
result = roxy.numerology.calculate_life_path(year=1990, month=7, day=15)

Setup step (only when the endpoint requires coordinates)

Always call GET /location/search?q={city} first. Take latitude, longitude, timezone from cities[0] and pipe them in. Never ask the user to type coordinates.

Note: the numerology Life Path endpoint does NOT require coordinates. Pass year, month, day only. All three are required integers.

Request fields

  • year (number, required): birth year between 100 and 2100. Supports historical figures like Einstein (1879) and Shakespeare (1564).
  • month (number, required): birth month, 1 to 12.
  • day (number, required): birth day, 1 to 31. A day that does not exist for the given month and year is rejected with a 422.

Response top level keys

  • number: the Life Path number. 1 to 9 for single digits, or 11, 22, 33 for Master Numbers.
  • calculation: step-by-step Pythagorean reduction string showing month, day, and year reducing independently before combining.
  • type: single or master. Master Numbers are never reduced further.
  • hasKarmicDebt: boolean, true when a Karmic Debt number (13, 14, 16, 19) appeared during reduction.
  • karmicDebtNumber: the specific Karmic Debt number detected, present only when hasKarmicDebt is true.
  • karmicDebtMeaning: object with description, challenge, resolution. Present only when hasKarmicDebt is true.
  • meaning: object with title (archetype), keywords (array), description (300 to 500 words), strengths (array), challenges (array), career, relationships, spirituality.

Domain rules

  • This is Pythagorean numerology. Reduction is 3-cycle: month, day, and year reduce independently, then the three results sum and reduce to the final Life Path number.
  • Master Numbers (11, 22, 33) are never reduced to a single digit. Branch on type to surface them.
  • Karmic Debt (13, 14, 16, 19) is detected mid-reduction. Render karmicDebtMeaning only when hasKarmicDebt is true. Do not assume the keys exist otherwise.
  • The endpoint takes no coordinates and no name. Life Path is derived from the birth date alone.
  • For the Expression and Soul Urge numbers, use the name-based endpoints below. For an annual forecast, use Personal Year.

Related endpoints

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

Verified

2026-Q2 against https://roxyapi.com/api/v2/openapi.json. Re-fetch the spec for ground truth before changing this file.

Discovery