{"openapi":"3.1.0","info":{"title":"Kabbalah API","version":"2.0.0","description":"Kabbalah API for gematria, the 72 names, the Tree of Life and the Hebrew birthday, from one key. Score a Hebrew word or a Latin name across ten rabbinic ciphers with the per letter breakdown, every candidate Hebrew spelling shown and the rule that chose one, plus a cited equal value lexicon. The 72 names are derived from the verses rather than copied from a table, the birth name is dated by the exact position of the Sun or by the civil wheel as you choose, and the sephirot, the 22 paths and the 22 letters come back under typed school variants cross linked to the tarot deck. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs.\n\n# RoxyAPI: AI-Native Insight Infrastructure\n\n> **Base URL:** `https://roxyapi.com/api/v2`\n> All endpoint paths below are relative to this base URL.\n\nThe only multi-domain spiritual intelligence API. 18 domains (Astrology, Vedic Astrology, Forecast, Human Design, Chinese Astrology, Feng Shui, Mesoamerican Astrology, Vastu Shastra, Numerology, Kabbalah, Tarot Reading, Biorhythm, Ayurveda, I-Ching Oracle, Crystals and Healing Stones, Dream Interpretation, Angel Numbers, Location and Timezone), 258+ endpoints, one API key, instant activation. Remote MCP server per domain plus AGENTS.md for AI coding agents.\n\n## Who uses RoxyAPI\n\n- **Developers** building astrology apps, tarot platforms, numerology calculators, or dream journals\n- **AI agent builders** connecting Claude, GPT, or Gemini to real calculation engines via MCP\n- **Vibe coders** shipping insight apps with Cursor, Bolt, or Replit using zero domain knowledge\n- **Founders and brands** launching branded spiritual experiences for their audience\n\n## Quick start (60 seconds)\n\n**1. Get your API key** at [roxyapi.com/pricing](https://roxyapi.com/pricing). Instant delivery, no account required.\n\n**2. Make your first call:**\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" https://roxyapi.com/api/v2/tarot/draw -X POST -H \"Content-Type: application/json\" -d '{\"count\": 3}'\n```\n\n**3. Monitor usage:**\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" https://roxyapi.com/api/v2/usage\n```\n\n## AI agent integration (Remote MCP)\n\nRoxyAPI ships a Remote MCP server per product over Streamable HTTP, with no local setup and no Docker. Your AI agent auto-discovers all 258+ endpoints as callable tools with zero configuration:\n- **Claude Desktop, Cursor, Windsurf**: Add MCP server URL in settings\n- **OpenAI Agents, Gemini ADK**: Connect via Streamable HTTP transport\n- **Custom agents**: Use the MCP Python/TypeScript SDK\n\nMCP endpoints: `https://roxyapi.com/mcp/{domain}` (e.g., `/mcp/astrology`, `/mcp/tarot`)\n\nSetup guide: [roxyapi.com/docs/mcp](https://roxyapi.com/docs/mcp)\n\n## Authentication\n\nAll endpoints require an API key via header or query param:\n- **Header (recommended):** `X-API-Key: YOUR_KEY`\n- **Query param (testing):** `?api_key=YOUR_KEY`\n\n## Response format\n\nClean JSON, no wrapper objects. Errors return `{ \"error\": \"message\", \"code\": \"error_code\" }`. The `error` field is human-readable (may change wording). The `code` field is machine-readable and stable, so it is the one safe to switch on programmatically.\n\nRate limit headers on every response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Used`, `X-RateLimit-Reset` (Unix timestamp, seconds). Quotas reset on the 1st of every calendar month at 12:00 AM UTC, not on your renewal date.\n\n## Errors\n\nAll errors return `{ \"error\": \"message\", \"code\": \"error_code\" }`:\n\n| Status | Code | When |\n|--------|------|------|\n| 400 | `validation_error` | Missing or invalid parameters. Response includes `issues[]` with per-field `path`, `message`, `code`, `expected`, `minimum`, `maximum`, `format`, `pattern`. |\n| 401 | `api_key_required` | No API key provided |\n| 401 | `invalid_api_key` | Key format invalid or tampered |\n| 401 | `subscription_not_found` | Key references non-existent subscription |\n| 401 | `subscription_inactive` | Subscription cancelled, expired, or suspended |\n| 404 | `not_found` | Resource not found. Response may include a ranked `suggestions[]` array (each with `endpoint`, `hint`, and a `docs` deep link) for typo recovery. |\n| 405 | `method_not_allowed` | Path exists for a different HTTP method. Response includes `allow[]` and the `Allow` header lists valid methods. |\n| 429 | `rate_limit_exceeded` | Monthly quota reached |\n| 500 | `internal_error` | Server error |\n\n## Pricing\n\nFlat per-request pricing. Every call counts the same, whether a planet position or a full birth chart with aspects. No credit systems, no variable costs. Plans from $39 per month for 50K requests, up to 3M requests, with custom volume above that.\n\nSee [roxyapi.com/pricing](https://roxyapi.com/pricing)\n\n## Resources\n\n- [Quickstart guide](https://roxyapi.com/docs/quickstart): first API call in 60 seconds\n- [Documentation](https://roxyapi.com/docs): guides, tutorials, domain reference\n- [MCP setup](https://roxyapi.com/docs/mcp): connect AI agents\n- [Open source templates](https://roxyapi.com/starters): clone and deploy in 30 minutes\n- [FAQ](https://roxyapi.com/faq): common questions\n- [Contact](https://roxyapi.com/contact): support and API key recovery\n","contact":{"name":"RoxyAPI Support","url":"https://roxyapi.com/contact"},"license":{"name":"Proprietary","url":"https://roxyapi.com/policy/terms"}},"externalDocs":{"description":"Complete API Documentation with Examples","url":"https://roxyapi.com/docs"},"servers":[{"url":"/api/v2","description":"Production API v2"}],"security":[{"apiKey":[]}],"tags":[{"name":"Kabbalah","description":"Kabbalah API for gematria, the 72 names, the Tree of Life and the Hebrew birthday, from one key. Score a Hebrew word or a Latin name across ten rabbinic ciphers with the per letter breakdown, every candidate Hebrew spelling shown and the rule that chose one, plus a cited equal value lexicon. The 72 names are derived from the verses rather than copied from a table, the birth name is dated by the exact position of the Sun or by the civil wheel as you choose, and the sephirot, the 22 paths and the 22 letters come back under typed school variants cross linked to the tarot deck. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs."}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your API key for accessing RoxyAPI. Alternatively, you can pass the API key as a query parameter \"api_key\"."}},"schemas":{},"parameters":{}},"paths":{"/gematria":{"post":{"operationId":"calculateGematria","tags":["Kabbalah"],"summary":"Calculate gematria - Hebrew gematria calculator API with every spelling shown","description":"Score a Hebrew word or a Latin name across ten rabbinic gematria ciphers and two substitution transformations, with the per letter breakdown and the curated equal value matches beside each number. A Latin name has no single Hebrew spelling, so every candidate spelling the transliteration map produces comes back with its own values and the rule that produced it, and the chosen one is named. Built for name meaning features, numerology apps that want the Hebrew reading, and any product that has to show a reader why the number is what it is.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":200,"example":"Sarah","description":"Latin text to write in Hebrew and then score, up to 200 characters. Non Latin scripts are folded to Latin first, so a Cyrillic or Devanagari name works. Send textHebrew instead to control the Hebrew spelling yourself."},"textHebrew":{"type":"string","minLength":1,"maxLength":200,"example":"שלום","description":"Hebrew text to score, up to 200 characters. Anything outside the Hebrew script is rejected. Vowel points, cantillation marks, maqaf and paseq are removed before scoring, so a pointed and an unpointed spelling of one word give the same number."},"transliteration":{"type":"string","enum":["letter-map-mathers"],"default":"letter-map-mathers","example":"letter-map-mathers","description":"How a Latin name is written in Hebrew before it is scored. One member, a deterministic published letter map. Phonetic Ashkenazi and Sephardi schemes are not offered because no two references agree on a rule for that direction, and every published Hebrew standard romanizes the other way. Send textHebrew to control the spelling yourself."},"ciphers":{"type":"array","items":{"type":"string"},"example":["mispar-hechrachi","mispar-gadol"],"description":"Which ciphers to return, by identifier. Omit for every computed cipher. Valid values are mispar-hechrachi, mispar-gadol, otiyot-be-milui, mispar-katan, mispar-kidmi, mispar-prati, mispar-ha-merubah-ha-klali, mispar-meshulash, mispar-musafi, kolel."},"misparGadol":{"type":"string","enum":["finals-500-900","milui"],"default":"finals-500-900","example":"finals-500-900","description":"Which method the name mispar gadol means, because the sources use it for two. Use finals-500-900 to score the five word final letters as 500 to 900, or milui to score each letter as the value of its own spelled out name."},"atbashOutput":{"type":"string","enum":["both","string","value"],"default":"both","example":"both","description":"What 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, which is why the string is available on its own."},"includeMatches":{"type":"boolean","default":true,"example":true,"description":"Whether to return the curated equal value entries for the chosen spelling. Set false to skip the lookup when only the numbers are wanted."},"latinCiphers":{"type":"boolean","default":false,"example":false,"description":"Whether to also score the Latin text with the three Latin alphabet ciphers. They are Renaissance Christian and modern in lineage rather than rabbinic, and the response labels each one. Ignored when textHebrew was sent."}}}}}},"responses":{"200":{"description":"Every candidate spelling with its values, the chosen one, and the matches.","content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"object","properties":{"text":{"type":"string","example":"Sarah","description":"Echo of the Latin text sent. Absent when Hebrew was sent instead."},"textHebrew":{"type":"string","example":"שלום","description":"Echo of the Hebrew text sent. Absent when Latin was sent instead."}}},"hebrewForms":{"type":"array","items":{"type":"object","properties":{"hebrew":{"type":"string","example":"שרה","description":"One Hebrew spelling the Latin input can be written as. Data, identical in every language."},"romanization":{"type":"string","example":"ShRH","description":"Latin transcription of the Hebrew beside it, produced by one mechanical letter map. It is a label for reading the string back, never a pronunciation claim."},"rule":{"type":"string","example":"Longest match first: every two letter group the table prints is read as one Hebrew letter before the single letters are tried.","description":"Why this spelling came out of the map, so a caller can tell the parses apart."},"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"mispar-hechrachi","description":"Machine identifier of the cipher. Call the ciphers endpoint for the definition, the tradition and the sources behind each one."},"value":{"type":["number","null"],"example":376,"description":"The number this cipher gives for the string. Null on the one catalogued cipher this API does not compute, which is stated on its catalogue entry rather than left to guess."},"alternateValues":{"type":"array","items":{"type":"number"},"example":[527,536],"description":"Other published totals for the same string, ascending. Present only where the cipher is not single valued: letter names have several accepted spellings, so several totals are equally published. Absent otherwise, so a caller can branch on presence."},"tradition":{"type":"string","example":"rabbinic","description":"Provenance class of the cipher, one of rabbinic, renaissance-latin, golden-dawn-transliterated or modern. Always English, so it stays safe to compare against in code."},"source":{"type":"string","example":"https://en.wikipedia.org/wiki/Gematria","description":"The first published source this cipher was taken from."}},"required":["id","value","tradition","source"]},"description":"Every cipher applied to this spelling."},"letters":{"type":"array","items":{"type":"object","properties":{"glyph":{"type":"string","example":"ש","description":"The Hebrew letter as it stands in the string. Data, identical in every language."},"letterId":{"type":"string","example":"shin","description":"Machine identifier of the letter, always English romanization so it stays safe to compare against in code."},"name":{"type":"string","example":"Shin","description":"Display name of the letter."},"isFinal":{"type":"boolean","example":false,"description":"True when the glyph is the word final form. Under the finals-500-900 reading the same letter scores differently in final position, which is why this is on the row."},"value":{"type":"number","example":300,"description":"What this letter contributed under the standard reading, or under the finals reading when one applies."}},"required":["glyph","letterId","name","isFinal","value"]},"description":"The per letter breakdown of this spelling under the standard reading."}},"required":["hebrew","romanization","rule","values","letters"]},"description":"Every Hebrew spelling the input can be written as, greedy parse first. One entry when Hebrew was sent, since there is nothing to choose."},"chosen":{"type":"object","properties":{"hebrew":{"type":"string","example":"שרה","description":"The spelling the values and matches on this response were taken from."},"rule":{"type":"string","example":"Longest match first: every two letter group the table prints is read as one Hebrew letter before the single letters are tried.","description":"Why this spelling was chosen over the others."}},"required":["hebrew","rule"]},"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"mispar-hechrachi","description":"Machine identifier of the cipher. Call the ciphers endpoint for the definition, the tradition and the sources behind each one."},"value":{"type":["number","null"],"example":376,"description":"The number this cipher gives for the string. Null on the one catalogued cipher this API does not compute, which is stated on its catalogue entry rather than left to guess."},"alternateValues":{"type":"array","items":{"type":"number"},"example":[527,536],"description":"Other published totals for the same string, ascending. Present only where the cipher is not single valued: letter names have several accepted spellings, so several totals are equally published. Absent otherwise, so a caller can branch on presence."},"tradition":{"type":"string","example":"rabbinic","description":"Provenance class of the cipher, one of rabbinic, renaissance-latin, golden-dawn-transliterated or modern. Always English, so it stays safe to compare against in code."},"source":{"type":"string","example":"https://en.wikipedia.org/wiki/Gematria","description":"The first published source this cipher was taken from."}},"required":["id","value","tradition","source"]},"description":"Every requested cipher applied to the chosen spelling."},"transformations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"atbash","description":"Machine identifier of the transformation."},"output":{"type":"string","example":"בבל","description":"The substituted Hebrew string. Absent when atbashOutput asked for the value alone."},"outputRomanization":{"type":"string","example":"BBL","description":"Latin transcription of the substituted string, from the same mechanical letter map."},"value":{"type":"number","example":34,"description":"Standard value of the substituted string. Absent when atbashOutput asked for the string alone."},"tradition":{"type":"string","example":"rabbinic","description":"Provenance class of the transformation."},"source":{"type":"string","example":"https://en.wikipedia.org/wiki/Gematria","description":"The first published source the substitution table was taken from."}},"required":["id","tradition","source"]},"description":"The two substitution transformations applied to the chosen spelling. Each exchanges letters and returns a new word, so the interesting output is often the string rather than the number."},"latinValues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"simple-ordinal","description":"Machine identifier of the Latin cipher."},"value":{"type":"number","example":52,"description":"The number this cipher gives for the Latin text as sent."},"tradition":{"type":"string","example":"renaissance-latin","description":"Provenance class. None of these is rabbinic, whatever a consumer calculator calls them."},"lineage":{"type":"string","example":"A Latin analogue of Greek isopsephy. Traced through Etienne Tabourot 1583, Pietro Bongo, Georg Philipp Harsdorffer 1651, Athanasius Kircher 1665 and Johann Henning 1683, and called the Alphabetum Cabbalisticum Vulgare by Johann Christoph Maennling 1704 and Christian Friedrich Hunold 1707.","description":"Where the cipher comes from, stated so it cannot be misattributed."}},"required":["id","value","tradition","lineage"]},"description":"The Latin alphabet ciphers applied to the Latin text. Present only when latinCiphers was set and a Latin text was sent."},"matches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"shalom","description":"Machine identifier of the entry, an ASCII romanization."},"hebrew":{"type":"string","example":"שלום","description":"The word in Hebrew. Data, identical in every language."},"romanization":{"type":"string","example":"ShLVM","description":"Latin transcription of the Hebrew beside it, from the same mechanical letter map."},"meaning":{"type":"string","example":"peace","description":"What the word means, in the requested language."},"value":{"type":"number","example":376,"description":"Its value under the standard reading, which is why it matched."},"note":{"type":"string","example":"Peace and the name Esau share a value, which the sources treat as a deliberate pairing.","description":"What the tradition says about the equality, in the requested language."},"sources":{"type":"array","items":{"type":"string"},"example":["https://www.sefaria.org/Noam_Elimelekh%2C_Additions%2C_Likutei_Shoshana.61.1"],"description":"Where the value is attested. Every entry in the lexicon carries at least two independent sources, which is why the list is short rather than long."}},"required":["id","hebrew","romanization","meaning","value","note","sources"]},"description":"Curated words whose standard value equals the chosen spelling. Matching is on the standard reading only, because that is the relation the classical method works with. Empty when nothing matches, which is the ordinary case."},"conventions":{"type":"object","properties":{"transliteration":{"type":"string","example":"letter-map-mathers","description":"The Latin to Hebrew scheme applied. Absent when the caller sent Hebrew directly."},"misparGadol":{"type":"string","example":"finals-500-900","description":"Which of the two published methods the name mispar gadol was read as."},"atbashOutput":{"type":"string","example":"both","description":"What the substitution transformations returned."}},"required":["misparGadol","atbashOutput"]}},"required":["input","hebrewForms","chosen","values","transformations","matches","conventions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/ciphers":{"get":{"operationId":"listGematriaCiphers","tags":["Kabbalah"],"summary":"List gematria ciphers - gematria methods API with provenance on every row","description":"Return the full catalogue of gematria methods this API computes: eleven rabbinic ciphers, two substitution transformations, and the three Latin alphabet ciphers, each with its definition, its provenance class, the century of its tradition and the sources it was taken from. Every entry states whether it is rabbinic or a Renaissance Christian or modern Latin cipher, so a product never presents one tradition as the other. Built for calculators that want to show a reader which method produced a number and where the method comes from.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"responses":{"200":{"description":"The cipher catalogue, split by kind.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":16,"description":"Number of entries across all three lists."},"ciphers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"mispar-hechrachi","description":"Machine identifier of the cipher, always English romanization so it stays safe to compare against in code. Pass it in the ciphers array on the gematria endpoint."},"name":{"type":"string","example":"Mispar hechrachi (absolute value)","description":"Display name of the cipher, in the requested language."},"tradition":{"type":"string","example":"rabbinic","description":"Provenance class, one of rabbinic, renaissance-latin, golden-dawn-transliterated or modern. Always English. Read it before presenting a cipher as Jewish practice, because three of the ones here are not."},"century":{"type":"string","example":"Second century onward","description":"The century the tradition this method belongs to is attested in, not a first publication date for the named variety."},"definition":{"type":"string","example":"The standard method. Assigns 1 to 9, 10 to 90, 100 to 400 to the 22 letters in order. Final forms score as their base letter.","description":"How the cipher turns letters into a number, in the requested language."},"computed":{"type":"boolean","example":true,"description":"Whether the gematria endpoint returns a number for this cipher. False on the one method whose table is not published in two independent sources, which is stated rather than silently omitted."},"multiValued":{"type":"boolean","example":true,"description":"Present and true where one spelling has several equally published totals. Absent otherwise, so a caller can branch on presence."},"sources":{"type":"array","items":{"type":"string"},"example":["https://en.wikipedia.org/wiki/Gematria"],"description":"Where the definition is published. Every cipher here carries at least two independent sources, which is why the catalogue is shorter than the ones that advertise a cipher count."}},"required":["id","name","tradition","century","definition","computed","sources"]},"description":"The rabbinic ciphers. Each returns a number from the letters of a Hebrew string."},"transformations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"mispar-hechrachi","description":"Machine identifier of the cipher, always English romanization so it stays safe to compare against in code. Pass it in the ciphers array on the gematria endpoint."},"name":{"type":"string","example":"Mispar hechrachi (absolute value)","description":"Display name of the cipher, in the requested language."},"tradition":{"type":"string","example":"rabbinic","description":"Provenance class, one of rabbinic, renaissance-latin, golden-dawn-transliterated or modern. Always English. Read it before presenting a cipher as Jewish practice, because three of the ones here are not."},"century":{"type":"string","example":"Second century onward","description":"The century the tradition this method belongs to is attested in, not a first publication date for the named variety."},"definition":{"type":"string","example":"The standard method. Assigns 1 to 9, 10 to 90, 100 to 400 to the 22 letters in order. Final forms score as their base letter.","description":"How the cipher turns letters into a number, in the requested language."},"computed":{"type":"boolean","example":true,"description":"Whether the gematria endpoint returns a number for this cipher. False on the one method whose table is not published in two independent sources, which is stated rather than silently omitted."},"multiValued":{"type":"boolean","example":true,"description":"Present and true where one spelling has several equally published totals. Absent otherwise, so a caller can branch on presence."},"sources":{"type":"array","items":{"type":"string"},"example":["https://en.wikipedia.org/wiki/Gematria"],"description":"Where the definition is published. Every cipher here carries at least two independent sources, which is why the catalogue is shorter than the ones that advertise a cipher count."}},"required":["id","name","tradition","century","definition","computed","sources"]},"description":"The rabbinic substitution transformations. Each exchanges letters for other letters and returns a WORD, whose value is then read the ordinary way."},"latinCiphers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"mispar-hechrachi","description":"Machine identifier of the cipher, always English romanization so it stays safe to compare against in code. Pass it in the ciphers array on the gematria endpoint."},"name":{"type":"string","example":"Mispar hechrachi (absolute value)","description":"Display name of the cipher, in the requested language."},"tradition":{"type":"string","example":"rabbinic","description":"Provenance class, one of rabbinic, renaissance-latin, golden-dawn-transliterated or modern. Always English. Read it before presenting a cipher as Jewish practice, because three of the ones here are not."},"century":{"type":"string","example":"Second century onward","description":"The century the tradition this method belongs to is attested in, not a first publication date for the named variety."},"definition":{"type":"string","example":"The standard method. Assigns 1 to 9, 10 to 90, 100 to 400 to the 22 letters in order. Final forms score as their base letter.","description":"How the cipher turns letters into a number, in the requested language."},"computed":{"type":"boolean","example":true,"description":"Whether the gematria endpoint returns a number for this cipher. False on the one method whose table is not published in two independent sources, which is stated rather than silently omitted."},"multiValued":{"type":"boolean","example":true,"description":"Present and true where one spelling has several equally published totals. Absent otherwise, so a caller can branch on presence."},"sources":{"type":"array","items":{"type":"string"},"example":["https://en.wikipedia.org/wiki/Gematria"],"description":"Where the definition is published. Every cipher here carries at least two independent sources, which is why the catalogue is shorter than the ones that advertise a cipher count."}},"required":["id","name","tradition","century","definition","computed","sources"]},"description":"The Latin alphabet ciphers, scored on Latin letters directly. None is rabbinic and each carries the lineage that says so."}},"required":["total","ciphers","transformations","latinCiphers"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/name-profile":{"post":{"operationId":"generateNameProfile","tags":["Kabbalah"],"summary":"Generate a name profile - Kabbalah name numerology API with the spelling shown","description":"Score a name across the rabbinic gematria ciphers and place it on the Tree of Life, with every candidate Hebrew spelling shown and the chosen one named. The response carries the standard, the large, the small and the preceding readings with the per letter breakdown, the sephirah the reduced value points at, and the curated words that share the value. Built for name meaning pages, Kabbalah numerology features and any product that wants a name reading it can defend line by line.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"example":"Sarah","description":"The name in Latin script, to be written in Hebrew and then scored. Non Latin scripts are folded to Latin first. Send nameHebrew instead to control the spelling yourself."},"nameHebrew":{"type":"string","minLength":1,"maxLength":200,"example":"שרה","description":"The name already in Hebrew, which skips the transliteration step entirely and scores exactly the spelling you sent."},"transliteration":{"type":"string","enum":["letter-map-mathers"],"default":"letter-map-mathers","example":"letter-map-mathers","description":"How a Latin name is written in Hebrew before it is scored. One member, a deterministic published letter map. Phonetic Ashkenazi and Sephardi schemes are not offered because no two references agree on a rule for that direction, and every published Hebrew standard romanizes the other way. Send textHebrew to control the spelling yourself."},"misparGadol":{"type":"string","enum":["finals-500-900","milui"],"default":"finals-500-900","example":"finals-500-900","description":"Which method the name mispar gadol means, because the sources use it for two. Use finals-500-900 to score the five word final letters as 500 to 900, or milui to score each letter as the value of its own spelled out name."}}}}}},"responses":{"200":{"description":"The name profile.","content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"object","properties":{"name":{"type":"string","example":"Sarah","description":"Echo of the Latin name sent. Absent when Hebrew was sent instead."},"nameHebrew":{"type":"string","example":"שרה","description":"Echo of the Hebrew name sent. Absent when Latin was sent instead."}}},"hebrewForms":{"type":"array","items":{"type":"object","properties":{"hebrew":{"type":"string","example":"שרה","description":"One Hebrew spelling the Latin input can be written as. Data, identical in every language."},"romanization":{"type":"string","example":"ShRH","description":"Latin transcription of the Hebrew beside it, produced by one mechanical letter map. It is a label for reading the string back, never a pronunciation claim."},"rule":{"type":"string","example":"Longest match first: every two letter group the table prints is read as one Hebrew letter before the single letters are tried.","description":"Why this spelling came out of the map, so a caller can tell the parses apart."},"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"mispar-hechrachi","description":"Machine identifier of the cipher. Call the ciphers endpoint for the definition, the tradition and the sources behind each one."},"value":{"type":["number","null"],"example":376,"description":"The number this cipher gives for the string. Null on the one catalogued cipher this API does not compute, which is stated on its catalogue entry rather than left to guess."},"alternateValues":{"type":"array","items":{"type":"number"},"example":[527,536],"description":"Other published totals for the same string, ascending. Present only where the cipher is not single valued: letter names have several accepted spellings, so several totals are equally published. Absent otherwise, so a caller can branch on presence."},"tradition":{"type":"string","example":"rabbinic","description":"Provenance class of the cipher, one of rabbinic, renaissance-latin, golden-dawn-transliterated or modern. Always English, so it stays safe to compare against in code."},"source":{"type":"string","example":"https://en.wikipedia.org/wiki/Gematria","description":"The first published source this cipher was taken from."}},"required":["id","value","tradition","source"]},"description":"Every cipher applied to this spelling."},"letters":{"type":"array","items":{"type":"object","properties":{"glyph":{"type":"string","example":"ש","description":"The Hebrew letter as it stands in the string. Data, identical in every language."},"letterId":{"type":"string","example":"shin","description":"Machine identifier of the letter, always English romanization so it stays safe to compare against in code."},"name":{"type":"string","example":"Shin","description":"Display name of the letter."},"isFinal":{"type":"boolean","example":false,"description":"True when the glyph is the word final form. Under the finals-500-900 reading the same letter scores differently in final position, which is why this is on the row."},"value":{"type":"number","example":300,"description":"What this letter contributed under the standard reading, or under the finals reading when one applies."}},"required":["glyph","letterId","name","isFinal","value"]},"description":"The per letter breakdown of this spelling under the standard reading."}},"required":["hebrew","romanization","rule","values","letters"]},"description":"Every Hebrew spelling the name can be written as, greedy parse first. One entry when Hebrew was sent, since there is nothing to choose."},"chosen":{"type":"object","properties":{"hebrew":{"type":"string","example":"שרה","description":"The spelling the rest of this response was computed from."},"romanization":{"type":"string","example":"ShRH","description":"Latin transcription of the chosen spelling, from the mechanical map."},"rule":{"type":"string","example":"Longest match first: every two letter group the table prints is read as one Hebrew letter before the single letters are tried.","description":"Why this spelling was chosen over the others."}},"required":["hebrew","romanization","rule"]},"values":{"type":"object","properties":{"standard":{"type":"number","example":505,"description":"Mispar hechrachi, the standard reading, where every letter takes its ordinary value and a final form scores as its base letter."},"large":{"type":"number","example":505,"description":"Mispar gadol under the reading the misparGadol convention selected, which is why the convention comes back on the response."},"small":{"type":"number","example":10,"description":"Mispar katan, where each letter value has its trailing zeros truncated, so yod is 1 and qof is 1."},"preceding":{"type":"number","example":1590,"description":"Mispar kidmi, where each letter scores the sum of every standard value up to and including itself, so tav is 1495."}},"required":["standard","large","small","preceding"],"description":"The four readings a name profile leads with. Call the gematria endpoint for the full set and for the substitution transformations."},"letters":{"type":"array","items":{"type":"object","properties":{"glyph":{"type":"string","example":"ש","description":"The letter as it stands in the chosen spelling."},"letterId":{"type":"string","example":"shin","description":"Machine identifier of the letter."},"name":{"type":"string","example":"Shin","description":"Display name of the letter."},"isFinal":{"type":"boolean","example":false,"description":"True when the glyph is the word final form."},"value":{"type":"number","example":300,"description":"What this letter contributed."}},"required":["glyph","letterId","name","isFinal","value"]},"description":"The per letter breakdown of the chosen spelling."},"sephirah":{"type":"object","properties":{"id":{"type":"string","example":"malkuth","description":"Machine identifier of the sephirah the reduced value points at."},"number":{"type":["number","null"],"example":10,"description":"Its position in the emanation, 1 to 10."},"english":{"type":"string","example":"Kingdom","description":"The English gloss of the name, in the requested language."},"hebrew":{"type":"string","example":"מַלְכוּת","description":"The name in Hebrew. Data, identical in every language."},"reduced":{"type":"number","example":10,"description":"The standard value reduced by repeated digit sum, stopping at ten so all ten emanations stay reachable."},"meaning":{"type":"string","example":"Kingdom, the emanation that receives. It holds no light of its own in the classical reading, and its whole character is what it does with what arrives.","description":"What the emanation is said to hold, in the requested language."},"reading":{"type":"string","example":"Reducing the standard value of שרה gives 10, which points at Kingdom on the tree.","description":"The composed sentence that places the name on the tree, in the requested language. It states plainly that the reduction is a numerical convention rather than a classical rule."}},"required":["id","number","english","hebrew","reduced","meaning","reading"],"description":"Where the name lands on the tree. The reduction is a numerical convention, not a rule from any text, and the reading says so."},"matches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"shalom","description":"Machine identifier of the entry, an ASCII romanization."},"hebrew":{"type":"string","example":"שלום","description":"The word in Hebrew. Data, identical in every language."},"romanization":{"type":"string","example":"ShLVM","description":"Latin transcription of the Hebrew beside it, from the same mechanical letter map."},"meaning":{"type":"string","example":"peace","description":"What the word means, in the requested language."},"value":{"type":"number","example":376,"description":"Its value under the standard reading, which is why it matched."},"note":{"type":"string","example":"Peace and the name Esau share a value, which the sources treat as a deliberate pairing.","description":"What the tradition says about the equality, in the requested language."},"sources":{"type":"array","items":{"type":"string"},"example":["https://www.sefaria.org/Noam_Elimelekh%2C_Additions%2C_Likutei_Shoshana.61.1"],"description":"Where the value is attested. Every entry in the lexicon carries at least two independent sources, which is why the list is short rather than long."}},"required":["id","hebrew","romanization","meaning","value","note","sources"]},"description":"Curated words whose standard value equals the name. Empty when nothing matches, which is the ordinary case."},"conventions":{"type":"object","properties":{"transliteration":{"type":"string","example":"letter-map-mathers","description":"The Latin to Hebrew scheme applied. Absent when the caller sent Hebrew directly."},"misparGadol":{"type":"string","example":"finals-500-900","description":"Which of the two published methods the name mispar gadol was read as."}},"required":["misparGadol"]}},"required":["input","hebrewForms","chosen","values","letters","sephirah","matches","conventions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/birth-profile":{"post":{"operationId":"generateBirthProfile","tags":["Kabbalah"],"summary":"Generate a birth profile - Hebrew birthday and birth angel API","description":"Return the Hebrew date of a birth, the Hebrew birthday that follows it, the three birth names of the Renaissance angel tradition and the sephirah of the birth day, from one birth moment. The Hebrew date is computed from the published calendar algorithm rather than looked up, the sunset boundary is a typed request field because it depends on where you were, and the two rival ways of dating the first name are a typed convention the response echoes. Built for Jewish culture and education apps, birth angel features and any product that wants the Hebrew birthday on the same key as the rest of its readings.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"1990-06-15","description":"Birth date in YYYY-MM-DD, proleptic Gregorian. Dates before the 1582 reform are read on the same proleptic reckoning rather than switched to the Julian calendar."},"time":{"type":"string","format":"time","example":"14:30:00","description":"Birth time in HH:MM:SS local to the timezone field. Defaults to noon when omitted, which is stated because the name read from the hour changes every twenty minutes and a defaulted time cannot be precise."},"timezone":{"anyOf":[{"type":"number","minimum":-14,"maximum":14},{"type":"string"}],"description":"IANA name (e.g. \"America/New_York\", \"Europe/London\", \"UTC\"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. \"-05:00\", \"+01:00\"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.","example":"America/New_York"},"angelDating":{"type":"string","enum":["solar-longitude","lenain-blocks"],"default":"solar-longitude","example":"solar-longitude","description":"How the name of the day is found. Use solar-longitude for the exact five degree arc the Sun stood in at the birth moment, or lenain-blocks for the fixed civil calendar 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 and were never reconciled."},"yearStart":{"type":"string","enum":["march-21","march-20"],"default":"march-21","example":"march-21","description":"Which date the civil wheel of five day periods opens on. Both are conventions rather than facts: the equinox itself moves inside a window that covers both days, and it fell on 20 March in 2026. march-21 is the pinned published wheel and march-20 is that wheel shifted one day. Ignored when angelDating is solar-longitude."},"leapDayPolicy":{"type":"string","enum":["extend-previous","next-angel"],"default":"extend-previous","example":"extend-previous","description":"Where 29 February falls. The civil wheel was built for a 365 day year and has no slot for it, so published tables differ: extend-previous reads the day as part of the period ending 28 February, next-angel reads it as the opening of the period starting 1 March. Ignored when angelDating is solar-longitude."},"afterSunset":{"type":"boolean","default":false,"example":false,"description":"Set true when the moment falls after nightfall, which advances the Hebrew date by one day because the Hebrew day begins in the evening. It is a caller assertion rather than a computation, since sunset depends on a place and this conversion takes none."}},"required":["date","timezone"]}}}},"responses":{"200":{"description":"The Hebrew date, the birthday, the three names and the sephirah.","content":{"application/json":{"schema":{"type":"object","properties":{"birthData":{"type":"object","properties":{"date":{"type":"string","example":"1990-06-15","description":"Echo of the birth date."},"time":{"type":"string","example":"14:30:00","description":"The birth time used, which is noon when none was sent."},"timezone":{"type":"number","example":5.5,"description":"The timezone resolved to a decimal offset in hours. An IANA name sent on the request is resolved against the birth date, so a summer birth carries its summer offset."}},"required":["date","time","timezone"],"description":"The birth moment this answer was computed from."},"hebrewDate":{"type":"object","properties":{"year":{"type":"number","example":5750,"description":"Hebrew year."},"month":{"type":"string","example":"Sivan","description":"Hebrew month name. A leap year carries Adar I and Adar II in place of Adar, which is why the name is returned rather than only a number."},"monthNumber":{"type":"number","example":3,"description":"Month number in the published algorithm order, Nisan first. Adar II is 13."},"day":{"type":"number","example":22,"description":"Day of the Hebrew month, 1 to 30."},"leapYear":{"type":"boolean","example":false,"description":"True in the seven years of each nineteen that carry a second Adar."},"hebrew":{"type":"string","example":"כ״ב בסיוון תש״נ","description":"The date written the way it is printed, with the day and the year in Hebrew letters. Data, identical in every language."},"afterSunset":{"type":"boolean","example":false,"description":"Echo of the sunset flag. The Hebrew day begins in the evening, so a moment after nightfall already belongs to the next date and this says whether that was applied."}},"required":["year","month","monthNumber","day","leapYear","hebrew","afterSunset"],"description":"The Hebrew date of the birth."},"hebrewBirthday":{"type":"object","properties":{"date":{"type":["string","null"],"example":"2026-06-08","description":"The next Gregorian date the Hebrew birthday falls on, or null when that Hebrew date does not exist in the year it would fall in."},"hebrewYear":{"type":"number","example":5786,"description":"The Hebrew year the anniversary was looked for in."},"note":{"type":"string","example":"That Hebrew date does not exist in the target year, so no anniversary is returned. Which day it moves to is a matter of practice and differs between communities.","description":"Present only when the date is null, saying why. Absent otherwise, so a caller can branch on presence."}},"required":["date","hebrewYear"],"description":"The next Hebrew birthday. Three Hebrew dates are missing from some years, and where the anniversary moves to is a matter of community practice rather than arithmetic, so the field is null with a note rather than a guess."},"angels":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","example":"body","description":"What this name is read from: body and character both come from the day of birth by two different cycles, and spirit comes from the hour. Always English, so it stays safe to compare against in code."},"number":{"type":"number","example":27,"description":"Index of the name, 1 to 72."},"name":{"type":"string","example":"ירתאל","description":"The name in Hebrew. Data, identical in every language."},"romanization":{"type":"string","example":"IRThAL","description":"Latin transcription of the Hebrew, from the one mechanical letter map."},"traditionalName":{"type":"string","example":"Ierathel","description":"The Latin spelling the published tables print, which is the searchable name."},"choir":{"type":"string","example":"Dominions","description":"The angelic choir the name belongs to under the published Renaissance table."},"window":{"type":"string","example":"130 to 135 degrees of ecliptic longitude, Leo 10 to Leo 15","description":"The window that selected this name, in the terms of its own cycle: an arc of longitude, a span of civil days, or a twenty minute interval of the clock."},"reading":{"type":"string","example":"The name governing the day of birth. In this lineage it is the first of three, and the tradition reads it as the one attached to the physical circumstances a person is born into.","description":"What the tradition says this name is read for, in the requested language."}},"required":["role","number","name","romanization","traditionalName","choir","window","reading"]},"description":"The three names: two read from the day of birth by two different cycles, and one from the hour. All three are described, never invoked."},"sephirah":{"type":"object","properties":{"id":{"type":"string","example":"netzach","description":"Machine identifier of the sephirah of the birth day."},"number":{"type":["number","null"],"example":7,"description":"Its position in the emanation, 1 to 10."},"english":{"type":"string","example":"Endurance","description":"The English gloss of the name, in the requested language."},"hebrew":{"type":"string","example":"נֶצַח","description":"The name in Hebrew. Data, identical in every language."},"romanization":{"type":"string","example":"NTzCh","description":"Latin transcription of the Hebrew, from the mechanical letter map."},"meaning":{"type":"string","example":"Endurance, the impulse that keeps going after the first enthusiasm has gone. It sits low on the right hand pillar, close to where things actually get done.","description":"What the emanation is said to hold, in the requested language."}},"required":["id","number","english","hebrew","romanization","meaning"],"description":"The sephirah reached from the value of the Hebrew date written in letters. A numerical convention rather than a classical rule, offered as a way into the tree."},"conventions":{"type":"object","properties":{"angelDating":{"type":"string","example":"solar-longitude","description":"Which construction dated the name of the day."},"yearStart":{"type":"string","example":"march-21","description":"Where the civil wheel opened. Reported even under solar-longitude, where it selects nothing, so a stored response records every input."},"leapDayPolicy":{"type":"string","example":"extend-previous","description":"Where 29 February was read as falling."},"afterSunset":{"type":"boolean","example":false,"description":"Whether the Hebrew date was advanced for nightfall."}},"required":["angelDating","yearStart","leapDayPolicy","afterSunset"],"description":"The conventions this answer was computed under, echoed so it can be reproduced."}},"required":["birthData","hebrewDate","hebrewBirthday","angels","sephirah","conventions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/names":{"get":{"operationId":"listShemNames","tags":["Kabbalah"],"summary":"List the 72 names - Shem HaMephorash API derived from the verses","description":"Return the seventy two names, each with the three letters it is read from, the divine name suffix, the five degree ecliptic arc it governs, the sign that arc falls in and the angelic choir it belongs to. The names are DERIVED from three verses of Exodus read in the boustrophedon order rather than copied from a table, and any row where a named published list differs is flagged on that row. Pass a longitude to get the single name governing that degree. Built for birth angel features, Shem HaMephorash reference pages and any product that has to show where a name comes from.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":72,"default":20,"example":20,"description":"Maximum items to return per page. Range: 1-72, default 20."},"required":false,"description":"Maximum items to return per page. Range: 1-72, default 20.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"example":0,"description":"Number of items to skip for pagination. Default 0."},"required":false,"description":"Number of items to skip for pagination. Default 0.","name":"offset","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"exclusiveMaximum":360,"example":131.18,"description":"Ecliptic longitude in degrees, 0 inclusive to 360 exclusive, measured from 0 Aries. Returns the single name governing that degree instead of the list. 360 is rejected because it is the same point as 0 and the arcs are half open at the top."},"required":false,"description":"Ecliptic longitude in degrees, 0 inclusive to 360 exclusive, measured from 0 Aries. Returns the single name governing that degree instead of the list. 360 is rejected because it is the same point as 0 and the arcs are half open at the top.","name":"longitude","in":"query"}],"responses":{"200":{"description":"The names, or the one name governing the requested longitude.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":72,"description":"Number of names matching the request before paging, which is 72 for the list and 1 for a longitude lookup."},"limit":{"type":"number","example":72,"description":"How many rows this page carries at most."},"offset":{"type":"number","example":0,"description":"How many rows were skipped before this page."},"longitude":{"type":"number","example":131.18,"description":"Echo of the longitude looked up. Absent when the whole list was requested."},"names":{"type":"array","items":{"type":"object","properties":{"number":{"type":"number","example":27,"description":"Index of the name, 1 to 72. The index is the identifier here, because the Latin spellings differ between published tables while the index never does."},"letters":{"type":"string","example":"ירת","description":"The three letters read out of the verses, with any word final form written as its base letter, which is how every published list prints them."},"lettersAsWritten":{"type":"string","example":"םום","description":"The three letters exactly as they stand in the verses. Eighteen of the seventy two pick up a word final form because the source letter falls at a word end, and keeping this beside the normalized form is what makes the rule auditable."},"suffix":{"type":"string","example":"אל","description":"The divine name suffix added to make the triplet pronounceable. Forty of the seventy two take one and thirty two take the other."},"name":{"type":"string","example":"ירתאל","description":"The suffixed name in Hebrew. Data, identical in every language."},"romanization":{"type":"string","example":"IRThAL","description":"Latin transcription of the Hebrew, from the one mechanical letter map. A label for reading the string back, and NOT the spelling the published tables print, which is in traditionalName."},"traditionalName":{"type":"string","example":"Ierathel","description":"The Latin spelling the published tables print. This is the search term a reader knows the name by. Several rows have two attested spellings across tables and the one used here is stated on the methodology page."},"arcStart":{"type":"number","example":130,"description":"First degree of the ecliptic arc this name governs, measured from 0 Aries. Inclusive."},"arcEnd":{"type":"number","example":135,"description":"Last degree of the arc, EXCLUSIVE. Seventy two arcs of five degrees tile the circle exactly, which only works if the upper bound is exclusive."},"sign":{"type":"string","example":"leo","description":"Which sign the arc falls in. Always English lowercase, so it stays safe to compare against in code. Six names fall in each sign."},"degreeInSign":{"type":"number","example":10,"description":"Where the arc opens inside its sign, 0 to 25 in steps of five."},"choir":{"type":"string","example":"Dominions","description":"The angelic choir this name belongs to under the published Renaissance table. Nine choirs of exactly eight names each."},"publishedDisagreement":{"type":"object","properties":{"list":{"type":"string","example":"a second published list of the seventy two names","description":"Which published list prints something different on this row."},"prints":{"type":"string","example":"רעה","description":"What that list prints, so a caller matching against it can see why."}},"required":["list","prints"],"description":"Present only on the rows where a named published list differs from the derivation. Recorded rather than silently corrected, because a reader comparing two sources deserves to know which one moved. Absent on every other row, so a caller can branch on presence."}},"required":["number","letters","lettersAsWritten","suffix","name","romanization","traditionalName","arcStart","arcEnd","sign","degreeInSign","choir"]}}},"required":["total","limit","offset","names"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/names/{number}":{"get":{"operationId":"getShemName","tags":["Kabbalah"],"summary":"Get one of the 72 names - 72 names of God API by index","description":"Return one of the seventy two names by its index: the three letters read out of the verses, the exact positions they were read from, the suffixed name, the ecliptic arc it governs, the sign and the choir. The positions are on the response so a reader can check the derivation against the verses rather than trust it. Built for birth angel detail pages and reference features.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":["integer","null"],"example":27,"description":"Index of the name, 1 to 72."},"required":false,"description":"Index of the name, 1 to 72.","name":"number","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"responses":{"200":{"description":"The name.","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"number","example":27,"description":"Index of the name, 1 to 72. The index is the identifier here, because the Latin spellings differ between published tables while the index never does."},"letters":{"type":"string","example":"ירת","description":"The three letters read out of the verses, with any word final form written as its base letter, which is how every published list prints them."},"lettersAsWritten":{"type":"string","example":"םום","description":"The three letters exactly as they stand in the verses. Eighteen of the seventy two pick up a word final form because the source letter falls at a word end, and keeping this beside the normalized form is what makes the rule auditable."},"suffix":{"type":"string","example":"אל","description":"The divine name suffix added to make the triplet pronounceable. Forty of the seventy two take one and thirty two take the other."},"name":{"type":"string","example":"ירתאל","description":"The suffixed name in Hebrew. Data, identical in every language."},"romanization":{"type":"string","example":"IRThAL","description":"Latin transcription of the Hebrew, from the one mechanical letter map. A label for reading the string back, and NOT the spelling the published tables print, which is in traditionalName."},"traditionalName":{"type":"string","example":"Ierathel","description":"The Latin spelling the published tables print. This is the search term a reader knows the name by. Several rows have two attested spellings across tables and the one used here is stated on the methodology page."},"arcStart":{"type":"number","example":130,"description":"First degree of the ecliptic arc this name governs, measured from 0 Aries. Inclusive."},"arcEnd":{"type":"number","example":135,"description":"Last degree of the arc, EXCLUSIVE. Seventy two arcs of five degrees tile the circle exactly, which only works if the upper bound is exclusive."},"sign":{"type":"string","example":"leo","description":"Which sign the arc falls in. Always English lowercase, so it stays safe to compare against in code. Six names fall in each sign."},"degreeInSign":{"type":"number","example":10,"description":"Where the arc opens inside its sign, 0 to 25 in steps of five."},"choir":{"type":"string","example":"Dominions","description":"The angelic choir this name belongs to under the published Renaissance table. Nine choirs of exactly eight names each."},"publishedDisagreement":{"type":"object","properties":{"list":{"type":"string","example":"a second published list of the seventy two names","description":"Which published list prints something different on this row."},"prints":{"type":"string","example":"רעה","description":"What that list prints, so a caller matching against it can see why."}},"required":["list","prints"],"description":"Present only on the rows where a named published list differs from the derivation. Recorded rather than silently corrected, because a reader comparing two sources deserves to know which one moved. Absent on every other row, so a caller can branch on presence."}},"required":["number","letters","lettersAsWritten","suffix","name","romanization","traditionalName","arcStart","arcEnd","sign","degreeInSign","choir"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"No name carries that index.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. The wording may change, so do not parse it programmatically. Switch on the stable code instead."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/tree":{"get":{"operationId":"getTreeOfLife","tags":["Kabbalah"],"summary":"Get the Tree of Life - sephirot and 22 paths API with typed school variants","description":"Return the whole Tree of Life in one call: the ten sephirot with their Hebrew, their pillar, their world and their sphere, Daat beside them, the 22 paths with the letter and the tarot trump on each, the four worlds under both mappings that are in circulation, and the lightning flash order. The school splits are typed request parameters rather than hidden defaults, and the response echoes which arrangement and which reading produced it. Built for Tree of Life diagrams, tarot path features and reference pages that need the structure rather than a picture of it.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["kircher"],"default":"kircher","example":"kircher","description":"Which arrangement of the twenty two paths. The 1652 arrangement, in which Malkuth carries three paths, is the only one with a published table that letters every path, so it is the only member."},"required":false,"description":"Which arrangement of the twenty two paths. The 1652 arrangement, in which Malkuth carries three paths, is the only one with a published table that letters every path, so it is the only member.","name":"treeVariant","in":"query"},{"schema":{"type":"string","enum":["classical","golden-dawn"],"default":"classical","example":"classical","description":"Which reading assigns a sphere to each sephirah. The two were compared row by row and agree on all ten, so the answer is the same either way; the parameter exists so a caller knows which one produced it rather than assuming."},"required":false,"description":"Which reading assigns a sphere to each sephirah. The two were compared row by row and agree on all ten, so the answer is the same either way; the parameter exists so a caller knows which one produced it rather than assuming.","name":"sephirotSystem","in":"query"},{"schema":{"type":"string","enum":["sefer-yetzirah-gra","sefer-yetzirah-short","sefer-yetzirah-saadia","golden-dawn"],"default":"sefer-yetzirah-gra","example":"sefer-yetzirah-gra","description":"Which reading assigns the element, planet or sign to each letter. The seven double letters are the contested column and the four readings genuinely disagree on them; the twelve simple letters run in natural zodiacal order in all four. The golden-dawn member does NOT exchange He and Tzade, which is a later change from a different author."},"required":false,"description":"Which reading assigns the element, planet or sign to each letter. The seven double letters are the contested column and the four readings genuinely disagree on them; the twelve simple letters run in natural zodiacal order in all four. The golden-dawn member does NOT exchange He and Tzade, which is a later change from a different author.","name":"letterAttribution","in":"query"}],"responses":{"200":{"description":"The sephirot, the paths, the worlds and the lightning flash.","content":{"application/json":{"schema":{"type":"object","properties":{"sephirot":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"tiferet","description":"Machine identifier of the sephirah, an ASCII romanization, always English so it stays safe to compare against in code. Several romanizations of each name are in circulation and none is canonical, which is exactly why the id is fixed here."},"number":{"type":["number","null"],"example":6,"description":"Position in the emanation, 1 to 10. Null for Daat, which is counted in some diagrams and left out of others and is never an eleventh emanation."},"hebrew":{"type":"string","example":"תִּפְאֶרֶת","description":"The name in Hebrew, with vowel points. Data, identical in every language."},"romanization":{"type":"string","example":"ThPARTh","description":"Latin transcription of the Hebrew beside it, from the one mechanical letter map. A label for reading the string back, never a pronunciation claim and not the same thing as the id."},"english":{"type":"string","example":"Beauty","description":"The English gloss of the name, in the requested language."},"pillar":{"type":"string","example":"middle","description":"Which of the three pillars the sephirah stands on: left, middle or right. Always English."},"pillarName":{"type":"string","example":"Pillar of Equilibrium","description":"Display name of the pillar, in the requested language."},"world":{"type":["string","null"],"example":"Yetzirah","description":"Which of the four worlds the sephirah belongs to under the Hermetic mapping. Null for Daat. A second mapping is in circulation and both are returned in the worlds block."},"attribution":{"type":"string","example":"Shemesh, the Sun","description":"The sphere assigned to the sephirah under the requested system, in the requested language. This is the sephirot allotment and it is NOT the planet series the seven double letters carry."},"meaning":{"type":"string","example":"Beauty, the centre of the tree, where the giving side and the withholding side are held in one place. More paths meet here than anywhere else, which is the structure saying what the texts say.","description":"What the emanation is said to hold, in the requested language."}},"required":["id","number","hebrew","romanization","english","pillar","pillarName","world","attribution","meaning"]},"description":"The ten emanations in order, with Daat last."},"paths":{"type":"array","items":{"type":"object","properties":{"path":{"type":"number","example":32,"description":"Path number, 11 to 32. The numbering continues the ten sephirot into the thirty two Paths of Wisdom, so path 11 is the eleventh Path and not the eleventh path."},"letter":{"type":"string","example":"tav","description":"Machine identifier of the letter on the path. Each of the 22 appears exactly once."},"letterGlyph":{"type":"string","example":"ת","description":"The letter itself. Data, identical in every language."},"from":{"type":"string","example":"yesod","description":"Machine identifier of the sephirah the path runs from."},"to":{"type":"string","example":"malkuth","description":"Machine identifier of the sephirah the path runs to."},"trump":{"type":"object","properties":{"id":{"type":"string","example":"world","description":"Identifier of the tarot trump on this path. It resolves in the Tarot API on the same key."},"number":{"type":"string","example":"XXI","description":"The trump number as the deck prints it."},"name":{"type":"string","example":"The World","description":"Display name of the trump."}},"required":["id","number","name"]},"attribution":{"type":"object","properties":{"kind":{"type":"string","example":"planet","description":"What the letter attribution names: element, planet or sign."},"value":{"type":"string","example":"jupiter","description":"The element, planet or sign under the requested reading. Always English."}},"required":["kind","value"]}},"required":["path","letter","letterGlyph","from","to","trump","attribution"]},"description":"The 22 paths, in path order."},"worlds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"yetzirah","description":"Machine identifier of the world, an ASCII romanization."},"hebrew":{"type":"string","example":"יְצִירָה","description":"The name in Hebrew. Data, identical in every language."},"romanization":{"type":"string","example":"ITzIRH","description":"Latin transcription of the Hebrew, from the mechanical letter map."},"english":{"type":"string","example":"Formation","description":"The English gloss, in the requested language."},"sephirot":{"type":"array","items":{"type":"string"},"example":["chesed","gevurah","tiferet","netzach","hod","yesod"],"description":"Which sephirot fall in this world under the Hermetic mapping, the one the world field on each sephirah uses."},"sephirotAlternate":{"type":"array","items":{"type":"string"},"example":["chesed","gevurah","tiferet","netzach","hod","yesod"],"description":"Which sephirot fall in this world under the second mapping in circulation. The two agree on Formation and Action and differ at the top, and neither is suppressed."}},"required":["id","hebrew","romanization","english","sephirot","sephirotAlternate"]},"description":"The four worlds, with both published mappings of the sephirot onto them."},"lightningFlash":{"type":"array","items":{"type":"string"},"example":["keter","chokhmah","binah","chesed","gevurah","tiferet","netzach","hod","yesod","malkuth"],"description":"The order the emanation descends, top to bottom. Ten identifiers, no repeats."},"conventions":{"type":"object","properties":{"treeVariant":{"type":"string","example":"kircher","description":"Which arrangement of the paths produced this answer."},"sephirotSystem":{"type":"string","example":"classical","description":"Which reading assigned the spheres."},"letterAttribution":{"type":"string","example":"sefer-yetzirah-gra","description":"Which reading assigned the element, planet or sign on each path."}},"required":["treeVariant","sephirotSystem","letterAttribution"],"description":"The conventions this answer was computed under, echoed so it can be reproduced."}},"required":["sephirot","paths","worlds","lightningFlash","conventions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/sephirot/{id}":{"get":{"operationId":"getSephirah","tags":["Kabbalah"],"summary":"Get one sephirah - sefirot meaning API with the paths that touch it","description":"Return one sephirah in full: its Hebrew and English names, its pillar, its world, the sphere it carries under the requested system, what the emanation is said to hold, and every path that touches it with the letter and the tarot trump on each. Daat is addressable here as well, and its response says plainly that it is counted in some diagrams and not in others. Built for sephirot detail pages and for tree diagrams that load one node at a time.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["keter","chokhmah","binah","chesed","gevurah","tiferet","netzach","hod","yesod","malkuth","daat"],"example":"tiferet","description":"Sephirah identifier, one of keter, chokhmah, binah, chesed, gevurah, tiferet, netzach, hod, yesod, malkuth, daat. Matching folds case and punctuation."},"required":true,"description":"Sephirah identifier, one of keter, chokhmah, binah, chesed, gevurah, tiferet, netzach, hod, yesod, malkuth, daat. Matching folds case and punctuation.","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["classical","golden-dawn"],"default":"classical","example":"classical","description":"Which reading assigns a sphere to each sephirah. The two were compared row by row and agree on all ten, so the answer is the same either way; the parameter exists so a caller knows which one produced it rather than assuming."},"required":false,"description":"Which reading assigns a sphere to each sephirah. The two were compared row by row and agree on all ten, so the answer is the same either way; the parameter exists so a caller knows which one produced it rather than assuming.","name":"sephirotSystem","in":"query"},{"schema":{"type":"string","enum":["sefer-yetzirah-gra","sefer-yetzirah-short","sefer-yetzirah-saadia","golden-dawn"],"default":"sefer-yetzirah-gra","example":"sefer-yetzirah-gra","description":"Which reading assigns the element, planet or sign to each letter. The seven double letters are the contested column and the four readings genuinely disagree on them; the twelve simple letters run in natural zodiacal order in all four. The golden-dawn member does NOT exchange He and Tzade, which is a later change from a different author."},"required":false,"description":"Which reading assigns the element, planet or sign to each letter. The seven double letters are the contested column and the four readings genuinely disagree on them; the twelve simple letters run in natural zodiacal order in all four. The golden-dawn member does NOT exchange He and Tzade, which is a later change from a different author.","name":"letterAttribution","in":"query"}],"responses":{"200":{"description":"The sephirah, with the paths that touch it.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"tiferet","description":"Machine identifier of the sephirah, an ASCII romanization, always English so it stays safe to compare against in code. Several romanizations of each name are in circulation and none is canonical, which is exactly why the id is fixed here."},"number":{"type":["number","null"],"example":6,"description":"Position in the emanation, 1 to 10. Null for Daat, which is counted in some diagrams and left out of others and is never an eleventh emanation."},"hebrew":{"type":"string","example":"תִּפְאֶרֶת","description":"The name in Hebrew, with vowel points. Data, identical in every language."},"romanization":{"type":"string","example":"ThPARTh","description":"Latin transcription of the Hebrew beside it, from the one mechanical letter map. A label for reading the string back, never a pronunciation claim and not the same thing as the id."},"english":{"type":"string","example":"Beauty","description":"The English gloss of the name, in the requested language."},"pillar":{"type":"string","example":"middle","description":"Which of the three pillars the sephirah stands on: left, middle or right. Always English."},"pillarName":{"type":"string","example":"Pillar of Equilibrium","description":"Display name of the pillar, in the requested language."},"world":{"type":["string","null"],"example":"Yetzirah","description":"Which of the four worlds the sephirah belongs to under the Hermetic mapping. Null for Daat. A second mapping is in circulation and both are returned in the worlds block."},"attribution":{"type":"string","example":"Shemesh, the Sun","description":"The sphere assigned to the sephirah under the requested system, in the requested language. This is the sephirot allotment and it is NOT the planet series the seven double letters carry."},"meaning":{"type":"string","example":"Beauty, the centre of the tree, where the giving side and the withholding side are held in one place. More paths meet here than anywhere else, which is the structure saying what the texts say.","description":"What the emanation is said to hold, in the requested language."},"paths":{"type":"array","items":{"type":"object","properties":{"path":{"type":"number","example":32,"description":"Path number, 11 to 32. The numbering continues the ten sephirot into the thirty two Paths of Wisdom, so path 11 is the eleventh Path and not the eleventh path."},"letter":{"type":"string","example":"tav","description":"Machine identifier of the letter on the path. Each of the 22 appears exactly once."},"letterGlyph":{"type":"string","example":"ת","description":"The letter itself. Data, identical in every language."},"from":{"type":"string","example":"yesod","description":"Machine identifier of the sephirah the path runs from."},"to":{"type":"string","example":"malkuth","description":"Machine identifier of the sephirah the path runs to."},"trump":{"type":"object","properties":{"id":{"type":"string","example":"world","description":"Identifier of the tarot trump on this path. It resolves in the Tarot API on the same key."},"number":{"type":"string","example":"XXI","description":"The trump number as the deck prints it."},"name":{"type":"string","example":"The World","description":"Display name of the trump."}},"required":["id","number","name"]},"attribution":{"type":"object","properties":{"kind":{"type":"string","example":"planet","description":"What the letter attribution names: element, planet or sign."},"value":{"type":"string","example":"jupiter","description":"The element, planet or sign under the requested reading. Always English."}},"required":["kind","value"]}},"required":["path","letter","letterGlyph","from","to","trump","attribution"]},"description":"Every path that runs to or from this sephirah, in path order. Malkuth carries three under the arrangement this API ships, which is the whole difference between the two arrangements in circulation."},"conventions":{"type":"object","properties":{"sephirotSystem":{"type":"string","example":"classical","description":"Which reading assigned the sphere."},"letterAttribution":{"type":"string","example":"sefer-yetzirah-gra","description":"Which reading assigned the element, planet or sign on each path."}},"required":["sephirotSystem","letterAttribution"],"description":"The conventions this answer was computed under."}},"required":["id","number","hebrew","romanization","english","pillar","pillarName","world","attribution","meaning","paths","conventions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"No sephirah carries that identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. The wording may change, so do not parse it programmatically. Switch on the stable code instead."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/letters":{"get":{"operationId":"listHebrewLetters","tags":["Kabbalah"],"summary":"List the Hebrew letters - Hebrew alphabet API with the Sefer Yetzirah attributions","description":"Return all 22 Hebrew letters with their numeric value, their final form, their Sefer Yetzirah class, the element or planet or sign they carry under the requested reading, the tarot trump on their path and the path number itself. The letter attributions are a documented school split rather than a fixed table, so the reading is a request parameter and the response echoes which one produced the answer. Built for letter reference pages, tarot apps that render the paths, and any feature that has to say what a letter carries and on whose authority.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["sefer-yetzirah-gra","sefer-yetzirah-short","sefer-yetzirah-saadia","golden-dawn"],"default":"sefer-yetzirah-gra","example":"sefer-yetzirah-gra","description":"Which reading assigns the element, planet or sign to each letter. The seven double letters are the contested column and the four readings genuinely disagree on them; the twelve simple letters run in natural zodiacal order in all four. The golden-dawn member does NOT exchange He and Tzade, which is a later change from a different author."},"required":false,"description":"Which reading assigns the element, planet or sign to each letter. The seven double letters are the contested column and the four readings genuinely disagree on them; the twelve simple letters run in natural zodiacal order in all four. The golden-dawn member does NOT exchange He and Tzade, which is a later change from a different author.","name":"letterAttribution","in":"query"}],"responses":{"200":{"description":"All 22 letters in alphabet order.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number","example":22,"description":"Number of letters returned, which is always 22."},"letterAttribution":{"type":"string","example":"sefer-yetzirah-gra","description":"Echo of the reading the attributions were taken from."},"classCounts":{"type":"object","properties":{"mother":{"type":"number","example":3,"description":"Mother letters, which take an element."},"double":{"type":"number","example":7,"description":"Double letters, which take a planet."},"simple":{"type":"number","example":12,"description":"Simple letters, which take a sign of the zodiac."}},"required":["mother","double","simple"],"description":"Three, seven and twelve. Every recension agrees on the split even where it disagrees on what goes where."},"letters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"shin","description":"Machine identifier of the letter, always English romanization so it stays safe to compare against in code."},"letter":{"type":"string","example":"ש","description":"The base glyph. Data, identical in every language."},"final":{"type":["string","null"],"example":"ם","description":"The word final glyph, or null for the seventeen letters that have none. Five letters change shape at the end of a word and score differently there under one reading of mispar gadol."},"romanization":{"type":"string","example":"Sh","description":"Latin transcription of the glyph, from the one mechanical letter map this API uses in both directions. A label, never a pronunciation claim."},"name":{"type":"string","example":"Shin","description":"Display name of the letter, in the requested language."},"meaning":{"type":"string","example":"Tooth","description":"What the letter name means as an ordinary word, in the requested language. The names are object names, which is what the shapes were drawn from."},"ordinal":{"type":"number","example":21,"description":"Position in the alphabet, 1 to 22. A property of the letter, not a cipher reading."},"value":{"type":"number","example":300,"description":"Value under the standard reading. The 22 letters cover 1 to 9, 10 to 90 and 100 to 400."},"finalValue":{"type":["number","null"],"example":900,"description":"Value in final position under the finals-500-900 reading of mispar gadol, or null where the letter has no final form."},"letterClass":{"type":"string","example":"mother","description":"Sefer Yetzirah class: mother, double or simple. Three mothers take an element, seven doubles take a planet, twelve simples take a sign, and the three counts are the structure of the whole letter tradition."},"classReading":{"type":"string","example":"One of the three mother letters. The Sefer Yetzirah gives each of the three an element, and they are the top of the letter hierarchy rather than one class among many.","description":"What the class means, in the requested language."},"attribution":{"type":"object","properties":{"kind":{"type":"string","example":"element","description":"What the attribution names: element, planet or sign. Always English."},"value":{"type":"string","example":"fire","description":"The element, planet or sign under the requested reading. Always English, so it stays safe to compare against in code."}},"required":["kind","value"]},"trump":{"type":"object","properties":{"id":{"type":"string","example":"judgement","description":"Identifier of the tarot trump on this letter path. It resolves in the Tarot API on the same key, so a caller can follow it straight to the card."},"number":{"type":"string","example":"XX","description":"The trump number as the deck prints it, in Roman numerals."},"name":{"type":"string","example":"Judgement","description":"Display name of the trump."}},"required":["id","number","name"]},"path":{"type":["number","null"],"example":31,"description":"The path this letter sits on, numbered 11 to 32 to continue the ten sephirot into the thirty two Paths of Wisdom. Never null in practice: all 22 letters carry a path."}},"required":["id","letter","final","romanization","name","meaning","ordinal","value","finalValue","letterClass","classReading","attribution","trump","path"]}}},"required":["total","letterAttribution","classCounts","letters"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/letters/{id}":{"get":{"operationId":"getHebrewLetter","tags":["Kabbalah"],"summary":"Get one Hebrew letter - Hebrew letter meaning API","description":"Return one Hebrew letter in full: its glyph and final form, its value under the standard and the finals reading, its Sefer Yetzirah class and what that class means, the element or planet or sign it carries under the requested reading, the tarot trump on its path, and the path number. Built for letter detail pages and for any reader who wants one row rather than all 22 letters.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["alef","bet","gimel","dalet","he","vav","zayin","chet","tet","yod","kaf","lamed","mem","nun","samekh","ayin","pe","tzadi","qof","resh","shin","tav"],"example":"shin","description":"Letter identifier, one of alef, bet, gimel, dalet, he, vav, zayin, chet, tet, yod, kaf, lamed, mem, nun, samekh, ayin, pe, tzadi, qof, resh, shin, tav. Matching folds case and punctuation."},"required":true,"description":"Letter identifier, one of alef, bet, gimel, dalet, he, vav, zayin, chet, tet, yod, kaf, lamed, mem, nun, samekh, ayin, pe, tzadi, qof, resh, shin, tav. Matching folds case and punctuation.","name":"id","in":"path"},{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"string","enum":["sefer-yetzirah-gra","sefer-yetzirah-short","sefer-yetzirah-saadia","golden-dawn"],"default":"sefer-yetzirah-gra","example":"sefer-yetzirah-gra","description":"Which reading assigns the element, planet or sign to each letter. The seven double letters are the contested column and the four readings genuinely disagree on them; the twelve simple letters run in natural zodiacal order in all four. The golden-dawn member does NOT exchange He and Tzade, which is a later change from a different author."},"required":false,"description":"Which reading assigns the element, planet or sign to each letter. The seven double letters are the contested column and the four readings genuinely disagree on them; the twelve simple letters run in natural zodiacal order in all four. The golden-dawn member does NOT exchange He and Tzade, which is a later change from a different author.","name":"letterAttribution","in":"query"}],"responses":{"200":{"description":"The letter.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"shin","description":"Machine identifier of the letter, always English romanization so it stays safe to compare against in code."},"letter":{"type":"string","example":"ש","description":"The base glyph. Data, identical in every language."},"final":{"type":["string","null"],"example":"ם","description":"The word final glyph, or null for the seventeen letters that have none. Five letters change shape at the end of a word and score differently there under one reading of mispar gadol."},"romanization":{"type":"string","example":"Sh","description":"Latin transcription of the glyph, from the one mechanical letter map this API uses in both directions. A label, never a pronunciation claim."},"name":{"type":"string","example":"Shin","description":"Display name of the letter, in the requested language."},"meaning":{"type":"string","example":"Tooth","description":"What the letter name means as an ordinary word, in the requested language. The names are object names, which is what the shapes were drawn from."},"ordinal":{"type":"number","example":21,"description":"Position in the alphabet, 1 to 22. A property of the letter, not a cipher reading."},"value":{"type":"number","example":300,"description":"Value under the standard reading. The 22 letters cover 1 to 9, 10 to 90 and 100 to 400."},"finalValue":{"type":["number","null"],"example":900,"description":"Value in final position under the finals-500-900 reading of mispar gadol, or null where the letter has no final form."},"letterClass":{"type":"string","example":"mother","description":"Sefer Yetzirah class: mother, double or simple. Three mothers take an element, seven doubles take a planet, twelve simples take a sign, and the three counts are the structure of the whole letter tradition."},"classReading":{"type":"string","example":"One of the three mother letters. The Sefer Yetzirah gives each of the three an element, and they are the top of the letter hierarchy rather than one class among many.","description":"What the class means, in the requested language."},"attribution":{"type":"object","properties":{"kind":{"type":"string","example":"element","description":"What the attribution names: element, planet or sign. Always English."},"value":{"type":"string","example":"fire","description":"The element, planet or sign under the requested reading. Always English, so it stays safe to compare against in code."}},"required":["kind","value"]},"trump":{"type":"object","properties":{"id":{"type":"string","example":"judgement","description":"Identifier of the tarot trump on this letter path. It resolves in the Tarot API on the same key, so a caller can follow it straight to the card."},"number":{"type":"string","example":"XX","description":"The trump number as the deck prints it, in Roman numerals."},"name":{"type":"string","example":"Judgement","description":"Display name of the trump."}},"required":["id","number","name"]},"path":{"type":["number","null"],"example":31,"description":"The path this letter sits on, numbered 11 to 32 to continue the ten sephirot into the thirty two Paths of Wisdom. Never null in practice: all 22 letters carry a path."}},"required":["id","letter","final","romanization","name","meaning","ordinal","value","finalValue","letterClass","classReading","attribution","trump","path"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"404":{"description":"No letter carries that identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Resource not found","description":"Human-readable error message. The wording may change, so do not parse it programmatically. Switch on the stable code instead."},"code":{"type":"string","example":"not_found","description":"Machine-readable error code. Stable identifier for programmatic error handling."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/compatibility":{"post":{"operationId":"calculateNameCompatibility","tags":["Kabbalah"],"summary":"Compare two names - gematria name compatibility API with every component published","description":"Score two names against each other in gematria and return both profiles, the ciphers they agree on, and a composite with every component and its maximum published beside it. Equal value under the standard reading is the one relation the classical method actually works with and it carries the largest weight; the rest of the composite is ours and the response says so, so a caller can recompute or ignore it. Built for name compatibility features, relationship content and any product that wants a number it can show the arithmetic for.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":200,"example":"Sarah","description":"First name in Latin script. Send firstNameHebrew instead to control the spelling."},"firstNameHebrew":{"type":"string","minLength":1,"maxLength":200,"example":"שרה","description":"First name already in Hebrew, which skips the transliteration step."},"secondName":{"type":"string","minLength":1,"maxLength":200,"example":"David","description":"Second name in Latin script. Send secondNameHebrew instead to control the spelling."},"secondNameHebrew":{"type":"string","minLength":1,"maxLength":200,"example":"דוד","description":"Second name already in Hebrew, which skips the transliteration step."},"transliteration":{"type":"string","enum":["letter-map-mathers"],"default":"letter-map-mathers","example":"letter-map-mathers","description":"How a Latin name is written in Hebrew before it is scored. One member, a deterministic published letter map. Phonetic Ashkenazi and Sephardi schemes are not offered because no two references agree on a rule for that direction, and every published Hebrew standard romanizes the other way. Send textHebrew to control the spelling yourself."},"misparGadol":{"type":"string","enum":["finals-500-900","milui"],"default":"finals-500-900","example":"finals-500-900","description":"Which method the name mispar gadol means, because the sources use it for two. Use finals-500-900 to score the five word final letters as 500 to 900, or milui to score each letter as the value of its own spelled out name."}}}}}},"responses":{"200":{"description":"Both profiles, what they share, and the composite with its components.","content":{"application/json":{"schema":{"type":"object","properties":{"first":{"type":"object","properties":{"input":{"type":"string","example":"Sarah","description":"The name as sent, in whichever script it was sent in."},"hebrew":{"type":"string","example":"שרה","description":"The Hebrew spelling this side was scored from."},"romanization":{"type":"string","example":"ShRH","description":"Latin transcription of that spelling, from the one mechanical letter map."},"rule":{"type":"string","example":"Longest match first: every two letter group the table prints is read as one Hebrew letter before the single letters are tried.","description":"Why this spelling was chosen over the other parses."},"standard":{"type":"number","example":505,"description":"Value under the standard reading, which is the relation the tradition works with."},"reduced":{"type":"number","example":10,"description":"The standard value reduced by repeated digit sum, stopping at ten."},"sephirah":{"type":"string","example":"malkuth","description":"Machine identifier of the sephirah the reduced value points at."},"sephirahEnglish":{"type":"string","example":"Kingdom","description":"The English gloss of that sephirah, in the requested language."}},"required":["input","hebrew","romanization","rule","standard","reduced","sephirah","sephirahEnglish"]},"second":{"type":"object","properties":{"input":{"type":"string","example":"Sarah","description":"The name as sent, in whichever script it was sent in."},"hebrew":{"type":"string","example":"שרה","description":"The Hebrew spelling this side was scored from."},"romanization":{"type":"string","example":"ShRH","description":"Latin transcription of that spelling, from the one mechanical letter map."},"rule":{"type":"string","example":"Longest match first: every two letter group the table prints is read as one Hebrew letter before the single letters are tried.","description":"Why this spelling was chosen over the other parses."},"standard":{"type":"number","example":505,"description":"Value under the standard reading, which is the relation the tradition works with."},"reduced":{"type":"number","example":10,"description":"The standard value reduced by repeated digit sum, stopping at ten."},"sephirah":{"type":"string","example":"malkuth","description":"Machine identifier of the sephirah the reduced value points at."},"sephirahEnglish":{"type":"string","example":"Kingdom","description":"The English gloss of that sephirah, in the requested language."}},"required":["input","hebrew","romanization","rule","standard","reduced","sephirah","sephirahEnglish"]},"sharedValues":{"type":"array","items":{"type":"object","properties":{"cipher":{"type":"string","example":"mispar-katan","description":"Machine identifier of the cipher the two names agree on."},"name":{"type":"string","example":"Mispar katan (small value)","description":"Display name of that cipher."},"value":{"type":"number","example":10,"description":"The value both names give under it."}},"required":["cipher","name","value"]},"description":"Every cipher on which the two names give the same number. Empty when they share none, which happens often and carries no traditional reading of its own."},"score":{"type":"number","example":45,"description":"The composite, 0 to 100. A RoxyAPI composite, not a classical measure: no source scores two names against each other, so the components below are published and the number is derivable from them."},"band":{"type":"string","example":"moderate","description":"Which band the composite falls in: high, moderate or low. Derived from the score, always English."},"components":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"equalStandardValue","description":"Machine identifier of the component."},"points":{"type":"number","example":35,"description":"What this component contributed."},"maximum":{"type":"number","example":35,"description":"The most it can contribute. The four maxima sum to 100, so the weighting is visible rather than implied."},"matched":{"type":"boolean","example":true,"description":"Whether the component found anything at all."}},"required":["id","points","maximum","matched"]},"description":"Every component of the composite with its own maximum, so a caller who disagrees with the weighting can recompute rather than argue."},"reading":{"type":"string","example":"The two names meet on some readings and part on others, which is the ordinary case rather than a middling result.","description":"The composed reading, in the requested language. It states that the score is ours."},"conventions":{"type":"object","properties":{"transliteration":{"type":"string","example":"letter-map-mathers","description":"The Latin to Hebrew scheme applied. Absent when both names arrived in Hebrew."},"misparGadol":{"type":"string","example":"finals-500-900","description":"Which of the two published methods the name mispar gadol was read as."}},"required":["misparGadol"],"description":"The conventions this answer was computed under."}},"required":["first","second","sharedValues","score","band","components","reading","conventions"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}},"/daily":{"get":{"operationId":"getDailySephirah","tags":["Kabbalah"],"summary":"Get the sephirah of the day - Omer count API with the sephirot pairing","description":"Return the day of the Omer count for a date, with the sephirah of the week, the sephirah of the day inside it, the printed Hebrew label and a composed reading. The count is a real, dated, forty nine day observance rather than an invented daily, so outside the window the response says the count is not running and gives the date it next opens. Built for daily widgets, Jewish calendar features and lifecycle emails that want a dated reading rather than a random one.","security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["en","tr","de","es","hi","pt","fr","ru","zh-Hans","zh-Hant"],"default":"en","example":"en","description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English."},"required":false,"description":"Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.","name":"lang","in":"query"},{"schema":{"type":"string","format":"date","example":"2026-04-04","description":"Date in YYYY-MM-DD. Defaults to the current UTC date when omitted, so a caller that wants a fixed answer should send one."},"required":false,"description":"Date in YYYY-MM-DD. Defaults to the current UTC date when omitted, so a caller that wants a fixed answer should send one.","name":"date","in":"query"},{"schema":{"type":"string","example":"Asia/Jerusalem","description":"IANA name or decimal offset, used only to decide which calendar date it is where the caller is when date is omitted. It does not move the count, which is a calendar count rather than a clock one."},"required":false,"description":"IANA name or decimal offset, used only to decide which calendar date it is where the caller is when date is omitted. It does not move the count, which is a calendar count rather than a clock one.","name":"timezone","in":"query"},{"schema":{"type":"string","example":"false","description":"Set true when the moment falls after nightfall, which advances the Hebrew date by one day because the Hebrew day begins in the evening. It is a caller assertion rather than a computation, since sunset depends on a place and this route takes none."},"required":false,"description":"Set true when the moment falls after nightfall, which advances the Hebrew date by one day because the Hebrew day begins in the evening. It is a caller assertion rather than a computation, since sunset depends on a place and this route takes none.","name":"afterSunset","in":"query"}],"responses":{"200":{"description":"The Omer day, or a statement that the count is not running.","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","example":"2026-04-04","description":"The date this answer is for. Echoes the request or the resolved date."},"inOmer":{"type":"boolean","example":true,"description":"Whether the count is running on this date. False outside the forty nine days, and the fields below the count are then absent."},"day":{"type":"number","example":1,"description":"Day of the count, 1 to 49. Absent when the count is not running."},"week":{"type":"number","example":1,"description":"Which of the seven weeks the day falls in. Absent outside the count."},"dayInWeek":{"type":"number","example":1,"description":"Which day inside that week, 1 to 7. Absent outside the count."},"weekSephirah":{"type":"object","properties":{"id":{"type":"string","example":"chesed","description":"Machine identifier of the sephirah, always English so it stays safe to compare against in code."},"hebrew":{"type":"string","example":"חסד","description":"The name in Hebrew, unpointed. Data, identical in every language."},"romanization":{"type":"string","example":"ChSD","description":"Latin transcription of the Hebrew, from the one mechanical letter map."},"english":{"type":"string","example":"Mercy","description":"The English gloss of the name, in the requested language."}},"required":["id","hebrew","romanization","english"],"description":"The sephirah of the WEEK, which is the outer half of the label. Absent outside the count."},"daySephirah":{"type":"object","properties":{"id":{"type":"string","example":"chesed","description":"Machine identifier of the sephirah, always English so it stays safe to compare against in code."},"hebrew":{"type":"string","example":"חסד","description":"The name in Hebrew, unpointed. Data, identical in every language."},"romanization":{"type":"string","example":"ChSD","description":"Latin transcription of the Hebrew, from the one mechanical letter map."},"english":{"type":"string","example":"Mercy","description":"The English gloss of the name, in the requested language."}},"required":["id","hebrew","romanization","english"],"description":"The sephirah of the DAY inside the week, which is the inner half of the label and is named first. Absent outside the count."},"hebrewLabel":{"type":"string","example":"חסד שבחסד","description":"The label as the printed text carries it, inner then outer. Absent outside the count."},"hebrewDate":{"type":"string","example":"Nisan 16","description":"The Hebrew month and day of this Omer day. Day 1 is 16 Nisan, the second day of Passover, on the reckoning this API uses. Absent outside the count."},"reading":{"type":"string","example":"Day 1 of the count falls in week 1, so the week opens a hand and keeps it open and the day inside it opens a hand and keeps it open.","description":"The composed reading for the day, in the requested language."},"nextStart":{"type":"string","example":"2027-04-22","description":"The date the count next opens. Present only when the count is not running, so a caller can branch on presence."}},"required":["date","inOmer","reading"]}}}},"400":{"description":"Validation error. `issues[]` lists every failed field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"First issue summary."},"code":{"type":"string","enum":["validation_error"]},"issues":{"type":"array","description":"Every validation failure. Use this to rebuild a valid request.","items":{"type":"object","properties":{"path":{"type":"string","description":"Dot-separated field path, or \"(root)\" for top-level."},"message":{"type":"string"},"code":{"type":"string","description":"Zod issue code (invalid_type, too_small, too_big, invalid_string, ...)."},"expected":{"type":"string","description":"Expected type for invalid_type."},"minimum":{"description":"Minimum bound for too_small issues.","oneOf":[{"type":"number"},{"type":"string"}]},"maximum":{"description":"Maximum bound for too_big issues.","oneOf":[{"type":"number"},{"type":"string"}]},"inclusive":{"type":"boolean"},"format":{"type":"string","description":"Format name for string issues (regex, email, url, uuid)."},"pattern":{"type":"string","description":"Regex pattern when format is regex."}},"required":["path","message"]}}},"required":["error","code","issues"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"405":{"description":"Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.","headers":{"Allow":{"description":"Comma-separated list of allowed methods (RFC 9110).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["method_not_allowed"]},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods for this path. Mirrors the Allow response header."},"docs":{"type":"string","description":"Link to the product page for this domain."}},"required":["error","code","allow"]}}}},"429":{"description":"Monthly rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message. May change wording."},"code":{"type":"string","description":"Machine-readable error code. Stable identifier."}},"required":["error","code"]}}}}}}}},"webhooks":{}}