---
title: "Calculate explicit Pythagorean numerology arithmetic"
method: POST
path: "/api/astro/numerology"
tags: ["Calculations"]
---

# Calculate explicit Pythagorean numerology arithmetic

`POST /api/astro/numerology`

## Request

- Base URL: `https://api.cosmicephemeris.com`
- URL: `https://api.cosmicephemeris.com/api/astro/numerology`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Symbolic calculation-only numerology: component-wise birth-date reduction, optional ASCII-name sums and an explicitly requested calendar-year cycle. Includes reduction traces, exact master-number and Y conventions. No interpretation, scientifically validated prediction, personality assessment or advice. Name data is not persisted by this route; use only data you are authorized to process. Each admitted request reserves one standard monthly unit; failed or timed-out admitted attempts are not refunded. Not a durable-job operation.
Historical mode uses an explicit BCE/CE date object and UT1 conventions. Its response is the versioned historical envelope, not the modern UTC envelope. Read result for calculation fields and metadata for limits and uncertainty.

## Request body

- union
  - NumerologyRequest
    - `birth_date` string, date, required: Valid Gregorian YYYY-MM-DD local civil date, inclusive 1800-01-01 through 2200-12-31. Calendar validity and timezone conversion are checked by the server.
    - `name` string: ASCII letters with internal spaces, apostrophes and hyphens only; no line breaks. Caller supplies any transliteration. No inference from language or pronunciation.
    - `master_numbers` boolean: Preserve 11, 22 and 33 at every date-component, name-total and final reduction. False reduces every result to one digit. Personal-year cycles always reduce to one digit.
    - `y_vowel` boolean: Requires name, including when false. All Y letters are either vowels or consonants according to this explicit option.
    - `year` integer: Optional calendar-year cycle; never defaults to the server clock.
  - HistoricalNumerologyRequest: Explicit historical mode, 1000 BCE (BC)–2500 CE (AD). No year zero, implicit calendar, UTC or IANA zone. Preserve tool-specific mathematical, geographic and search limits; calendar/time conventions and estimated Delta-T are not certified historical accuracy.
    - `birth_date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
      - `year` integer, required
      - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
      - `month` integer, required
      - `day` integer, required
      - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
    - `name` string: ASCII letters with internal spaces, apostrophes and hyphens only; no line breaks. Caller supplies any transliteration. No inference from language or pronunciation.
    - `master_numbers` boolean: Preserve 11, 22 and 33 at every date-component, name-total and final reduction. False reduces every result to one digit. Personal-year cycles always reduce to one digit.
    - `y_vowel` boolean: Requires name, including when false. All Y letters are either vowels or consonants according to this explicit option.
    - `year` object: Personal year in the same explicitly selected convention; BCE year is at most 1000.
      - `year` integer, required
      - `era` 'BCE' | 'CE', required
    - `year_convention` 'displayed_year_digits' | 'astronomical_year_digits', required: Explicit symbolic choice: civil year digits or absolute astronomical-year digits (1 BCE is astronomical zero). Not a reconstructed ancient tradition.

## Response `200`

Deterministic symbolic number calculations and auditable arithmetic traces.

- union
  - NumerologyResponse
    - `type` 'numerology', required
    - `status` 'current', required
    - `method` 'pythagorean_component_sum_v1', required
    - `input` NumerologyRequest, required
      - `birth_date` string, date, required: Valid Gregorian YYYY-MM-DD local civil date, inclusive 1800-01-01 through 2200-12-31. Calendar validity and timezone conversion are checked by the server.
      - `name` string: ASCII letters with internal spaces, apostrophes and hyphens only; no line breaks. Caller supplies any transliteration. No inference from language or pronunciation.
      - `master_numbers` boolean: Preserve 11, 22 and 33 at every date-component, name-total and final reduction. False reduces every result to one digit. Personal-year cycles always reduce to one digit.
      - `y_vowel` boolean: Requires name, including when false. All Y letters are either vowels or consonants according to this explicit option.
      - `year` integer: Optional calendar-year cycle; never defaults to the server clock.
    - `date_components` object, required
      - `month` NumerologyReduction, required
        - `total` integer, required
        - `steps` integer[], required
        - `number` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 11 | 22 | 33, required
        - `master_number` boolean, required
      - `day` NumerologyReduction, required
        - `total` integer, required
        - `steps` integer[], required
        - `number` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 11 | 22 | 33, required
        - `master_number` boolean, required
      - `year` NumerologyReduction, required
        - `total` integer, required
        - `steps` integer[], required
        - `number` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 11 | 22 | 33, required
        - `master_number` boolean, required
    - `numbers` object, required
      - `life_path` NumerologyReduction, required
        - `total` integer, required
        - `steps` integer[], required
        - `number` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 11 | 22 | 33, required
        - `master_number` boolean, required
      - `birthday_root` NumerologyReduction, required
        - `total` integer, required
        - `steps` integer[], required
        - `number` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 11 | 22 | 33, required
        - `master_number` boolean, required
      - `expression` NumerologyReduction
        - `total` integer, required
        - `steps` integer[], required
        - `number` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 11 | 22 | 33, required
        - `master_number` boolean, required
      - `soul_urge` NumerologyReduction
        - `total` integer, required
        - `steps` integer[], required
        - `number` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 11 | 22 | 33, required
        - `master_number` boolean, required
      - `personality` NumerologyReduction
        - `total` integer, required
        - `steps` integer[], required
        - `number` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 11 | 22 | 33, required
        - `master_number` boolean, required
      - `personal_year` NumerologyReduction
        - `total` integer, required
        - `steps` integer[], required
        - `number` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 11 | 22 | 33, required
        - `master_number` boolean, required
    - `name_analysis` object
      - `normalized_name` string, required
      - `letters` object[], required
        - `letter` string, required
        - `value` integer, required
        - `vowel` boolean, required
    - `metadata` object, required
      - `interpretations` unknown, required
      - `predictions` unknown, required
      - `scientifically_validated` unknown, required
      - `practitioner_review` 'not_completed', required
  - HistoricalNumerologyNumerologyResponse
    - `schema` 'cosmicephemeris-historical-calculation-v1', required
    - `status` 'historical', required
    - `type` 'numerology', required
    - `input` HistoricalNumerologyRequest, required: Explicit historical mode, 1000 BCE (BC)–2500 CE (AD). No year zero, implicit calendar, UTC or IANA zone. Preserve tool-specific mathematical, geographic and search limits; calendar/time conventions and estimated Delta-T are not certified historical accuracy.
      - `birth_date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
        - `year` integer, required
        - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
        - `month` integer, required
        - `day` integer, required
        - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
      - `name` string: ASCII letters with internal spaces, apostrophes and hyphens only; no line breaks. Caller supplies any transliteration. No inference from language or pronunciation.
      - `master_numbers` boolean: Preserve 11, 22 and 33 at every date-component, name-total and final reduction. False reduces every result to one digit. Personal-year cycles always reduce to one digit.
      - `y_vowel` boolean: Requires name, including when false. All Y letters are either vowels or consonants according to this explicit option.
      - `year` object: Personal year in the same explicitly selected convention; BCE year is at most 1000.
        - `year` integer, required
        - `era` 'BCE' | 'CE', required
      - `year_convention` 'displayed_year_digits' | 'astronomical_year_digits', required: Explicit symbolic choice: civil year digits or absolute astronomical-year digits (1 BCE is astronomical zero). Not a reconstructed ancient tradition.
    - `result` object, required: Complete historical calculation adapter result. Times are explicit UT1 date records, never UTC strings; derived times may include fractional seconds and years outside the input range.
    - `metadata` object, required
      - `time_standard` 'not_applicable', required
      - `historical_accuracy_certified` unknown, required
      - `warnings` string[], required

## Other responses

- `400`: Invalid request, malformed JSON, out-of-range date/location, unknown model, invalid timezone or ambiguous/nonexistent clock-change time. Invalid attempts reaching quota reservation consume one unit.
- `401`: Missing, invalid, revoked API key or unavailable activated key owner. Dashboard cookies do not authenticate calculation routes.
- `403`: Origin not allowed by production CORS policy. Server-to-server requests can omit Origin.
- `404`: Wrong/case-variant/noncanonical or trailing-slash route; public paths have no version prefix.
- `413`: Request exceeds the body limit; gateway JSON is capped at 128 KiB. Edge failures may be HTML.
- `429`: Monthly quota exhausted, per-user two-request concurrency reached, or nginx rate/connection admission refused. Retry-After: 2 is sent for application per-user concurrency only, not a promise that monthly quota resets in two seconds.
- `500`: Bounded gateway/database/internal failure. An admitted attempt can still consume quota.
- `502`: Engine unavailable, unsuccessful internal server response or invalid upstream JSON. No engine internals are exposed.
- `503`: Four-request global calculation pool full (Retry-After: 2), maintenance or upstream service unavailable.
- `504`: Application engine timeout: 15 seconds normally; planetary events, house ingresses, aspect windows, event calendar, eclipse geometry, electional search, and event-rule search use 30 seconds; Nakshatra Timeline plus the explicitly enumerated readiness, robustness, location, uncertainty, and electional-audit family use 60 seconds. Timer includes response-body parsing; an admitted timeout consumes quota.

---

[API](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api.md) · [All operations](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/revisions/f041e924cea3?raw)