Docs: REST API

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

GET

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

Open in your browser

Example response
{
  "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; 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

  • reference string · query required

    Bible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".

  • language string · query required

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

  • format string · query optional default plain

    "plain" (stripped) or "usfm".

  • all boolean · query optional default false

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

Open in your browser

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
    }
  }
}
  • role is one of: "literal" | "simplified" | "original", and "other" for a version standing in for one that lacks the book or returned by all=1.
  • versionsNote is 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, 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.

Reads from: TSV Translation Notes · Translation Academy (titles)

Parameters

  • reference string · query required

    Bible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".

  • language string · query required

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

Open in your browser

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

Translation Questions

TSV Translation Questions for a reference.

Reads from: TSV Translation Questions

Parameters

  • reference string · query required

    Bible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".

  • language string · query required

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

Open in your browser

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

Reads from: Translation Words

Parameters

  • language string · query required

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

Open in your browser

Example response
{
  "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).

Reads from: Translation Words

Parameters

  • language string · query required

    BCP-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 string · path required

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

Open in your browser

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

/api/v1/academy

List Translation Academy articles

Catalog of TA article paths/titles for a language.

Reads from: Translation Academy

Parameters

  • language string · query required

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

Open in your browser

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

Reads from: Translation Academy

Parameters

  • language string · query required

    BCP-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 string · path required

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

Open in your browser

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

Reads from: Aligned Bible · Hebrew Bible / Greek NT

Parameters

  • reference string · query required

    Bible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".

  • language string · query required

    BCP-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 string · query required

    Source-language quote string (may use & for discontinuous spans).

  • occurrence number · query optional default 1

    1-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&quote=%CE%B3%CE%AC%CF%81&occurrence=1"

Open in your browser

Example response
{
  "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/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

  • reference string · query required

    Bible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".

  • language string · query required

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

Open in your browser

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_…"
}
  • 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.

Reads from: Translation Notes · Word Links · Questions

Parameters

  • reference string · query required

    Bible reference, e.g. "TIT 2:12", "JHN 3:16", "MAT 5:3-12".

  • language string · query required

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

Open in your browser

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

Reads from: Open Bible Stories

Parameters

  • reference string · query required

    OBS 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 string · query required

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

Open in your browser

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

Reads from: OBS Translation Notes

Parameters

  • reference string · query required

    OBS 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 string · query required

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

Open in your browser

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…"
    }
  ]
}
GET

/api/v1/obs-questions

OBS translation questions

Translation questions for an OBS story:frame.

Reads from: OBS Translation Questions

Parameters

  • reference string · query required

    OBS 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 string · query required

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

Open in your browser

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

/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

  • reference string · query required

    OBS 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 string · query required

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

Open in your browser

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…"
    }
  ]
}
GET

/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

  • reference string · query required

    OBS 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 string · query required

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

Open in your browser

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