HTTP

REST API

REST adapter over Door43 / DCS resources. Owns KV/R2 caching, USFM/TSV parsing, and quote alignment. Consumed by the MCP worker via a service binding.

Data layer used by the MCP tools via ApiClient. Also available for apps that prefer plain HTTP.
Base /api/v1 Library @translation-helps/door43 Manifest GET /api/v1/_manifest
Public base https://translation-helps-api-v2.unfoldingword.workers.dev
GET /api/v1/languages

List tc-ready languages

Returns languages that have translationCore-ready resources in the Door43 catalog.

Adapts Door43 Catalog API /languages

/api/v1/languages Try it

Example response

200 OK
{
  "languages": [
    {
      "code": "en",
      "name": "English",
      "direction": "ltr"
    },
    {
      "code": "es-419",
      "name": "Español (Latinoamérica)",
      "direction": "ltr"
    }
  ]
}
GET /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. Pass all=1 for every available version.

Adapts Aligned Bible · Simplified Bible · Hebrew Bible · Greek New Testament

ParamInTypeDescription
reference*querystringBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
language*querystringBCP-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.
formatquerystring"plain" (stripped) or "usfm".
allquerybooleanWhen true, return every matching scripture version.
/api/v1/scripture?reference=TIT%202:12&language=en Try it

Example response

200 OK
{
  "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
    }
  }
}
  • • `role` is one of: "literal" | "simplified" | "original" (and sometimes others when all=1).
  • • With all=1, `versions` may include every catalog match (e.g. multiple gateway Bibles).
  • • `meta.cache` is one of: kv | r2 | miss | stale (when present).
  • • On failure: `{ error: string, code?: string, requestId?: string }` with 4xx/5xx.
GET /api/v1/notes

Translation Notes

TSV Translation Notes for a reference, with resolved TA article titles and optional quote alignment.

Adapts TSV Translation Notes · Translation Academy (titles)

ParamInTypeDescription
reference*querystringBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
language*querystringBCP-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.
/api/v1/notes?reference=TIT%202:12&language=en Try it

Example response

200 OK
{
  "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` / chapter `front`) when present for the book/chapter.
  • • Empty `notes: []` means none for that reference — not an error.
  • • `meta.cache` is one of: kv | r2 | miss | stale (when present).
  • • On failure: `{ error: string, code?: string, requestId?: string }` with 4xx/5xx.
GET /api/v1/word-links

Translation Word Links

TSV Translation Word Links for a reference, with TW article titles.

Adapts TSV Translation Words Links · Translation Words (titles)

ParamInTypeDescription
reference*querystringBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
language*querystringBCP-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.
/api/v1/word-links?reference=TIT%202:12&language=en Try it

Example response

200 OK
{
  "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.cache` is one of: kv | r2 | miss | stale (when present).
  • • On failure: `{ error: string, code?: string, requestId?: string }` with 4xx/5xx.
GET /api/v1/questions

Translation Questions

TSV Translation Questions for a reference.

Adapts TSV Translation Questions

ParamInTypeDescription
reference*querystringBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
language*querystringBCP-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.
/api/v1/questions?reference=TIT%202:12&language=en Try it

Example response

200 OK
{
  "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.cache` is one of: kv | r2 | miss | stale (when present).
  • • On failure: `{ error: string, code?: string, requestId?: string }` with 4xx/5xx.
GET /api/v1/words

List Translation Words articles

Catalog of TW article paths/titles for a language.

Adapts Translation Words

ParamInTypeDescription
language*querystringBCP-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.
/api/v1/words?language=en Try it

Example response

200 OK
{
  "language": "en",
  "articles": [
    {
      "path": "kt/grace",
      "title": "grace, gracious",
      "category": "kt"
    },
    {
      "path": "other/angel",
      "title": "angel, archangel",
      "category": "other"
    }
  ]
}
GET /api/v1/words/{path}

Fetch a Translation Word article

Full markdown body for a TW article path (e.g. kt/grace).

Adapts Translation Words

ParamInTypeDescription
language*querystringBCP-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.
path*pathstringArticle path, e.g. kt/grace or other/angel.
/api/v1/words/kt/grace?language=en Try it

Example response

200 OK
{
  "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.
GET /api/v1/academy

List Translation Academy articles

Catalog of TA article paths/titles for a language.

Adapts Translation Academy

ParamInTypeDescription
language*querystringBCP-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.
/api/v1/academy?language=en Try it

Example response

200 OK
{
  "language": "en",
  "articles": [
    {
      "path": "translate/figs-metaphor",
      "title": "Metaphor",
      "category": "translate"
    }
  ]
}
GET /api/v1/academy/{path}

Fetch a Translation Academy article

Full markdown body for a TA article path.

Adapts Translation Academy

ParamInTypeDescription
language*querystringBCP-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.
path*pathstringArticle path, e.g. translate/figs-metaphor.
/api/v1/academy/translate/figs-metaphor?language=en Try it

Example response

200 OK
{
  "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.
GET /api/v1/quote

Align a quote to original + gateway text

Token-level quote matching against original-language USFM and an aligned gateway (ULT/GLT).

Adapts Aligned Bible · Hebrew Bible / Greek NT

ParamInTypeDescription
reference*querystringBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
language*querystringBCP-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.
quote*querystringSource-language quote string (may use & for discontinuous spans).
occurrencequerynumber1-based occurrence of the quote in the verse.
/api/v1/quote?reference=TIT%202:12&language=en&quote=%CE%B3%CE%AC%CF%81&occurrence=1 Try it

Example response

200 OK
{
  "reference": "TIT 2:12",
  "language": "en",
  "quote": "γάρ",
  "occurrence": 1,
  "match": {
    "original": "γάρ",
    "aligned": "for",
    "ok": true
  }
}
  • • When the quote cannot be matched, `original`/`gateway` are empty and `note` explains why.
  • • `language` may differ from `requestedLanguage` when a variant is resolved (e.g. es → es-419).
GET /api/v1/search

Lexical search of TA/TW articles

Ranked keyword search across Translation Academy and Translation Words.

Adapts Translation Academy · Translation Words

ParamInTypeDescription
q*querystringSearch query.
language*querystringBCP-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.
typequerystringOptional filter: "ta" or "tw".
/api/v1/search?q=metaphor&language=en Try it

Example response

200 OK
{
  "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.
GET /api/v1/resources

Resource availability for a language/reference

Catalog-only summary of which scripture and helps resources exist (no ZIP downloads).

Adapts Door43 Catalog API

ParamInTypeDescription
reference*querystringBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
language*querystringBCP-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.
/api/v1/resources?reference=TIT%202:12&language=en Try it

Example response

200 OK
{
  "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_…"
}
  • • `language` may differ from `requestedLanguage` when a variant is resolved (e.g. es → es-419).
  • • Optional `book` / `reference` filters book-scoped resources missing that book.
  • • Entries may include `books` / `bookCount` / `warning` for partial coverage; see `coverage.note`.
GET /api/v1/prefetch

Warm caches for a passage

Returns 202 and warms notes/word-links/questions in the background via waitUntil. Also accepts POST.

Adapts Translation Notes · Word Links · Questions

ParamInTypeDescription
reference*querystringBible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".
language*querystringBCP-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.
/api/v1/prefetch?reference=TIT%202:12&language=en Try it

Example response

200 OK
{
  "status": "accepted",
  "reference": "TIT 2:12",
  "language": "en"
}
  • • HTTP 202 Accepted — body confirms the warm job was queued.
GET /api/v1/obs

Open Bible Stories story text

OBS story frames for a story:frame reference.

Adapts Open Bible Stories

ParamInTypeDescription
reference*querystringOBS 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.
language*querystringBCP-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.
/api/v1/obs?reference=3%3A1-3&language=spa Try it

Example response

200 OK
{
  "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-level `frame` or `text`.
  • • Single-frame requests return one element in `frames`; ranges and whole-story requests return multiple.
  • • `language` may differ from the requested code after variant resolution (e.g. spa → es → es-419).
  • • `meta.cache` is one of: kv | r2 | miss | stale (when present).
  • • On failure: `{ error: string, code?: string, requestId?: string }` with 4xx/5xx.
GET /api/v1/obs-notes

OBS translation notes

Translation notes for an OBS story:frame.

Adapts OBS Translation Notes

ParamInTypeDescription
reference*querystringOBS 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.
language*querystringBCP-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.
/api/v1/obs-notes?reference=1:1&language=en Try it

Example response

200 OK
{
  "reference": "1:1",
  "language": "en",
  "notes": [
    {
      "id": "obs-n1",
      "reference": "1:1",
      "quote": "God",
      "note": "This refers to the one true God…"
    }
  ]
}
GET /api/v1/obs-questions

OBS translation questions

Translation questions for an OBS story:frame.

Adapts OBS Translation Questions

ParamInTypeDescription
reference*querystringOBS 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.
language*querystringBCP-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.
/api/v1/obs-questions?reference=1:1&language=en Try it

Example response

200 OK
{
  "reference": "1:1",
  "language": "en",
  "questions": [
    {
      "id": "obs-q1",
      "reference": "1:1",
      "question": "Who made everything?",
      "response": "God"
    }
  ]
}

Fetch the live manifest

terminal
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/_manifest"