REST API
The same data as the MCP tools, over plain HTTP: GET requests that answer in JSON, with no key or account. The MCP tools call this API underneath, so the two always agree. Use it from an app, a script, or anything that does not speak MCP.
https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1 The list of endpoints below is also served by the API itself, at GET /api/v1/_manifest. Answers carry open CORS headers, so a browser page can call them. The same rate limit applies.
Errors
A failed request answers with a 4xx or 5xx status and this body. retryable tells you whether
trying again can help.
{
"error": {
"code": "RATE_LIMITED",
"message": "…",
"retryable": true
}
}Endpoints
- /languages · List tc-ready languages
- /scripture · Scripture text for a reference
- /notes · Translation Notes
- /word-links · Translation Word Links
- /questions · Translation Questions
- /words · List Translation Words articles
- /words/{path} · Fetch a Translation Word article
- /academy · List Translation Academy articles
- /academy/{path} · Fetch a Translation Academy article
- /quote · Align a quote to original + gateway text
- /search · Lexical search of TA/TW articles
- /resources · Resource availability for a language/reference
- /prefetch · Warm caches for a passage
- /obs · Open Bible Stories story text
- /obs-notes · OBS translation notes
- /obs-word-links · OBS translation word links
- /obs-questions · OBS translation questions
- /obs-study-notes · OBS study notes
- /obs-study-questions · OBS study questions
/api/v1/languages
List tc-ready languages
Returns languages that have translationCore-ready resources in the Door43 catalog.
Reads from: Door43 Catalog API /languages
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/languages"Example response
{
"languages": [
{
"code": "en",
"name": "English",
"direction": "ltr"
},
{
"code": "es-419",
"name": "Español (Latinoamérica)",
"direction": "ltr"
}
]
} /api/v1/scripture
Scripture text for a reference
Returns scripture versions for a reference. By default one literal, one simplified, and the original language text; when the literal or the simplified version does not have the book, or the book's id line says it is in another language, or the text is written in another script, another version of the language stands in and versionsNote says so. Pass all=1 for every available version.
Reads from: Aligned Bible · Simplified Bible · Hebrew Bible · Greek New Testament
Parameters
referencestring · query requiredBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
formatstring · query optional defaultplain"plain" (stripped) or "usfm".
allboolean · query optional defaultfalseWhen true, return every matching scripture version.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/scripture?reference=TIT%202:12&language=en"Example response
{
"reference": "TIT 2:12",
"language": "en",
"book": "TIT",
"chapter": "2",
"verse": "12",
"format": "plain",
"versions": [
{
"resourceType": "ult",
"role": "literal",
"text": "training us so that we can reject ungodliness…",
"source": "https://git.door43.org/…"
},
{
"resourceType": "ust",
"role": "simplified",
"text": "By means of this free gift, God trains us…",
"source": "https://git.door43.org/…"
},
{
"resourceType": "ugnt",
"role": "original",
"text": "παιδεύουσα ἡμᾶς…",
"source": "https://git.door43.org/…"
}
],
"meta": {
"cache": "kv",
"timings": {
"totalMs": 42
}
}
} roleis one of: "literal" | "simplified" | "original", and "other" for a version standing in for one that lacks the book or returned by all=1.versionsNoteis present only when a stand-in was used, a book was left out because its id line names another language or its text is in another script, or none could be found.- With all=1,
versionsmay include every catalog match (e.g. multiple gateway Bibles). meta.cacheis one of: kv | r2 | miss | stale (when present).- On failure:
{ error: string, code?: string, requestId?: string }with 4xx/5xx.
/api/v1/notes
Translation Notes
TSV Translation Notes for a reference, with resolved TA article titles and optional quote alignment.
Reads from: TSV Translation Notes · Translation Academy (titles)
Parameters
referencestring · query requiredBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/notes?reference=TIT%202:12&language=en"Example response
{
"reference": "TIT 2:12",
"language": "en",
"notes": [
{
"book": "TIT",
"chapter": "2",
"verse": "12",
"id": "abc123",
"supportReference": "rc://*/ta/man/translate/figs-personification",
"supportReferenceTitle": "Personification",
"quote": "παιδεύουσα ἡμᾶς",
"occurrence": "1",
"note": "Here, **grace** is spoken of as if it were a person who trains us…",
"gatewayQuote": {
"original": "παιδεύουσα ἡμᾶς",
"aligned": "training us"
}
}
],
"meta": {
"cache": "kv"
}
} - Includes intro notes (verse
intro/ chapterfront) when present for the book/chapter. - Empty
notes: []means none for that reference — not an error. meta.cacheis one of: kv | r2 | miss | stale (when present).- On failure:
{ error: string, code?: string, requestId?: string }with 4xx/5xx.
/api/v1/word-links
Translation Word Links
TSV Translation Word Links for a reference, with TW article titles.
Reads from: TSV Translation Words Links · Translation Words (titles)
Parameters
referencestring · query requiredBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/word-links?reference=TIT%202:12&language=en"Example response
{
"reference": "TIT 2:12",
"language": "en",
"wordLinks": [
{
"book": "TIT",
"chapter": "2",
"verse": "12",
"id": "def456",
"twLink": "rc://*/tw/dict/bible/kt/righteous",
"twTitle": "righteous, righteousness",
"origWords": "δικαίως",
"occurrence": "1",
"gatewayQuote": {
"original": "δικαίως",
"aligned": "righteous"
}
}
],
"meta": {
"cache": "kv"
}
} - Empty
wordLinks: []when none exist. meta.cacheis one of: kv | r2 | miss | stale (when present).- On failure:
{ error: string, code?: string, requestId?: string }with 4xx/5xx.
/api/v1/questions
Translation Questions
TSV Translation Questions for a reference.
Reads from: TSV Translation Questions
Parameters
referencestring · query requiredBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/questions?reference=TIT%202:12&language=en"Example response
{
"reference": "TIT 2:12",
"language": "en",
"questions": [
{
"id": "tq1",
"reference": "2:12",
"question": "What does God's grace train us to do?",
"response": "To reject ungodliness and worldly passions…"
}
],
"meta": {
"cache": "kv"
}
} - Empty
questions: []when none exist. meta.cacheis one of: kv | r2 | miss | stale (when present).- On failure:
{ error: string, code?: string, requestId?: string }with 4xx/5xx.
/api/v1/words
List Translation Words articles
Catalog of TW article paths/titles for a language.
Reads from: Translation Words
Parameters
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/words?language=en"Example response
{
"language": "en",
"articles": [
{
"path": "kt/grace",
"title": "grace, gracious",
"category": "kt"
},
{
"path": "other/angel",
"title": "angel, archangel",
"category": "other"
}
]
} /api/v1/words/{path}
Fetch a Translation Word article
Full markdown body for a TW article path (e.g. kt/grace).
Reads from: Translation Words
Parameters
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
pathstring · path requiredArticle path, e.g. kt/grace or other/angel.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/words/kt/grace?language=en"Example response
{
"language": "en",
"path": "kt/grace",
"title": "grace, gracious",
"article": "# grace, gracious\n\n### Definition:\nThe word **grace**…\n"
} - 404 when the path does not exist for that language.
/api/v1/academy
List Translation Academy articles
Catalog of TA article paths/titles for a language.
Reads from: Translation Academy
Parameters
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/academy?language=en"Example response
{
"language": "en",
"articles": [
{
"path": "translate/figs-metaphor",
"title": "Metaphor",
"category": "translate"
}
]
} /api/v1/academy/{path}
Fetch a Translation Academy article
Full markdown body for a TA article path.
Reads from: Translation Academy
Parameters
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
pathstring · path requiredArticle path, e.g. translate/figs-metaphor.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/academy/translate/figs-metaphor?language=en"Example response
{
"language": "en",
"path": "translate/figs-metaphor",
"title": "Metaphor",
"article": "# Metaphor\n\n### Description\nA metaphor…\n"
} - 404 when the path does not exist for that language.
/api/v1/quote
Align a quote to original + gateway text
Token-level quote matching against original-language USFM and an aligned gateway (ULT/GLT).
Reads from: Aligned Bible · Hebrew Bible / Greek NT
Parameters
referencestring · query requiredBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
quotestring · query requiredSource-language quote string (may use & for discontinuous spans).
occurrencenumber · query optional default11-based occurrence of the quote in the verse.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/quote?reference=TIT%202:12&language=en"e=%CE%B3%CE%AC%CF%81&occurrence=1"Example response
{
"reference": "TIT 2:12",
"language": "en",
"quote": "γάρ",
"occurrence": 1,
"match": {
"original": "γάρ",
"aligned": "for",
"ok": true
}
} - When the quote cannot be matched,
original/gatewayare empty andnoteexplains why. languagemay differ fromrequestedLanguagewhen a variant is resolved (e.g. es → es-419).
/api/v1/search
Lexical search of TA/TW articles
Ranked keyword search across Translation Academy and Translation Words.
Reads from: Translation Academy · Translation Words
Parameters
qstring · query requiredSearch query.
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
typestring · query optionalOptional filter: "ta" or "tw".
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/search?q=metaphor&language=en"Example response
{
"query": "metaphor",
"language": "en",
"results": [
{
"type": "ta",
"path": "translate/figs-metaphor",
"title": "Metaphor",
"snippet": "A metaphor is a figure of speech…",
"score": 12.4
}
]
} - Empty
results: []when nothing matches.
/api/v1/resources
Resource availability for a language/reference
Catalog-only summary of which scripture and helps resources exist (no ZIP downloads).
Reads from: Door43 Catalog API
Parameters
referencestring · query requiredBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/resources?reference=TIT%202:12&language=en"Example response
{
"language": "en",
"requestedLanguage": "en",
"available": [
{
"type": "scripture",
"subject": "Aligned Bible",
"abbreviation": "ult",
"role": "literal"
},
{
"type": "notes",
"subject": "TSV Translation Notes",
"abbreviation": "tn",
"role": "notes"
}
],
"requestId": "req_…"
} languagemay differ fromrequestedLanguagewhen a variant is resolved (e.g. es → es-419).- Optional
book/referencefilters book-scoped resources missing that book. - Entries may include
books/bookCount/warningfor partial coverage; seecoverage.note.
/api/v1/prefetch
Warm caches for a passage
Returns 202 and warms notes/word-links/questions in the background via waitUntil. Also accepts POST.
Reads from: Translation Notes · Word Links · Questions
Parameters
referencestring · query requiredBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/prefetch?reference=TIT%202:12&language=en"Example response
{
"status": "accepted",
"reference": "TIT 2:12",
"language": "en"
} - HTTP 202 Accepted — body confirms the warm job was queued.
/api/v1/obs
Open Bible Stories story text
OBS story frames for a story:frame reference.
Reads from: Open Bible Stories
Parameters
referencestring · query requiredOBS reference — "1:1" (single frame), "3:1-3" (frames 1–3 inclusive), "3" (whole story), "1:0" (story title), "front" (front matter). Optional "OBS" prefix ("OBS 3:1-3"). Story numbers 1–50; frames are 1-indexed. Inverted ranges (e.g. "3:5-2") are invalid.
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/obs?reference=3%3A1-3&language=spa"Example response
{
"reference": "3:1-3",
"language": "es-419",
"story": 3,
"title": "Noah and the Great Flood",
"frames": [
{
"index": 1,
"imageUrl": "https://cdn.door43.org/obs/en/obs/01/01.jpg",
"text": "A long time ago, the world had become very wicked…"
},
{
"index": 2,
"imageUrl": "https://cdn.door43.org/obs/en/obs/01/02.jpg",
"text": "God saw that the people on earth were very wicked…"
},
{
"index": 3,
"imageUrl": "https://cdn.door43.org/obs/en/obs/01/03.jpg",
"text": "So God decided to send a great flood…"
}
],
"attribution": "© unfoldingWord"
} - Frame text lives in
frames[](index,imageUrl,text); there is no top-levelframeortext. - Single-frame requests return one element in
frames; ranges and whole-story requests return multiple. languagemay differ from the requested code after variant resolution (e.g. spa → es → es-419).meta.cacheis one of: kv | r2 | miss | stale (when present).- On failure:
{ error: string, code?: string, requestId?: string }with 4xx/5xx.
/api/v1/obs-notes
OBS translation notes
Translation notes for an OBS story:frame.
Reads from: OBS Translation Notes
Parameters
referencestring · query requiredOBS reference — "1:1" (single frame), "3:1-3" (frames 1–3 inclusive), "3" (whole story), "1:0" (story title), "front" (front matter). Optional "OBS" prefix ("OBS 3:1-3"). Story numbers 1–50; frames are 1-indexed. Inverted ranges (e.g. "3:5-2") are invalid.
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/obs-notes?reference=1:1&language=en"Example response
{
"reference": "1:1",
"language": "en",
"notes": [
{
"id": "obs-n1",
"reference": "1:1",
"quote": "God",
"supportReference": "rc://*/ta/man/translate/figs-idiom",
"supportReferenceTitle": "Idiom",
"occurrence": "1",
"note": "This refers to the one true God…"
}
]
} /api/v1/obs-word-links
OBS translation word links
Key terms for an OBS story:frame. Each row carries twArticle.{path,category,title} and no article body.
Reads from: OBS Translation Words Links
Parameters
referencestring · query requiredOBS reference — "1:1" (single frame), "3:1-3" (frames 1–3 inclusive), "3" (whole story), "1:0" (story title), "front" (front matter). Optional "OBS" prefix ("OBS 3:1-3"). Story numbers 1–50; frames are 1-indexed. Inverted ranges (e.g. "3:5-2") are invalid.
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/obs-word-links?reference=1:3&language=en"Example response
{
"reference": "OBS 1:3",
"language": "en",
"words": [
{
"reference": "1:3",
"id": "b1",
"tags": "keyterm",
"origWords": "God",
"occurrence": "1",
"twArticle": {
"path": "bible/kt/god",
"category": "kt",
"title": "God"
}
}
]
} /api/v1/obs-questions
OBS translation questions
Translation questions for an OBS story:frame.
Reads from: OBS Translation Questions
Parameters
referencestring · query requiredOBS reference — "1:1" (single frame), "3:1-3" (frames 1–3 inclusive), "3" (whole story), "1:0" (story title), "front" (front matter). Optional "OBS" prefix ("OBS 3:1-3"). Story numbers 1–50; frames are 1-indexed. Inverted ranges (e.g. "3:5-2") are invalid.
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/obs-questions?reference=1:1&language=en"Example response
{
"reference": "1:1",
"language": "en",
"questions": [
{
"id": "obs-q1",
"reference": "1:1",
"question": "Who made everything?",
"response": "God"
}
]
} /api/v1/obs-study-notes
OBS study notes
Study notes for an OBS story:frame (reader/discussion background; not translator TN).
Reads from: OBS Study Notes
Parameters
referencestring · query requiredOBS reference — "1:1" (single frame), "3:1-3" (frames 1–3 inclusive), "3" (whole story), "1:0" (story title), "front" (front matter). Optional "OBS" prefix ("OBS 3:1-3"). Story numbers 1–50; frames are 1-indexed. Inverted ranges (e.g. "3:5-2") are invalid.
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/obs-study-notes?reference=1:1&language=en"Example response
{
"reference": "OBS 1:1",
"language": "en",
"notes": [
{
"id": "prf0",
"reference": "1:1",
"quote": "God",
"note": "The term God refers to the eternal being…"
}
]
} /api/v1/obs-study-questions
OBS study questions
Study/discussion questions for an OBS story:frame. Rows may cover frame ranges (e.g. 1:1-8); a request for 1:3 returns questions whose range covers that frame.
Reads from: OBS Study Questions
Parameters
referencestring · query requiredOBS reference — "1:1" (single frame), "3:1-3" (frames 1–3 inclusive), "3" (whole story), "1:0" (story title), "front" (front matter). Optional "OBS" prefix ("OBS 3:1-3"). Story numbers 1–50; frames are 1-indexed. Inverted ranges (e.g. "3:5-2") are invalid.
languagestring · query requiredBCP-47 language code, e.g. "en", "es", "es-419". ISO 639-2/639-3 bibliographic codes are also accepted (e.g. "spa" for Spanish → catalog "es"; may further resolve to "es-419"). Prefer BCP-47 when known; run /languages for codes.
Example request
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/obs-study-questions?reference=1:3&language=en"Example response
{
"reference": "OBS 1:3",
"language": "en",
"questions": [
{
"id": "toi2",
"reference": "1:1-8",
"question": "What did God do in order to create everything except the first people?",
"response": "God only spoke, and the universe and everything in it appeared."
}
]
}