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
      Copyright & AttributionSearchVerse images
React SDK
React Native (Expo) SDK
Guides

Verse images

Use the Images APIs to show verse art for the Verse of the Day, a search query, or a passage. This guide covers the JavaScript core SDK. For direct HTTP requests and the rules that apply to every platform, see Verse Images. For other SDKs, see the image guides for React, React Native Expo, Kotlin, and Swift.

Use ImagesClient from @youversion/platform-core to find verse art and load image metadata. These examples work in JavaScript and TypeScript applications.

Requirements

Use @youversion/platform-core 2.17.0 or later for all examples in this guide. Image listing and detail are available from 2.16.0; image search and VOTD image options require 2.17.0. Configure your app key as shown in the JavaScript SDK reference.

TerminalCode
npm install @youversion/platform-core@2.17.0

List images for a passage

Create the clients and request one page of art:

Code
import { ApiClient, BibleClient, ImagesClient } from "@youversion/platform-core"; const apiClient = new ApiClient({ appKey: "YOUR_APP_KEY" }); const images = new ImagesClient(apiClient); const bible = new BibleClient(apiClient); const filters = { passage_id: "JHN.3.16", language_ranges: ["en"], page_size: 12 }; const page = await images.getImages(filters); for (const image of page.data) { console.log(image.passage_id, image.image_url); }

Replace YOUR_APP_KEY with your app key. The example logs a passage identifier and image URL for each image in the page.

getImages lists the art for a passage that you already know. Pass one verse or a verse range as passage_id. Chapter ids such as JHN.3 are unsupported. Omit language_ranges to include every language. See Language selection for the supported image-language filters.

Load another page

Pass next_page_token back as page_token, keeping the passage and language filters unchanged:

Code
if (page.next_page_token !== null) { const nextPage = await images.getImages({ ...filters, page_token: page.next_page_token, }); console.log(nextPage.data, nextPage.next_page_token); }

Repeat when the user requests more results, using the token from each new page. A null token means there are no more pages. An empty page can still have a continuation token.

To find art that matches freeform text, such as "love", use image search instead.

Display a listed image

Use the image URL from a listed record. The following fragment selects the card size for the first record from the list above:

Code
const image = page.data[0]; if (image) { const cardUrl = new URL(image.image_url); cardUrl.searchParams.set("size", "card"); console.log(cardUrl.toString(), image.attribution); }

Listing returns the full image record. Use getImage when you have an id from search or Verse of the Day.

Use URL.searchParams.set to select thumb, card, or full without removing query parameters from the original URL. Showing attribution as an image credit is optional; it can be empty. See Verse Images for rendition sizes and caching.

Load Verse of the Day art

Request the day's selected image by supplying language ranges, then resolve a non-null image_id:

Code
const dailyVerse = await bible.getVOTD(1, { language_ranges: ["en"] }); console.log(dailyVerse.passage_id); if (dailyVerse.image_id !== null) { const image = await images.getImage(dailyVerse.image_id); console.log(image.image_url); } else { // No image is available for this day. }

This requests January 1 and logs its passage identifier and the selected art URL. image_id is null when no art matches the requested languages.

If you do not provide language_ranges, you get no image data. To fetch the full year's calendar, call getAllVOTDs with the same language_ranges and read its data records. See Images in Verse of the Day for language selection.

Handle request failures

Client methods return promises and reject on invalid arguments, failed requests, or unreadable responses. For HTTP failures, import getHttpStatus from @youversion/platform-core and call getHttpStatus(error) to read the response status.

For parameter limits and response fields, see ImagesClient API.

Last modified on November 17, 2026
SearchQuick Start
On this page
  • Requirements
  • List images for a passage
    • Load another page
  • Display a listed image
  • Load Verse of the Day art
  • Handle request failures
Javascript
Javascript
Javascript
Javascript