YouVersion PlatformYouVersion Platform
PlatformContent LibraryDev Docs
CommunityPartnersSupport

YouVersion Platform

Build applications and integrate with the world's most popular Bible platform.

Platform Products

  • Platform Portal
  • Developer Documentation
  • App Management

Resources

  • Support
  • Press inquiries

Legal

  • Privacy Policy
  • Terms of Use

© 2026 YouVersion. All rights reserved.

  • Overview
  • API Reference
  • SDKs
  • Changelog
<  Back to Platform
SDK Introduction
Swift SDK
Kotlin SDK
JavaScript SDK
    Quick StartJavaScript SDK API referenceTypeScript Types
    Guides
React SDK
React Native (Expo) SDK
JavaScript SDK

JavaScript SDK API reference

The JavaScript SDK (@youversion/platform-core) provides typed API clients for fetching Bible data and verse art in JavaScript and TypeScript applications. It is the shared core package used by the React SDK; core clients do not require React. See the source on GitHub.

Installation

Install the package with your preferred package manager:

npm install @youversion/platform-core

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

Troubleshooting: If you get a "Version not found" error (404), verify the version ID exists:

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.

USFM format: References follow the pattern BOOK.CHAPTER.VERSE where BOOK is a 3-character code (e.g., GEN, JHN, PSA). You can specify:

  • A single verse: JHN.3.16
  • A verse range: GEN.1.1-5
  • An entire chapter: GEN.1

Use getBooks() to discover valid book codes for a version, or see the USFM Reference for all standard book identifiers.

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

When displaying Bible text, always display a Bible Version's copyright attribution in accordance with the license agreement

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(options?)

Fetch the Verse of the Day for the entire year. Returns Promise<Collection<VOTDResponse>>. Image options require @youversion/platform-core 2.17.0 or later.

options.language_ranges is an optional array of ordered language ranges for the verse art. For example, pass { language_ranges: ["es", "en"] }. The collection contains records with day, passage_id, and nullable image_id. If you do not provide language_ranges, the response does not include image data.

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, options?)

Fetch the Verse of the Day for a specific day of the year. Returns Promise<VOTDResponse>. Image options require @youversion/platform-core 2.17.0 or later.

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

Parameters:

  • day (number): Integer from 1 through 366.
  • options.language_ranges (string array, optional): Ordered language ranges for the art. Omit to request the passage without art.

Response: day, passage_id, and image_id. image_id is null when you omit the language option or no art is available for the selected language. To load the selected image, pass a non-null image_id to ImagesClient.getImage:

Code
import { ImagesClient } from "@youversion/platform-core"; const images = new ImagesClient(apiClient); const dailyVerse = await bibleClient.getVOTD(1, { language_ranges: ["es", "en"], }); if (dailyVerse.image_id !== null) { const image = await images.getImage(dailyVerse.image_id); console.log(dailyVerse.passage_id, image.image_url); }

The example logs the passage identifier and image URL when art is available. The image is selected for that day; listing images for the same passage can return different art. See Images in Verse of the Day for language selection and rendering.

Images and unified search

To list verse art or load the selected daily image, see the Verse images guide.

@youversion/platform-core 2.16.0 includes ImagesClient and SearchClient.searchUnified. Version 2.17.0 adds paginated image search and Verse of the Day image options. These clients use your App Key.

Code
import { ApiClient, ImagesClient, SearchClient } from "@youversion/platform-core"; const apiClient = new ApiClient({ appKey: "YOUR_APP_KEY" }); const images = new ImagesClient(apiClient); const search = new SearchClient(apiClient); const page = await images.getImages({ passage_id: "JHN.3.16", language_ranges: ["en"], }); console.log(page.data); const results = await search.searchUnified("love", 3034, ["en"], { fields: ["verses", "topics", "images"], }); console.log(results.verses, results.topics); const relatedImage = results.images[0]; if (relatedImage) { const image = await images.getImage(relatedImage.id); console.log(image.image_url, image.attribution); }

getImages lists verse-art metadata for a verse or verse range that you already know. Chapter IDs such as JHN.3 are unsupported. If no images match, the result contains an empty data list. Pass next_page_token back as page_token to load another page. To find art that matches freeform text, use searchImages instead. See Verse Images for language selection, image sizes, caching, and the optional attribution credit line.

searchUnified returns one unpaginated response. The Bible version selects the verse results and their language. The language ranges select the search language for topics and images. See Language ranges for matching rules and preferences. Each related image contains id and passageId. Pass the id to getImage to get its URL and attribution. Showing attribution with the image is optional, and the API can return an empty string.

The React Verse images guide shows the same core ImagesClient calls inside a React component. The React Search guide uses useUnifiedSearch and YouVersionProvider from @youversion/platform-react-hooks. For JavaScript without React, use SearchClient.searchUnified as shown above. See Search APIs for the endpoints and pagination rules.

ImagesClient API

ImagesClient is available in @youversion/platform-core 2.16.0 or later. Construct it with an ApiClient. See the Verse images guide for setup, pagination, and VOTD art.

getImages(options?)

List verse-art metadata. Returns Promise<Collection<VerseImage>>.

Parameters: options (GetImagesOptions, optional):

  • passage_id (string, optional): One verse or a verse range, such as JHN.3.16 or JHN.3.16-18. Chapter ids are unsupported.
  • language_ranges (string array, optional): Ordered language filters. Omit to include every language. See Language selection.
  • page_size (number, optional): Integer from 1 through 99. The API default is 25.
  • page_token (string or null, optional): Continuation token from the previous page. Omit or pass null for the first page.

Response:

  • data: Array of VerseImage records.
  • next_page_token: Continuation token, or null when there are no more pages. An empty page can have a token.
  • total_size (optional): Total matching images, present when you pass passage_id.

If no images match, the result contains an empty data list.

getImage(imageId)

Fetch one image's metadata by id. Returns Promise<VerseImage>. A missing image rejects with an error whose getHttpStatus is 404.

A VerseImage contains id, image_url, passage_id, attribution, language_tag, width, height, and aspect_ratio. Load image bytes from image_url. The dimensions describe the original image. Showing the attribution credit is optional, and the string can be empty.

Both methods reject on invalid inputs or failed requests. Use getHttpStatus(error) to inspect HTTP errors.

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

Troubleshooting: If you get "Language ID must match BCP 47 format" error, use proper language codes:

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, topics, and images 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 characters.
  • versionId (number): Integer identifying a Bible version your app can access. Determines the language of verse results.
  • languageRanges (string or string array): Language preferences for topic and image 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): Result kinds to include: "verses", "topics", and "images". Omit to request all available kinds.

Response:

  • verses: Array of passage references, with the same shape as searchVerses results.
  • topics: Array of topics, with the same shape as searchTopics results.
  • images: Array of { id: string; passageId: string } related images, 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 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): nextPageToken from a previous response.

Response:

  • verses: Array of { id: string } results. 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.

Image search

searchImages(query, versionId, options?)

Find art that matches freeform text in one Bible version, with pagination. Requires @youversion/platform-core 2.17.0 or later. Returns Promise<SearchImagesResponse>. To list the art for a passage that you already know, use getImages instead.

Parameters:

  • query (string): Search text, trimmed before validation. Accepts 1 through 100 characters.
  • versionId (number): Integer identifying a Bible version your app can access. Selects the language searched.
  • options (SearchImagesOptions, optional):
    • pageSize (number, optional): Integer from 1 through 99. If omitted, the API determines the page size.
    • pageToken (string, optional): nextPageToken from a previous response.

Response:

  • images: Array of { id: string; passageId: string } related images. Pass an id to ImagesClient.getImage for its image URL and full metadata.
  • nextPageToken: Continuation token, or null when there are no more pages. An empty page can include a token, and the token can be an empty string.

Keep the query, Bible version, and page size unchanged between requests. Stop when nextPageToken is null. See Search images for an example.

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

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

Last modified on November 17, 2026
Quick StartTypeScript Types
On this page
  • Installation
  • Configuration
  • BibleClient API
    • Version Methods
    • Book Methods
    • Chapter Methods
    • Verse Methods
    • Passage Methods
    • Index & VOTD Methods
  • Images and unified search
    • ImagesClient API
  • LanguagesClient API
    • Language Methods
  • SearchClient API
    • Unified search
    • Verse search
    • Image search
    • Topic search
    • Suggested queries
    • Trending queries
  • Fonts
  • Utilities
    • Parse a passage reference
React
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
JSON
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
Javascript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript
TypeScript