Core

The JavaScript SDK (@youversion/platform-core) provides typed API clients for fetching Bible data in any JavaScript environment. See the source on GitHub.

Installation

Install the package with your preferred package manager:

Configuration

Create an API client with your App Key:

Code
import { ApiClient, BibleClient, LanguagesClient } from "@youversion/platform-core";

const apiClient = new ApiClient({
  appKey: "YOUR_APP_KEY",
});

const bibleClient = new BibleClient(apiClient);
const languagesClient = new LanguagesClient(apiClient);

Types
type ApiClientOptions = {
  /**
   * Your App Key for API authentication
   * Get from https://platform.youversion.com/
   */
  appKey: string;

  /**
   * Base URL for the API
   * @default "https://api.youversion.com"
   */
  baseUrl?: string;

  /**
   * Request timeout in milliseconds
   * @default 10_000
   */
  timeout?: number;
};

BibleClient API

The BibleClient provides methods for fetching Bible versions, books, chapters, verses, and passages.

Version Methods

getVersions(language_ranges, license_id?)

Fetch available Bible versions filtered by language.

Code
// Get all English versions
const englishVersions = await bibleClient.getVersions("en*");

// Get multiple languages
const multiLangVersions = await bibleClient.getVersions("en*,es*,fr*");

// Filter by license
const licenseVersions = await bibleClient.getVersions("en*", 123);

Parameters:

• language_ranges (string): Comma-separated language codes or ranges (e.g., "en*", "es-ES")
• license_id (string | number, optional): License ID to filter versions

Response:

Code
{
  data: [
    {
      id: 3034,
      abbreviation: "BSB",
      localized_abbreviation: "BSB",
      title: "Berean Standard Bible",
      localized_title: "Berean Standard Bible",
      language_tag: "en",
      copyright: "...",
      books: ["GEN", "EXO", ...],
      publisher_url: "https://...",
      youversion_deep_link: "https://www.bible.com/versions/3034"
    }
  ]
}

getVersion(id)

Fetch a specific Bible version by ID.

Code
const bibleVersion = await bibleClient.getVersion(3034);
console.log(bibleVersion.title); // "Berean Standard Bible"

Parameters:

• id (number): Bible version ID

Code
const versions = await bibleClient.getVersions("en*");
const validIds = versions.data.map((v) => v.id);
console.log("Valid version IDs:", validIds);

Book Methods

getBooks(versionId)

Fetch all books for a specific Bible version.

Code
const books = await bibleClient.getBooks(3034);

Parameters:

• versionId (number): Bible version ID

Response:

Code
{
  data: [
    {
      id: "GEN",
      title: "Genesis",
      full_title: "Genesis",
      abbreviation: "Gen.",
      canon: "old_testament",
      intro: { id: "INTRO", passage_id: "GEN.INTRO", title: "Intro" },
      chapters: [
        { id: "1", passage_id: "GEN.1", title: "1", verses: [ { id: "1", passage_id: "GEN.1.1", title: "1" }, ... ] },
        { id: "2", passage_id: "GEN.2", title: "2", verses: [...] },
        ...
      ]
    }
  ]
}

getBook(versionId, book)

Fetch a specific book by its USFM identifier.

Code
const genesis = await bibleClient.getBook(3034, "GEN");
console.log(genesis.title); // "Genesis"
console.log(genesis.chapters.length); // 50

Parameters:

• versionId (number): Bible version ID
• book (string): 3-character USFM book code (e.g., "GEN", "MAT", "JHN")

Chapter Methods

getChapters(versionId, book)

Fetch all chapters for a specific book.

Code
const chapters = await bibleClient.getChapters(3034, "GEN");
console.log(chapters.data.length); // 50

Parameters:

• versionId (number): Bible version ID
• book (string): 3-character USFM book code

getChapter(versionId, book, chapter)

Fetch a specific chapter.

Code
const genesis1 = await bibleClient.getChapter(3034, "GEN", 1);
console.log(genesis1.title); // "1"

Parameters:

• versionId (number): Bible version ID
• book (string): 3-character USFM book code
• chapter (number): Chapter number

Verse Methods

getVerses(versionId, book, chapter)

Fetch all verses for a specific chapter.

Code
const verses = await bibleClient.getVerses(3034, "GEN", 1);
console.log(verses.data.length); // 31

Parameters:

• versionId (number): Bible version ID
• book (string): 3-character USFM book code
• chapter (number): Chapter number

Response:

Code
{
  data: [
    { id: "1", passage_id: "GEN.1.1", title: "1" },
    { id: "2", passage_id: "GEN.1.2", title: "2" },
  ];
}

getVerse(versionId, book, chapter, verse)

Fetch a specific verse.

Code
const verse = await bibleClient.getVerse(3034, "GEN", 1, 1);
console.log(verse.passage_id); // "GEN.1.1"

Parameters:

• versionId (number): Bible version ID
• book (string): 3-character USFM book code
• chapter (number): Chapter number
• verse (number): Verse number

Passage Methods

getPassageDisplay(options)

Fetch a display-ready passage with transformed HTML, current attribution, stylesheet descriptors, and scoped container attributes. This is the recommended method when you will render styled Bible HTML.

Code
const display = await bibleClient.getPassageDisplay({
  versionId: 3034,
  passageId: "JHN.3.16",
  includeHeadings: true,
  includeNotes: true,
});

console.log(display.html);
console.log(display.attribution.text);
console.log(display.stylesheets);

The result is declarative. The SDK does not modify the DOM, inject stylesheets, or cache attribution. See Display Bible HTML for browser, server-rendered, and direct REST examples.

getPassage(versionId, usfm, format?, include_headings?, include_notes?, transform?)

Fetch a passage with formatted content. This is the recommended method for retrieving verse text to preserve proper formatting of paragraphs and tables.

Code
// Single verse (HTML + auto-transform by default)
const verse = await bibleClient.getPassage(3034, "JHN.3.16");
console.log(verse.content); // "<div class=\"p\" data-yv-transformed=\"\">..."

// Verse range (HTML by default)
const passage = await bibleClient.getPassage(3034, "GEN.1.1-5");

// Entire chapter
const chapter = await bibleClient.getPassage(3034, "GEN.1");

// With formatting options
const formatted = await bibleClient.getPassage(
  3034,
  "JHN.3.16",
  "html",
  true,
  true
);

Parameters:

• versionId (number): Bible version ID
• usfm (string): USFM reference format (e.g., "JHN.3.16", "GEN.1.1-5", "MAT.1")
• format (string, optional): "html" or "text" (default: "html")
• include_headings (boolean, optional): Include section headings in output
• include_notes (boolean, optional): Include footnotes/endnotes in output
• transform (boolean, optional, default true): When format is "html", sanitize and transform the HTML automatically. Pass false for raw API HTML.

Choosing a Format

• "html" (default) — YouVersion CSS classes for verses, paragraphs, headings, poetry, and tables. Auto-transformed unless you pass transform: false. To style it, see Display Bible HTML.
• "text" — Plain text with no markup.

Automatic HTML transformation

HTML from getPassage is transformed by default. The SDK uses DOMParser in the browser and jsdom on the server. Pass false as the sixth argument for raw API HTML, or when you do not have jsdom. usePassage forwards the same transform option. To show styled HTML, see Display Bible HTML.

Response:

format: text
{
  "id": "JHN.3.16",
  "content": "For God so loved the world that He gave His one and only Son, that everyone who believes in Him shall not perish but have eternal life.",
  "reference": "John 3:16"
}

format: html
{
  "id": "JHN.3.16",
  "content": "<div class=\"p\" data-yv-transformed=\"\"><span class=\"yv-v\" v=\"16\"><span class=\"yv-vlbl\">16&nbsp;</span>For God so loved the world...</span></div>",
  "reference": "John 3:16"
}

Index & VOTD Methods

getIndex(versionId)

Fetch the complete indexing structure for a Bible version.

Code
const index = await bibleClient.getIndex(3034);
console.log(index.books[0].chapters.length);

Parameters:

• versionId (number): Bible version ID

Response:

Code
50;

getAllVOTDs()

Fetch the Verse of the Day for the entire year.

Code
const allVOTDs = await bibleClient.getAllVOTDs();
console.log(allVOTDs.data[0].day); // 1 (January 1st)
console.log(allVOTDs.data[0].passage_id); // "JHN.3.16"

getVOTD(day)

Fetch the Verse of the Day for a specific day of the year.

Code
const votd = await bibleClient.getVOTD(1); // Day 1 (January 1st)
console.log(votd.passage_id); // "JHN.3.16"

Parameters:

• day (number): Day of the year (1-366)

LanguagesClient API

The LanguagesClient provides methods for accessing language information.

Code
import { LanguagesClient } from "@youversion/platform-core";

const languagesClient = new LanguagesClient(apiClient);

Language Methods

getLanguages(options)

Fetch available languages supported in the platform.

Code
// Get languages available in United States
const usLanguages = await languagesClient.getLanguages({
  country: "US",
});

// Get with pagination
const page2 = await languagesClient.getLanguages({
  country: "US",
  page_size: 10,
  page_token: "next_page_token_from_previous_response",
});

Parameters:

• options (object):
  • country (string, required): ISO 3166-1 alpha-2 country code (e.g., "US", "BR", "MX")
  • page_size (number, optional): Results per page
  • page_token (string, optional): Pagination token from previous response

Response:

Code
{
  data: [
    {
      id: "en",
      language: "en",
      script: "Latn",
      script_name: "Latin",
      display_names: { en: "English" },
      countries: ["US"],
      text_direction: "ltr",
      default_bible_id: 3034,
    },
  ];
}

getLanguage(languageId)

Fetch details about a specific language.

Code
const english = await languagesClient.getLanguage("en");
console.log(english.display_names?.en); // "English"

// With script specification
const serbianCyrillic = await languagesClient.getLanguage("sr-Cyrl");

Parameters:

• languageId (string): BCP 47 language code (e.g., "en", "es", "sr-Cyrl")

Code
await languagesClient.getLanguage("en"); // ✓ English
await languagesClient.getLanguage("es"); // ✓ Spanish
await languagesClient.getLanguage("sr-Cyrl"); // ✓ Serbian Cyrillic
await languagesClient.getLanguage("zh-Hans"); // ✓ Chinese Simplified

Fonts

Load Untitled Serif from the Fonts API stylesheet. Put this URL on a <link rel="stylesheet">. Do not host @font-face files yourself.

Code
https://api.youversion.com/v1/fonts/1/stylesheet?app_key=YOUR_APP_KEY

That is GET /v1/fonts/{font_id}/stylesheet. See the Fonts API. For Bible CSS, passage HTML, and attribution, see Display Bible HTML.