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.
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 install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

dotnet add package RoxyApi.Sdk

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 -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"] }'

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"

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

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'];

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

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)

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

Read the response

{
  "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.

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:

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:

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 (generateBirthProfile) is the Hebrew date, the Hebrew birthday, the three birth names and the birth sephirah in one call.

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.

The name profile

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.

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 (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.

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} (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 (getTreeOfLife) is the whole diagram in one call: eleven sephirot rows, the 22 paths, the four worlds and the ten step lightningFlash order.

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 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} (getSephirah) is one sphere with the paths that touch it. Ids are the ten plus daat.

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 (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.

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} (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 (calculateNameCompatibility) takes two names and publishes every component of the score.

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 (getDailySephirah) is the Omer day and its sephirot pairing.

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 (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.

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.

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.

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 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

Ready-made starter

There is no Kabbalah only template yet. The flagship 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. For a custom build, the Next.js integration guide is the fastest path.

What to build next

• The tarot guide 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 covers the Pythagorean and Chaldean readings of the same name, which is the natural second tab beside a Hebrew one.
• The caching guide 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 shows tool registration so users can ask "what is the gematria of my name" in natural language.