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:
Configuration
Create an API client with your App Key:
Code
Types
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
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
getVersion(id)
Fetch a specific Bible version by ID.
Code
Parameters:
id(number): Bible version ID
Troubleshooting: If you get a "Version not found" error (404), verify the version ID exists:
Code
Book Methods
getBooks(versionId)
Fetch all books for a specific Bible version.
Code
Parameters:
versionId(number): Bible version ID
Response:
Code
getBook(versionId, book)
Fetch a specific book by its USFM identifier.
Code
Parameters:
versionId(number): Bible version IDbook(string): 3-character USFM book code (e.g.,"GEN","MAT","JHN")
Chapter Methods
getChapters(versionId, book)
Fetch all chapters for a specific book.
Code
Parameters:
versionId(number): Bible version IDbook(string): 3-character USFM book code
getChapter(versionId, book, chapter)
Fetch a specific chapter.
Code
Parameters:
versionId(number): Bible version IDbook(string): 3-character USFM book codechapter(number): Chapter number
Verse Methods
getVerses(versionId, book, chapter)
Fetch all verses for a specific chapter.
Code
Parameters:
versionId(number): Bible version IDbook(string): 3-character USFM book codechapter(number): Chapter number
Response:
Code
getVerse(versionId, book, chapter, verse)
Fetch a specific verse.
Code
Parameters:
versionId(number): Bible version IDbook(string): 3-character USFM book codechapter(number): Chapter numberverse(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
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
Parameters:
versionId(number): Bible version IDusfm(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 outputinclude_notes(boolean, optional): Include footnotes/endnotes in outputtransform(boolean, optional, defaulttrue): Whenformatis"html", sanitize and transform the HTML automatically. Passfalsefor 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 passtransform: 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
format: html
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
Parameters:
versionId(number): Bible version ID
Response:
Code
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
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
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
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
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 asJHN.3.16orJHN.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 ornull, optional): Continuation token from the previous page. Omit or passnullfor the first page.
Response:
data: Array ofVerseImagerecords.next_page_token: Continuation token, ornullwhen there are no more pages. An empty page can have a token.total_size(optional): Total matching images, present when you passpassage_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
Language Methods
getLanguages(options)
Fetch available languages supported in the platform.
Code
Parameters:
options(object):country(string, required): ISO 3166-1 alpha-2 country code (e.g.,"US","BR","MX")page_size(number, optional): Results per pagepage_token(string, optional): Pagination token from previous response
Response:
Code
getLanguage(languageId)
Fetch details about a specific language.
Code
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
SearchClient API
SearchClient searches verses, topics, and images and retrieves suggested or trending queries. See the search guide for pagination and interface workflows.
Code
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, ornull.
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 tosearchTopics.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):nextPageTokenfrom a previous response.
Response:
verses: Array of{ id: string }results. Eachidis a USFM passage identifier, not passage text. Malformed references are removed.nextPageToken: Continuation token, ornullor 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, ornullwhen 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):nextPageTokenfrom a previous response.
Response:
images: Array of{ id: string; passageId: string }related images. Pass anidtoImagesClient.getImagefor its image URL and full metadata.nextPageToken: Continuation token, ornullwhen 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 assearchVerses.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 withtext(string),subtopics(string array), and optionalid(integer ornull).totalSize: Number of topics in this response.didYouMean: Array of alternative spellings.searchInsteadFor: Query string supplied by the API, ornullwhen 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 forsearchTopics.
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
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
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.