# Kabbalah API, what to build and how to call it

> Ship a gematria calculator that shows the Hebrew it scored, a Tree of Life explorer, a Hebrew birthday reminder, or a name meaning feature, in under 30 minutes. No Hebrew required.

Gematria reads a Hebrew word as a number, because every Hebrew letter carries a value. Latin names are where every calculator quietly breaks: there is no standard for writing a Latin name in Hebrew, so two sites give two numbers and neither says why. This domain is 12 endpoints that take the disagreement as an input instead. `POST /kabbalah/gematria` returns EVERY Hebrew spelling the published letter map produces, each with its own values and its own per letter breakdown, names the one it chose, and states the rule that chose it. Every cipher, table and attribution carries its tradition and its century, so a Renaissance Christian cipher is never served as rabbinic practice.

## What you can build

- Gematria calculators that show their working: the Hebrew, the candidate spellings, the per letter values and the equal value words with citations
- Name meaning features for a numerology or astrology app, in the Hebrew reading rather than the Pythagorean one
- Hebrew birthday reminders and Jewish life event tools, with the sunset boundary as an explicit flag
- Birth angel pages over the Renaissance tradition of three names per birth, each dated by a stated method
- Tree of Life explorers where every path carries its letter and the tarot trump on it, cross linked to the Tarot API on the same key
- Hebrew alphabet reference libraries under four attribution readings, for explainer and study content
- Omer counters for the forty nine day period, with the sephirot pairing and the printed Hebrew label
- Name compatibility widgets whose score publishes every component that built it

## Prerequisites

1. A RoxyAPI key from [/account](/account).
2. Nothing else for the gematria, tree, letters, names, compatibility and daily routes. They take a string, an id or a date.
3. For the birth profile only: a `date`, a `time` and a `timezone`. No latitude and no longitude anywhere in this domain, because nothing here needs a place: the Sun position is geocentric, the calendar is arithmetic and the sunset boundary is a flag you set.
4. If you want to score a specific Hebrew spelling rather than let the map choose, send `textHebrew` instead of `text`.

## Install


### npm
```bash
npm install @roxyapi/sdk
```

### Python
```bash
pip install roxy-sdk
```

### PHP
```bash
composer require roxyapi/sdk
```

### .NET CLI
```bash
dotnet add package RoxyApi.Sdk
```

### Go
```bash
go get github.com/RoxyAPI/sdk-go
```

## Call the endpoint

The #1 Kabbalah call is gematria. One POST turns a name into its Hebrew spellings and their numbers. Verified operationId: `calculateGematria`.


### curl
```bash
curl -X POST https://roxyapi.com/api/v2/kabbalah/gematria \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Ruth", "ciphers": ["mispar-hechrachi", "mispar-gadol", "mispar-katan"] }'
```

### TypeScript SDK
```typescript
import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data: gematria } = await roxy.kabbalah.calculateGematria({
  body: { text: 'Ruth', ciphers: ['mispar-hechrachi', 'mispar-gadol', 'mispar-katan'] },
});

console.log(gematria.chosen.hebrew);          // "רות"
console.log(gematria.values[0].value);        // 606
console.log(gematria.hebrewForms.length);     // 2
console.log(gematria.hebrewForms[1].hebrew);  // "רוטה"
console.log(gematria.transformations[0].id);  // "atbash"
console.log(gematria.conventions.misparGadol); // "finals-500-900"
```

### Python SDK
```python
import os
from roxy_sdk import create_roxy

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

gematria = roxy.kabbalah.calculate_gematria(
    text='Ruth', ciphers=['mispar-hechrachi', 'mispar-gadol', 'mispar-katan'],
)
print(gematria['chosen']['hebrew'], gematria['values'][0]['value'])
for form in gematria['hebrewForms']:
    print(form['hebrew'], form['romanization'], form['rule'])
```

### PHP SDK
```php
<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$gematria = $roxy->kabbalah->calculateGematria(
    text: 'Ruth',
    ciphers: ['mispar-hechrachi', 'mispar-gadol', 'mispar-katan'],
);
echo $gematria['chosen']['hebrew'], ' ', $gematria['values'][0]['value'];
```

### C# SDK
```csharp
using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var gematria = await roxy.Kabbalah.Gematria.PostAsync(new()
{
    Text = "Ruth",
    Ciphers = new() { "mispar-hechrachi", "mispar-gadol", "mispar-katan" },
});

Console.WriteLine(gematria!.Chosen!.Hebrew);   // "רות"
Console.WriteLine(gematria.Values![0].Value);  // 606
```

### Go SDK
```go
import (
    "context"
    roxyapi "github.com/RoxyAPI/sdk-go"
)

roxy, _ := roxyapi.NewRoxy("YOUR_API_KEY")

body := roxyapi.CalculateGematriaJSONRequestBody{
    Text:    roxyapi.Ptr("Ruth"),
    Ciphers: &[]string{"mispar-hechrachi", "mispar-gadol", "mispar-katan"},
}

gematria, _ := roxy.Kabbalah.CalculateGematria(context.Background(), nil, body)
```

### MCP
```bash
claude mcp add-json --scope user roxy-kabbalah '{"type":"http","url":"https://roxyapi.com/mcp/kabbalah","headers":{"X-API-Key":"YOUR_KEY"}}'
```

Then in any MCP client: "what is the gematria of the name Ruth, and which Hebrew spelling did you score?" The agent calls the gematria tool and reads the chosen spelling, the rule that chose it and the alternatives it rejected. Full setup for Cursor, Claude Desktop, Antigravity, and other clients: [MCP guide](/docs/mcp).

## Read the response

```json
{
  "input": { "text": "Ruth" },
  "hebrewForms": [
    {
      "hebrew": "רות",
      "romanization": "RVTh",
      "rule": "Longest match first: every two letter group the table prints is read as one Hebrew letter before the single letters are tried.",
      "values": [{ "id": "mispar-hechrachi", "value": 606, "tradition": "rabbinic", "source": "..." }],
      "letters": [
        { "glyph": "ר", "letterId": "resh", "name": "Resh", "isFinal": false, "value": 200 },
        { "glyph": "ו", "letterId": "vav", "name": "Vau", "isFinal": false, "value": 6 },
        { "glyph": "ת", "letterId": "tav", "name": "Tau", "isFinal": false, "value": 400 }
      ]
    },
    {
      "hebrew": "רוטה",
      "romanization": "RVTH",
      "rule": "An alternative parse: at least one two letter group is read as two separate Hebrew letters instead of one.",
      "values": [{ "id": "mispar-hechrachi", "value": 220, "tradition": "rabbinic", "source": "..." }],
      "letters": []
    }
  ],
  "chosen": {
    "hebrew": "רות",
    "rule": "Longest match first: every two letter group the table prints is read as one Hebrew letter before the single letters are tried."
  },
  "values": [
    { "id": "mispar-hechrachi", "value": 606, "tradition": "rabbinic", "source": "..." },
    { "id": "mispar-gadol", "value": 606, "tradition": "rabbinic", "source": "..." },
    { "id": "mispar-katan", "value": 12, "tradition": "rabbinic", "source": "..." }
  ],
  "transformations": [
    { "id": "atbash", "output": "גפא", "outputRomanization": "GPA", "value": 84, "tradition": "rabbinic", "source": "..." },
    { "id": "albam", "output": "טפך", "outputRomanization": "TPK", "value": 109, "tradition": "rabbinic", "source": "..." }
  ],
  "matches": [],
  "conventions": {
    "transliteration": "letter-map-mathers",
    "misparGadol": "finals-500-900",
    "atbashOutput": "both"
  }
}
```

Two arrays above are abridged so the shape reads in one screen: each `letters` list is shown in full only on the first form, and every `values` list is shown with one entry where the live call returns eleven. Nothing else is trimmed.

| Field | What it is |
|---|---|
| `input` | Whichever of `text` or `textHebrew` you sent, echoed |
| `hebrewForms` | Every candidate Hebrew spelling of a Latin input, each with its own `values`, `letters` and the `rule` that produced it. One entry when you sent `textHebrew` |
| `chosen` | The spelling the numbers at the top of the response were computed from, plus the rule that selected it. Always the first entry of `hebrewForms` |
| `values` | The cipher values of the chosen spelling. `id` is a canonical identifier, `value` is the number, `alternateValues` appears where a cipher is genuinely multi valued, `value` is `null` for a catalogued but uncomputed cipher |
| `letters` | The per letter breakdown, glyph by glyph, so a UI can show why the total is what it is. `isFinal` marks a word final form |
| `transformations` | AtBash and Albam: the substituted Hebrew string, its romanization and its standard value |
| `latinValues` | Present only when you sent `latinCiphers: true` with a Latin `text`. Three Latin alphabet ciphers, each with its `lineage` sentence |
| `matches` | Curated equal value entries for the chosen spelling, each with a meaning, a note and at least two `sources`. Empty when nothing in the lexicon shares the value |
| `conventions` | Every switch this result was computed with, echoed so it can be reproduced |

Branch on `id`, `tradition` and `conventions`, which never translate. Render `meaning`, `note`, `rule` and `reading`, which do.

## The `hebrewForms[]` array is the point

A Latin name has no single Hebrew spelling, and the ambiguity is in the letter map itself. Under the published table `th` is either tav, one letter, or tet followed by he, two letters. `tz` is either tzadi or tet followed by zayin. A name with several such junctions has several legitimate readings, and they give different numbers: Ruth is 606 as רות and 220 as רוטה.

So the response never hides the choice. Every parse the map allows comes back as its own entry:

```typescript
type HebrewForm = {
  hebrew: string;   // the spelling
  romanization: string;
  rule: string;     // why this parse exists
  values: { id: string; value: number | null; alternateValues?: number[] }[];
  letters: { glyph: string; letterId: string; name: string; isFinal: boolean; value: number }[];
};
```

The greedy longest match is always `hebrewForms[0]` and is always `chosen`, so a caller that only wants one number reads `values` and ignores the rest. A caller that wants to be honest with a user renders the alternatives beside it. Sending `textHebrew` skips transliteration entirely, returns exactly one form, and drops `transliteration` from `conventions`, because no scheme was applied:

```bash
curl -X POST https://roxyapi.com/api/v2/kabbalah/gematria \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"textHebrew":"שלום"}'
# => chosen.hebrew "שלום", values mispar-hechrachi 376, mispar-gadol 936,
#    matches[0] { id: "esav", value: 376, sources: [...] }
```

Vowel points and cantillation marks are stripped before scoring, so a pointed and an unpointed spelling of one word give the same number.

## Ship the rest

### The birth profile

[`POST /kabbalah/birth-profile`](/api-reference#tag/kabbalah/POST/kabbalah/birth-profile) (`generateBirthProfile`) is the Hebrew date, the Hebrew birthday, the three birth names and the birth sephirah in one call.

```bash
curl -X POST https://roxyapi.com/api/v2/kabbalah/birth-profile \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"date":"1990-06-15","time":"14:30","timezone":"America/New_York"}'
# => hebrewDate { year: 5750, month: "Sivan", day: 22, hebrew: "כ״ב בסיוון תש״נ", afterSunset: false },
#    hebrewBirthday { date: "1991-06-04", hebrewYear: 5751 },
#    angels[0] { role: "body", number: 17, traditionalName: "Loviah", choir: "Thrones" },
#    sephirah { id: "tiferet", number: 6, english: "Beauty" }
```

`angels` is always three entries with the roles `body`, `character` and `spirit`. The first two are read from the day of birth by two different cycles and the third from the twenty minute interval of the hour, so the third is the one a loosely recorded birth time moves. Each carries a `window` sentence naming the arc or the clock interval it governs, so a UI can show what the answer depends on.

`time` defaults to noon when omitted, and the response says so rather than implying precision it does not have. `hebrewBirthday` is `null` with a note where the Hebrew month and day do not exist in the target year, because which day the anniversary moves to is community practice and no single source can type it as a convention.

**Tip: This is a Hebrew birthday, not a Hebrew calendar**
There are no holidays, no candle times and no Torah readings in this domain, on purpose. A free and well maintained converter already covers that ground, so what ships here is the one field a birth profile needs.

### The name profile

[`POST /kabbalah/name-profile`](/api-reference#tag/kabbalah/POST/kabbalah/name-profile) (`generateNameProfile`) is the same transliteration engine narrowed to the four readings a name feature actually renders, plus the sephirah the reduced value points at.

```bash
curl -X POST https://roxyapi.com/api/v2/kabbalah/name-profile \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"David"}'
# => chosen { hebrew: "דאויד", romanization: "DAVID" },
#    values { standard: 25, large: 25, small: 16, preceding: 97 },
#    letters 5 entries, sephirah { id: "netzach", reduced: 7, english: "Victory" }
```

`values` here is an OBJECT with four named readings, not the array `POST /gematria` returns. Use this route for a name card and the gematria route when a reader wants every cipher. `sephirah.reading` states plainly that reducing a value to a single digit is a numerical convention rather than a classical rule, which is the sentence to keep if you print it.

### The 72 names

[`GET /kabbalah/names`](/api-reference#tag/kabbalah/GET/kabbalah/names) (`listShemNames`) is the paginated list, and it doubles as a lookup: pass `longitude` and it returns the single name governing that arc of the ecliptic.

```bash
curl "https://roxyapi.com/api/v2/kabbalah/names?longitude=127.5" -H "X-API-Key: $ROXY_API_KEY"
# => total 1, longitude 127.5,
#    names[0] { number: 26, name: "האאיה", traditionalName: "Haaiah",
#               arcStart: 125, arcEnd: 130, sign: "leo", degreeInSign: 5, choir: "Dominions" }
```

[`GET /kabbalah/names/{number}`](/api-reference#tag/kabbalah/GET/kabbalah/names/{number}) (`getShemName`) is one row by index 1 to 72. The index is the identifier here rather than the name, because the Latin spellings differ between published tables while the index never does.

Three fields are worth knowing. `letters` is the triplet with any word final form written as its base letter, the way every published list prints it, and `lettersAsWritten` is the same triplet exactly as it stands in the verses, which is what makes the reading auditable. `publishedDisagreement` appears on the one row where a second published list prints different letters, carrying what that list prints instead of silently correcting it.

### The Tree of Life

[`GET /kabbalah/tree`](/api-reference#tag/kabbalah/GET/kabbalah/tree) (`getTreeOfLife`) is the whole diagram in one call: eleven `sephirot` rows, the 22 `paths`, the four `worlds` and the ten step `lightningFlash` order.

```bash
curl "https://roxyapi.com/api/v2/kabbalah/tree" -H "X-API-Key: $ROXY_API_KEY"
# => sephirot[0] { id: "keter", number: 1, pillar: "middle", world: "Atziluth" },
#    paths[0] { path: 11, letter: "alef", letterGlyph: "א",
#               from: "keter", to: "chokhmah",
#               trump: { id: "fool", number: "0", name: "The Fool" },
#               attribution: { kind: "element", value: "air" } },
#    worlds[0] { id: "atziluth", sephirot: ["keter"], sephirotAlternate: ["chokhmah"] },
#    lightningFlash ["keter", "chokhmah", ..., "malkuth"]
```

`sephirot` has eleven entries because Daat is included, and Daat carries `number: null` and touches no path. Filter on `number` when you are drawing the ten. Every path carries the tarot trump on it with the same `id` the [Tarot API](/docs/guides/tarot) uses, so a path row links straight to a card on the same key. `attribution.kind` is one of `element`, `planet` or `sign`, and it changes with `letterAttribution`, which is the most contested column in the domain.

Each world carries BOTH readings of which sephirot belong to it. They agree exactly on Formation and Action and differ at the top, so `sephirot` and `sephirotAlternate` are published side by side rather than one being chosen.

[`GET /kabbalah/sephirot/{id}`](/api-reference#tag/kabbalah/GET/kabbalah/sephirot/{id}) (`getSephirah`) is one sphere with the paths that touch it. Ids are the ten plus `daat`.

```bash
curl "https://roxyapi.com/api/v2/kabbalah/sephirot/tiferet" -H "X-API-Key: $ROXY_API_KEY"
# => number 6, pillar "middle", pillarName "Pillar of Equilibrium", world "Yetzirah",
#    attribution "Shemesh, the solar light, the Sun", paths 8 entries
```

### The 22 letters

[`GET /kabbalah/letters`](/api-reference#tag/kabbalah/GET/kabbalah/letters) (`listHebrewLetters`) is the full alphabet with `total`, a `classCounts` object and the `letterAttribution` in force. There is no pagination: 22 rows is the whole table.

```bash
curl "https://roxyapi.com/api/v2/kabbalah/letters?letterAttribution=golden-dawn" \
  -H "X-API-Key: $ROXY_API_KEY"
# => total 22, classCounts { mother: 3, double: 7, simple: 12 },
#    letters[0] { id: "alef", letter: "א", value: 1, letterClass: "mother",
#                 attribution: { kind: "element", value: "air" },
#                 trump: { id: "fool", name: "The Fool" }, path: 11 }
```

[`GET /kabbalah/letters/{id}`](/api-reference#tag/kabbalah/GET/kabbalah/letters/{id}) (`getHebrewLetter`) is one letter in full: `final` and `finalValue` for the five that take a word final form, `letterClass` and its `classReading`, the attribution, the trump and the path number.

### Name compatibility

[`POST /kabbalah/compatibility`](/api-reference#tag/kabbalah/POST/kabbalah/compatibility) (`calculateNameCompatibility`) takes two names and publishes every component of the score.

```bash
curl -X POST https://roxyapi.com/api/v2/kabbalah/compatibility \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"firstName":"David","secondName":"Sarah"}'
# => first { standard: 25, reduced: 7, sephirah: "netzach" },
#    second { standard: 267, reduced: 6, sephirah: "tiferet" },
#    sharedValues [], score 4, band "low",
#    components[3] { id: "sharedLetters", points: 4, maximum: 30, matched: true }
```

`score` is a RoxyAPI composite, not a classical measure, and `components` is the reason it is safe to render: four weighted parts, each with its own `points`, `maximum` and `matched` flag, so a UI can show the working. `reading` says in plain words that nothing in the tradition reads a low number as an obstacle. Send `firstNameHebrew` and `secondNameHebrew` to score exact spellings instead.

### The daily Omer count

[`GET /kabbalah/daily`](/api-reference#tag/kabbalah/GET/kabbalah/daily) (`getDailySephirah`) is the Omer day and its sephirot pairing.

```bash
curl "https://roxyapi.com/api/v2/kabbalah/daily?date=2026-04-10" -H "X-API-Key: $ROXY_API_KEY"
# => inOmer true, day 8, week 2, dayInWeek 1,
#    weekSephirah { id: "gevurah", english: "Severity" },
#    daySephirah { id: "chesed", english: "Mercy" },
#    hebrewLabel "חסד שבגבורה", hebrewDate "Nisan 23"
```

The count runs forty nine days and is not running the rest of the year, so most dates return `inOmer: false` with a `nextStart` date and no invented reading. Branch on `inOmer` before rendering anything. `hebrewLabel` reads the day first and the week second, which is the order the traditional label uses.

### The cipher catalogue

[`GET /kabbalah/ciphers`](/api-reference#tag/kabbalah/GET/kabbalah/ciphers) (`listGematriaCiphers`) is the provenance surface: `total` 16 across `ciphers`, `latinCiphers` and `transformations`, each row carrying a `definition`, a `tradition`, a `century`, a `computed` flag and its `sources`.

| Identifier | Name | Tradition | Century | Computed |
|---|---|---|---|---|
| `mispar-hechrachi` | Mispar hechrachi, absolute value | rabbinic | Second century onward | yes |
| `mispar-gadol` | Mispar gadol, large value | rabbinic | Second century onward | yes |
| `otiyot-be-milui` | Otiyot be-milui, filled letters | rabbinic | Second century onward | yes |
| `mispar-katan` | Mispar katan, small value | rabbinic | Second century onward | yes |
| `mispar-kidmi` | Mispar kidmi, preceding value | rabbinic | Second century onward | yes |
| `mispar-prati` | Mispar prati, squared value | rabbinic | Second century onward | yes |
| `mispar-ha-merubah-ha-klali` | Mispar ha-merubah ha-klali | rabbinic | Second century onward | yes |
| `mispar-meshulash` | Mispar meshulash, cubed value | rabbinic | Second century onward | yes |
| `mispar-musafi` | Mispar musafi | rabbinic | Second century onward | yes |
| `kolel` | Kolel | rabbinic | Second century onward | yes |
| `mispar-mispari` | Mispar mispari | rabbinic | Second century onward | no |
| `atbash` | AtBash | rabbinic | Biblical | yes |
| `albam` | Albam | rabbinic | Second century onward | yes |
| `simple-ordinal` | Simple ordinal | renaissance-latin | Sixteenth century | yes |
| `latin-mispar` | Latin mispar | renaissance-latin | Sixteenth century | yes |
| `ordinal-times-six` | Ordinal times six | modern | Modern | yes |

Eleven rows in `ciphers` are rabbinic and ten of them return a value. `mispar-mispari` is the exception: it needs a table of Hebrew number words no source consulted carries, and its own published worked example yields two answers, so it returns `value: null` with `computed: false`. That is provenance, not a gap.

The three Latin ciphers are scored only when you send `latinCiphers: true` with a Latin `text`, and each returns a `lineage` sentence naming the authors it is traced through. Two of them are Renaissance Christian and one is modern. None of them is a Jewish cipher, whatever a consumer calculator prints beside it.

## The conventions are typed, defaulted and echoed

Kabbalah is not one tradition. Where two schools disagree, this API takes the disagreement as an input instead of choosing silently. Every switch is optional, has a named default, and comes back in `conventions` on the response, so a reading stored today can be reproduced years from now without knowing what the defaults were on the day it was made.

| Convention | Values | Default | Routes | Tradition and century | What it changes |
|---|---|---|---|---|---|
| `transliteration` | `letter-map-mathers` | `letter-map-mathers` | gematria, name profile, compatibility | Hermetic, 1887 | How a Latin name is written in Hebrew before it is scored. One member, because it is the only deterministic Latin to Hebrew scheme with a published table. Phonetic schemes are not offered: no two references agree on a rule for that direction, and every published Hebrew standard romanizes the other way |
| `misparGadol` | `finals-500-900`, `milui` | `finals-500-900` | gematria, name profile, compatibility | rabbinic, second century onward | Which published method the name large value means. One scores the five word final forms as 500 to 900, the other spells each letter out in full. They are different numbers under one name, so the request says which |
| `atbashOutput` | `both`, `string`, `value` | `both` | gematria | rabbinic, biblical | Whether AtBash and Albam return the substituted Hebrew string, its standard value, or both. The biblical witness for AtBash is a substituted WORD rather than a number |
| `letterAttribution` | `sefer-yetzirah-gra`, `sefer-yetzirah-short`, `sefer-yetzirah-saadia`, `golden-dawn` | `sefer-yetzirah-gra` | tree, sephirot, letters | rabbinic, tenth century onward, plus Hermetic nineteenth century | Which reading gives each letter its element, planet or sign. The seven double letters are the most contested column in the domain and the four readings genuinely differ |
| `treeVariant` | `kircher` | `kircher` | tree | Hermetic, 1652 | Which arrangement of the 22 paths is drawn. One member, because no published source letters the 22 paths of the other arrangement: the diagram it is traced to had seventeen paths and no letters at all |
| `sephirotSystem` | `classical`, `golden-dawn` | `classical` | tree, sephirot | rabbinic medieval, plus Hermetic nineteenth century | Which reading gives each sephirah its sphere. Measured as agreeing on all ten rows. The parameter exists so a caller knows which produced the answer rather than assuming |
| `angelDating` | `solar-longitude`, `lenain-blocks` | `solar-longitude` | birth profile | Hermetic, 1823 wheel | How the name of the day is found. The exact five degree arc the Sun stood in, or the fixed civil wheel of five day periods. The Sun does not move at a constant rate, so the two drift apart by up to about three days by early August |
| `yearStart` | `march-21`, `march-20` | `march-21` | birth profile | Hermetic, 1823 wheel | Which date the civil wheel opens on. Both are conventions rather than facts, and the equinox itself fell on 20 March in 2026. Ignored under `solar-longitude` |
| `leapDayPolicy` | `extend-previous`, `next-angel` | `extend-previous` | birth profile | Hermetic, 1823 wheel | Where 29 February falls. The wheel was built for a 365 day year and has no slot for it, so published tables differ. Ignored under `solar-longitude` |
| `afterSunset` | `true`, `false` | `false` | birth profile, daily | rabbinic, biblical | Whether the birth fell after nightfall, which starts the next Hebrew day. A caller assertion, because sunset needs a place this API deliberately does not take |

Three of these are worth a control in your own UI. **`transliteration` is why two calculators disagree**, so echoing `conventions.transliteration` beside a number is what turns an argument into a comparison. **`misparGadol` names two different methods**, so a product that prints a large value without saying which is printing an ambiguous number. **`afterSunset` is an input and never an assumption**: the Hebrew day begins at nightfall, so a birth at 21:00 belongs to the next Hebrew date and only the caller knows whether the Sun had set where they were.

## Reply in the user language

Every route accepts `?lang=`. This domain ships German, Spanish, French, Hindi, Portuguese, Russian and Turkish alongside the English source.

```bash
curl -X POST "https://roxyapi.com/api/v2/kabbalah/gematria?lang=de" \
  -H "X-API-Key: $ROXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"textHebrew":"שלום"}'
```

Machine readable identifiers never translate. Cipher `id` stays `mispar-hechrachi`, `tradition` stays `rabbinic`, sephirah `id` stays `tiferet`, letter `id` stays `alef`, `band` stays `low`, and every value in `conventions` stays canonical English. Hebrew data is Hebrew in every language: `hebrew`, `letter`, `name` on a shem row, `hebrewLabel`. Composed prose does translate in place: `meaning`, `note`, `reading`, `rule`, `classReading`, `window` and `definition`. Branch on the identifier, render the prose.

## Gotchas

- **Five Latin letters have no Hebrew in the published map.** `c`, `e`, `f`, `w` and `x` are unmapped, so a name containing one returns 400 naming the letters it could not write rather than dropping them and returning a number that is quietly wrong. `Felix` fails on `f`, `e` and `x`. The fix is to send `textHebrew` with the spelling you want, or to score the Latin string with `latinCiphers: true`.
- **Send `text` or `textHebrew`, never both.** Sending both returns 400, because which one you send decides whether a transliteration step runs at all. Sending neither returns 400 as well.
- **`chosen` is a choice, not a fact.** It is always the greedy longest match, and the other parses in `hebrewForms` are equally legal readings of the same map. A UI that renders only `values` is correct and a UI that renders the alternatives is honest.
- **`ciphers` filters the top level `values` only.** Every entry in `hebrewForms` keeps its full cipher set, so the candidate spellings stay comparable to each other. Read `values` when you want the filtered view.
- **A cipher can be multi valued.** `otiyot-be-milui` spells each letter out, and he and vav each have three accepted spellings, so `alternateValues` sits beside `value`. Render the array where you have room and the single value where you do not.
- **`value` can be `null`.** `mispar-mispari` is catalogued and not computed. Guard the field rather than assuming a number.
- **`sephirot` has eleven rows, not ten.** Daat is included with `number: null` and no path. Filter on `number` when drawing the tree.
- **The Omer is running for forty nine days a year.** `GET /kabbalah/daily` returns `inOmer: false` and a `nextStart` date the rest of the time. A UI that renders `daySephirah` unconditionally will render `undefined` for ten months.
- **The birth profile takes no place.** There is no latitude and no longitude, so [`GET /location/search`](/api-reference#tag/location-and-timezone/GET/location/search) is only ever needed for the `timezone` string.
- **The Golden Dawn attribution does NOT exchange He and Tzade.** That exchange belongs to a later author, and the books written from Golden Dawn material print He with Aries and Tzade with Aquarius. If your reference disagrees, check its date.
- **Every call bills at a flat 1 request.** REST and Remote MCP are identical, with no per-domain fees.

## Frequently asked questions


### How do I get the gematria of a name?
`POST /kabbalah/gematria` with `text` set to the name. The response returns every Hebrew spelling the published letter map produces, each with its own cipher values and per letter breakdown, plus `chosen` naming the spelling the headline numbers came from and the rule that selected it. Send `textHebrew` instead when you already know the spelling you want scored, and the transliteration step is skipped entirely.

### Why do two gematria calculators disagree on my name?
Almost always because they wrote it in Hebrew differently and said nothing about it. There is no standard for turning a Latin name into Hebrew, since the published Hebrew standards all romanize the other way. This API takes the scheme as a typed parameter, returns every candidate spelling rather than one, and echoes the convention on the response, so two answers can be compared instead of argued about.

### What does mispar gadol mean, and why is it a parameter?
Two published methods carry that name. One scores the five word final letters as 500 through 900; the other spells every letter out in full and adds the spellings. They give different numbers for the same word, so `misparGadol` says which one you meant and the response echoes it back. The default is the finals method.

### Which arrangement of the Tree of Life does the API use?
The 1652 arrangement, in which Malkuth carries three paths, which is the one the Hermetic orders used and the only one with a published table that letters every path. A one path Malkuth arrangement is in circulation, but the diagram it is traced to had seventeen paths and no letters at all, so there is no sourced table to serve. `treeVariant` is typed and echoed so this cannot change under a caller without notice.

### Is this Jewish Kabbalah or Hermetic Qabalah?
Both, and every row says which. The letter values, the ciphers, the substitution methods and the Omer count are rabbinic. The tarot trumps on the paths, the sephirot spheres, the transliteration map and the birth angel wheel are Renaissance and Victorian Hermetic. Each cipher and each table carries a tradition and the century of that tradition, so a product can present one, the other, or both without misattributing either.

### Does this compute the Hebrew calendar?
It computes a Hebrew birthday, not a calendar. The Hebrew date of a birth, the anniversary that follows it and the sunset boundary are fields inside the birth profile, worked out from the published calendar algorithm. There are no holidays, no candle times and no Torah readings, because a free and well maintained converter already covers that ground.

### How are the 72 names produced?
They are derived from three verses of Exodus read in the boustrophedon order, letter by letter, rather than copied from a table. The derivation reproduces a published list on all 72 rows; a second published list differs on one row, and that row carries `publishedDisagreement` with what the other list prints rather than a silent correction.

## Ready-made starter

There is no Kabbalah only template yet. The flagship [astrology-ai-chatbot](https://github.com/RoxyAPI/astrology-ai-chatbot) template connects every domain over Remote MCP by default, so cloning it gives you a working gematria and Tree of Life chatbot with no wiring; browse the catalog at [/starters](/starters). For a custom build, the [Next.js integration guide](/docs/integrations/nextjs) is the fastest path.

## What to build next

- The [tarot guide](/docs/guides/tarot) covers the deck the 22 paths are cross linked to. Every path carries the trump `id` the Tarot API serves, so one call each builds a path page with a card on it.
- The [numerology guide](/docs/guides/numerology) covers the Pythagorean and Chaldean readings of the same name, which is the natural second tab beside a Hebrew one.
- The [caching guide](/docs/guides/caching) covers the split this domain has: a gematria answer for a given string never changes, and neither does a tree, a letter or a name row, while the Omer daily tracks the date.
- The [AI chatbot tutorial](/docs/tutorials/ai-chatbot) shows tool registration so users can ask "what is the gematria of my name" in natural language.