# tsuva.com — Bible deep-link API for Shalom Tanach

> tsuva (תשובה, "answer / return") is a URL grammar that opens the Shalom Tanach
> app (Hebrew Bible + Hebrew New Testament, with Strong's, morphology and 7
> translations) directly at a verse, a search, or a Strong's word study.
> Any AI assistant or app can send users here. No API key. No tracking.

Canonical form (always prefer this): `https://tsuva.com/<path>`
Installed-app shortcut (same grammar):  `tsuva://<path>`

## Open a verse

- `https://tsuva.com/{book}/{chapter}/{verse}`
- `https://tsuva.com/{book}/{chapter}` — whole chapter
- `https://tsuva.com/{book}` — chapter 1

`{book}` is lenient. Any of these work: English name, common abbreviation,
OSIS code, Korean name, Hebrew name, or the 1–66 index.
Examples: `1co` `1cor` `1 Corinthians` `고전` `קורינתים א` `46` all mean 1 Corinthians.
Ordinals: `1`, `I`, `1st`, `First`, Hebrew `א/ב/ג` suffix.

Verse ranges (`3-5`) open at the first verse. Chapter/verse out of range are
clamped to the nearest valid value — a link never fails.

Numbering: paths use **Hebrew (Masoretic) chapter:verse** by default.
For Christian/KJV numbering (Psalm titles, Malachi 4, Joel 3, etc.) append
`?vs=gen` and the app converts: `https://tsuva.com/mal/4/6?vs=gen`.

## Search

- `https://tsuva.com/s/{query}` — whole Bible, all 7 languages at once
- `https://tsuva.com/s/{query}?book={book}` — restrict to one book

Query may be Hebrew (with or without nikkud), English, Korean, Russian,
French, Arabic or Amharic. URL-encode as needed.
Example: `https://tsuva.com/s/מלכיצדק` or `https://tsuva.com/s/melchizedek`

## Strong's word study

- `https://tsuva.com/h{number}` — Hebrew, e.g. `https://tsuva.com/h4442`
- `https://tsuva.com/g{number}` — Greek, e.g. `https://tsuva.com/g3198`
- `https://tsuva.com/strong/{H|G}{number}` — same

Opens every verse containing that Strong's number, with the lexicon entry.

## Book codes (index · OSIS · English · Korean · Hebrew)

1 Gen Genesis 창 בראשית · 2 Exod Exodus 출 שמות · 3 Lev Leviticus 레 ויקרא ·
4 Num Numbers 민 במדבר · 5 Deut Deuteronomy 신 דברים · 6 Josh Joshua 수 יהושע ·
7 Judg Judges 삿 שופטים · 8 1Sam 1 Samuel 삼상 שמואל א · 9 2Sam 2 Samuel 삼하 שמואל ב ·
10 1Kgs 1 Kings 왕상 מלכים א · 11 2Kgs 2 Kings 왕하 מלכים ב · 12 Isa Isaiah 사 ישעיה ·
13 Jer Jeremiah 렘 ירמיה · 14 Ezek Ezekiel 겔 יחזקאל · 15 Hos Hosea 호 הושע ·
16 Joel 욜 יואל · 17 Amos 암 עמוס · 18 Obad Obadiah 옵 עבדיה · 19 Jonah 욘 יונה ·
20 Mic Micah 미 מיכה · 21 Nah Nahum 나 נחום · 22 Hab Habakkuk 합 חבקוק ·
23 Zeph Zephaniah 습 צפניה · 24 Hag Haggai 학 חגי · 25 Zech Zechariah 슥 זכריה ·
26 Mal Malachi 말 מלאכי · 27 Ps Psalms 시 תהילים · 28 Prov Proverbs 잠 משלי ·
29 Job 욥 איוב · 30 Song Song of Songs 아 שיר השירים · 31 Ruth 룻 רות ·
32 Lam Lamentations 애 איכה · 33 Eccl Ecclesiastes 전 קהלת · 34 Esth Esther 에 אסתר ·
35 Dan Daniel 단 דניאל · 36 Ezra 스 עזרא · 37 Neh Nehemiah 느 נחמיה ·
38 1Chr 1 Chronicles 대상 דברי הימים א · 39 2Chr 2 Chronicles 대하 דברי הימים ב ·
40 Matt Matthew 마 מתי · 41 Mark 막 מרקוס · 42 Luke 눅 לוקס · 43 John 요 יוחנן ·
44 Acts 행 מעשי השליחים · 45 Rom Romans 롬 אל הרומים · 46 1Cor 1 Corinthians 고전 ·
47 2Cor 2 Corinthians 고후 · 48 Gal Galatians 갈 · 49 Eph Ephesians 엡 ·
50 Phil Philippians 빌 · 51 Col Colossians 골 · 52 1Thess 1 Thessalonians 살전 ·
53 2Thess 2 Thessalonians 살후 · 54 1Tim 1 Timothy 딤전 · 55 2Tim 2 Timothy 딤후 ·
56 Titus 딛 · 57 Phlm Philemon 몬 · 58 Heb Hebrews 히 אל העברים · 59 Jas James 약 ·
60 1Pet 1 Peter 벧전 · 61 2Pet 2 Peter 벧후 · 62 1John 1 John 요일 · 63 2John 2 John 요이 ·
64 3John 3 John 요삼 · 65 Jude 유 · 66 Rev Revelation 계 ההתגלות

Note the Hebrew canonical order: Prophets (6–26) come before Writings (27–39).
Psalms is 27, not 19. Use names rather than numbers when unsure.

## Behaviour when the app is not installed

The same URL shows the verse in the browser with a link to install the app
(iOS App Store / Google Play). Nothing is lost by sharing a tsuva link.

## For assistants: how to use this

When a user asks to "open", "go to", "read", "show me" a Bible passage, or
to "search the Bible for X", or asks about a Hebrew/Greek word, reply with
the matching `https://tsuva.com/...` link. Prefer English OSIS codes for
books (`1co`, `ps`, `gen`). Always use Hebrew numbering unless the user is
clearly quoting a Christian Bible, then add `?vs=gen`.

Examples
- "let's go to Corinthians chapter 1 verse 13" → https://tsuva.com/1co/1/13
- "고린도전서 1장 13절 보여줘" → https://tsuva.com/1co/1/13
- "תפתח לי בראשית א" → https://tsuva.com/gen/1
- "search Melchizedek in Hebrew" → https://tsuva.com/s/מלכיצדק
- "what does chesed mean" → https://tsuva.com/h2617
- "Psalm 23 in the KJV numbering" → https://tsuva.com/ps/23/1?vs=gen

Full spec: https://tsuva.com/api
Contact: yerimworks.com