JavaScript SDK API reference

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");

// Prefer English, then Spanish, then French
const preferredVersions = await bibleClient.getVersions(["en", "es", "fr"]);

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

Parameters:

• language_ranges (string or string array): A language range or ordered preferences (e.g., "en", ["en", "es"]). Returns versions from the first range with available Bibles. See Language ranges.
• 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

SearchClient API

SearchClient searches verses and topics and retrieves suggested or trending queries. See the search guide for pagination and interface workflows.

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

const search = new SearchClient(apiClient);

Unified search

searchUnified(query, versionId, languageRanges, options?)

Retrieve top results across content kinds, such as verse references and related topics, in one request. Returns Promise<SearchUnifiedResponse> with no pagination.

Parameters:

• query (string): Search text, 1 through 100 grapheme clusters (user-perceived characters).
• versionId (number): Integer identifying a Bible version your app can access. Determines the language of verse results.
• languageRanges (string or string array): Nonempty language preferences for topic results; "*" matches all languages. See Language ranges.
• options (SearchUnifiedOptions, optional):
  • userIntent (string, optional): "unknown", "reference", "text", or "topical". Leave unset unless you know the user's intent.
  • fields (SearchUnifiedField[], optional): Nonempty selection of result kinds: "verses", "topics", and "images". Omit to request all available kinds. Image selection requires backend support.

Response:

• verses: Array of passage references, with the same shape as searchVerses hits.
• topics: Array of topics, with the same shape as searchTopics hits.
• images: Array of { id: string; passageId: string } image hits, not image bytes.
• userIntent: Optional string describing the intent returned by the service.
• didYouMean: Array of alternative spellings.
• searchInsteadFor: Corrected query the results were returned for, or null.

There is no nextPageToken or totalSize. To paginate verse results, start a separate searchVerses request. To fetch passage text, use BibleClient.getPassage.

The standalone searchUnified export takes an ApiClient as its first argument, followed by the same arguments as this method.

Verse search

searchVerses(query, versionId, options?)

Search one Bible version. Returns Promise<SearchVersesResponse>.

Parameters:

• query (string): Search text, trimmed to remove surrounding whitespace. Accepts 1 through 100 grapheme clusters, or user-perceived characters. The SDK rejects longer input rather than truncating it. The same limit applies to searchTopics.
• versionId (number): Integer identifying a Bible version your app can access.
• options (SearchVersesOptions, optional):
  • userIntent (string, optional): "unknown", "reference", "text", or "topical". Leave unset unless you know the user's intent.
  • pageSize (number, optional): Integer from 1 through 99. If omitted, the API determines the page size.
  • pageToken (string, optional): Opaque nextPageToken from a previous response.

Response:

• verses: Array of { id: string } hits. Each id is a USFM passage identifier, not passage text. Malformed references are removed.
• nextPageToken: Continuation token, or null or absent when there are no more pages.
• userIntent: Optional string describing the intent returned by the service.
• didYouMean: Array of alternative spellings.
• searchInsteadFor: Query string supplied by the API, or null when omitted.

Topic search

searchTopics(query, languageRanges)

Find related topics without choosing a Bible version. Returns Promise<SearchTopicsResponse> with no pagination.

Parameters:

• query (string): Search text with the same limit as searchVerses.
• languageRanges (string or string array): Nonempty language range or ordered preferences, such as "en", "*" for all languages, or ["en-US", "en"]. See Language ranges.

The SDK trims language ranges, converts them to lowercase, and replaces underscores with hyphens. This normalization also applies to suggested and trending query requests; it does not make an unsupported language available.

Response:

• topics: Array of topics with text (string), subtopics (string array), and optional id (integer or null).
• totalSize: Number of topics in this response.
• didYouMean: Array of alternative spellings.
• searchInsteadFor: Query string supplied by the API, or null when omitted.

Suggested queries

getSuggestedQueries(query, languageRanges)

Retrieve suggestions for partial input. Returns Promise<SearchQueries>.

Parameters:

• query (string): Partial input, nonempty after trimming.
• languageRanges (string or string array): Language preferences, as for searchTopics.

Response: An object with a queries array. Each entry has text (string) and optional source (string). Treat source as an API-provided label, not a fixed set of values. A no-content response becomes { queries: [] }.

Trending queries

getTrendingQueries(languageRanges)

Retrieve popular queries without partial input. Accepts the same languageRanges as searchTopics and returns Promise<SearchQueries> with the same shape as getSuggestedQueries.

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.

Utilities

Parse a passage reference

parseUsfmReference(usfm) converts a USFM passage identifier into { book, chapter, verses }.

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

const reference = parseUsfmReference("JHN.3.16-18");
// { book: "JHN", chapter: "3", verses: [16, 17, 18] }

book and chapter are strings. verses is an ascending array of numbers, empty for a chapter-only reference such as PSA.23. Invalid input returns null, including non-positive or unsafe numbers, reversed ranges, and spans longer than 250 verses. The helper checks structure, not whether the book, chapter, or verses exist in a Bible version.