Guides

Verse Images

Let's say your app already shows the Verse of the Day as text. It works, but it looks like a text message. The Bible App shows that same verse as a piece of art, and your users have probably seen it there. The Images APIs let you show that same art in your own app: the daily verse image, images that match a search, and every image we have for a given passage.

There are two halves to the picture. The API tells you which image goes with a verse and hands you an opaque image_id or a full image record. The CDN serves the actual bytes at whatever size you ask for. You never build an image URL yourself; the API always gives it to you.

Endpoint	Use it when you want…	Paginated
`GET /v1/verse-of-the-days/{day}`	Today's verse with its image, in the user's language	No
`GET /v1/search-unified`	A search box that returns verses, topics, and images in one call	No
`GET /v1/search-images`	To page through every image that matches a search	Yes
`GET /v1/images`	Every image for a specific verse or passage, or to browse a language's art	Yes
`GET /v1/images/{image_id}`	To turn an `image_id` into a CDN URL, dimensions, and attribution	No

Browse the full request and response schemas in the interactive API reference.

Before You Start

Create your developer account and register your application at platform.YouVersion.com to obtain an App Key.
Every request must include your App Key in the X-YVP-App-Key header. See Authentication for details. No user sign-in is needed; verse images are app-scoped, not user-scoped.

Code
export YVP_APP_KEY='YOUR_APP_KEY_HERE'
export YVP_API_BASE='https://api.youversion.com/v1'

Key Concepts

An image is a record, not a file

The API never returns image bytes. It returns an Image record that points at the CDN:

Field	Description
`id`	A per-response reference to the image: the same value Verse of the Day returns as `image_id` and the search endpoints return as `id`. It is minted for that one response, so don't store, deduplicate, or compare it across responses; see Image ids and references.
`image_url`	The CDN URL for the art, ready to use exactly as given. It carries no App Key parameter; attribution of image loads to your app is handled by the API through the `id` the URL was resolved from. To pick a rendition, add `?size=thumb`, `?size=card`, or `?size=full`; leave it off for full size. See Picking a size.
`passage_id`	The passage the image illustrates: a verse (`JHN.3.16`) or a verse range (`1CO.13.4-8`). Same format the passages API accepts, so you can hand it straight back to fetch the text.
`attribution`	The credit line for the image, for example `© YouVersion`.
`language_tag`	BCP 47 tag of the language the art's text is in, for example `en` or `es`.
`width`, `height`	Native dimensions in pixels.
`aspect_ratio`	`width / height` rounded to three places (`1.0` for square art, `0.562` for 9:16 portrait). Use it to reserve layout space before the image loads.

Two of the entry points, Verse of the Day and Search, return just the id (plus passage_id for search). One extra call to GET /v1/images/{image_id} turns any id into the full record above. The /v1/images collection skips that step for rendering and returns full records directly.

Image ids and references

Every id the Images APIs return is an opaque, per-response reference. You can't construct or reverse one, so always take it from the API and never hard-code one. A reference is minted for the response that carried it, so the same image gets a different reference every time you see it: use it soon after you receive it, don't store it, and don't compare ids across responses (including between environments). Pass it to GET /v1/images/{image_id} as is.

A malformed or unknown id returns 404 Image not found.

The text always comes back

No verse art exists for every passage in every language. Every image-bearing endpoint treats the missing-image case as a normal response, never an error:

Verse of the Day returns 200 with the verse and image_id: null.
The /v1/images collection and GET /v1/search-images return 204 No Content with an empty body when nothing matches.
GET /v1/search-unified returns 200 with empty verses, topics, and images arrays, because it's a composite response that always carries query metadata (see Search APIs).

Design your UI with a text-only fallback: treat a null image_id, a 204, and an empty images array from unified search as no art, and check for them rather than catching errors.

Language selection

Verse art has words on it, so language matters. Verse of the Day and the /v1/images collection pick the art's language from language_ranges[], an ordered list of RFC 4647 Basic language ranges. Repeat the parameter to supply more than one, in preference order:

Code
language_ranges[]=es-MX&language_ranges[]=en

Ranges are tried in the order you give them, and resolution picks a language, not a particular image: it stops at the first language it recognizes, even if that language has no art for the day or passage you asked about. A later range is used only when an earlier one names a language the art catalog doesn't know. So es&en gives you Spanish art when there is some and no image when there isn't; it doesn't drop to English for that one day or passage. If you'd rather show English art than none, make a second request with language_ranges[]=en when the first returns no art.

The two endpoints differ in how they treat a regional range:

Verse of the Day falls back through each range's own chain: es-MX tries Mexican Spanish first, then Spanish.
The /v1/images collection stops at the first tag the image library recognizes. Regional tags such as es-MX, pt-BR, and en-US are recognized but currently have no art, so they come back 204 with no art rather than falling back to es, and resolution stops there even if you list es next. Strip the region before calling the collection (send es, not es-MX). Chinese is the exception: its art is tagged by region only, so ask for zh-CN, zh-TW, or zh-HK; a bare zh returns no art.

On Verse of the Day the wildcard * resolves to English; on the /v1/images collection it means "every language."

Search works differently:

GET /v1/search-images takes no language parameter. Its bible_id decides the language searched, exactly as it does for verse search.
GET /v1/search-unified still requires language_ranges[], as it always has, but there each range must exactly match a language search supports. There is no es-MX → es fallback, and * isn't accepted. If none of your ranges match, the request returns 400 with None of the requested language_ranges are supported by search., so end the list with a base tag such as en rather than relying on a regional one alone.

Picking a size

Every image_url accepts one optional size query parameter. The URL is clean (it has no query string), so add size with ?, not & — for example ?size=card. A URL builder (URLSearchParams in JavaScript, URLComponents on iOS, Uri.Builder on Android) saves you from splicing the string by hand. The CDN resizes from a single cached original, keeps the aspect ratio, and never upscales, so a 1080-pixel-wide original stays 1080 wide even at card.

`size`	Width	Good for
`thumb`	320 px	Lists, grids, pickers
`card`	1200 px	Feed cards, detail views, most phone screens
`full`	up to 2048 px	Sharing, wallpapers, hero images
(omitted)	same as `full`	Getting started

Sizes are presets on purpose. You can't pass raw pixel dimensions, and an unknown value or a duplicated size parameter returns 400 with a plain-text body: Invalid verse image size. Valid: size=thumb|card|full (omit for full).

Requesting thumb for a grid and card for the detail view is the difference between a download of a few tens of kilobytes and one of several hundred per image. Your users on cellular will notice.

Attribution

Every Image record carries an attribution string. Show it next to the image wherever the image appears, the same way you show Bible version attribution next to verse text. Verse of the Day and Search hand you only an id, so resolve the id through GET /v1/images/{image_id} before you render; the attribution comes back with the URL, and you never have to look it up separately.

If you'd also like to show the Bible App mark on your verse art, see the optional branding overlay. It's a nice touch, not a requirement, and it never replaces attribution.

Caching

Every Images API response carries Cache-Control: private, because the references and ids inside are minted for each response: keep them in a per-user or per-session cache, never a shared one, and give each entry a cache key that distinguishes the endpoint and the values of the request that produced it — the Verse of the Day day, the passage_id and language_ranges[] filters, and page_token where it applies — so two requests from the same user with different parameters never collide. A private cache alone isn't enough: without the key, a cached response for one passage or language can be served for another. See Image ids and references for why an id is private to the caller.

Don't hard-code a lifetime. Every response — and every CDN image URL — carries a Cache-Control header with the exact lifetime the platform intends for it, so respect that header per RFC 9111 (HTTP caching); your HTTP client or cache library can usually do this for you. Cache each response for as long as it allows, and re-fetch when the lifetime expires. If the platform changes the lifetime, your app follows automatically, no code change needed.

The CDN also serves the image bytes with a Cache-Control header on each URL, so let the browser or your image loader cache the bytes for whatever lifetime the header allows.

Images in Verse of the Day

Add language_ranges[] to any Verse of the Day request and the response carries an image_id for the day, whenever the language it resolves to has art for that day. Without the parameter, image_id is always null; day and passage_id are unchanged.

Endpoint URL

Code
GET https://api.youversion.com/v1/verse-of-the-days/{day}
GET https://api.youversion.com/v1/verse-of-the-days

Query Parameters

Parameter	Required	Description
`day` (path)	Yes, on the single-day route	Day of the year, 1–366. January 1 is day 1. A day outside that range returns `404`.
`language_ranges[]`	No	Ordered list of language ranges for the art. Omit it and `image_id` is `null`. The verse text itself is language-independent; you still pick a Bible when you fetch the passage.

Example Request

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/verse-of-the-days/1?language_ranges[]=es-MX&language_ranges[]=en"

Example Response


Code
{
  "day": 1,
  "passage_id": "ISA.43.18-19",
  "image_id": "cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6MTE2MzE2osR6OJpEx1ZVrEFLqeVWsg"
}

The full-year route returns the same shape inside a data array, one item per day.

Rendering it

Two calls get you from "what day is it" to pixels on screen:

Code
# 1. Today's verse, with Spanish art
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/verse-of-the-days/1?language_ranges[]=es&language_ranges[]=en"

# 2. Resolve the image_id to a CDN URL, then load it at card size
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/images/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6MTE2MzE2osR6OJpEx1ZVrEFLqeVWsg"
# -> image_url: https://cdn.youversion.com/images/base/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6MTE2MzE2osR6OJpEx1ZVrEFLqeVWsg/1280x1280.jpg
#    load https://cdn.youversion.com/images/base/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6MTE2MzE2osR6OJpEx1ZVrEFLqeVWsg/1280x1280.jpg?size=card

When image_id is null (the language your ranges resolved to has no art for that day, none of your ranges names a language with verse art, or you left the parameter off), show the passage text and move on. The response is still 200.

Language fallback, spelled out

You send	You get art in
`language_ranges[]=en`	English
`language_ranges[]=es-MX`	Mexican Spanish if it exists, otherwise Spanish
`language_ranges[]=fr&language_ranges[]=en`	French on days with French art, `image_id: null` on the others. English is used only if French had no verse art at all.
`language_ranges[]=*`	English
`language_ranges[]=xx-ZZ` (nothing matches)	`image_id: null`, text still returned

Images in unified search

GET /v1/search-unified now returns a third result kind, images, next to verses and topics. Nothing about the existing request changes, including the required language_ranges[] (see Language selection for how search matches it); if you already call this endpoint, your responses simply grow an images array. This is the right call for a general search box that shows a strip of verse art under the verse results. It is unpaginated; when you need every matching image, use search-images.

Example Request

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/search-unified?query=love&bible_id=3034&language_ranges[]=en"

Want only images from this endpoint? Narrow it with fields[]:

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/search-unified?query=love&bible_id=3034&language_ranges[]=en&fields[]=images"

Example Response


Code
{
  "verses": [
    { "reference": "JHN.3.16" },
    { "reference": "1CO.13.4" }
  ],
  "topics": [
    { "id": 42, "text": "love", "subtopics": ["trust", "belief"] }
  ],
  "images": [
    {
      "id": "cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6OTU2MzTSuDmYPvbDHD-9UateZkHP",
      "passage_id": "1CO.13.4-8"
    }
  ],
  "user_intent": "topical",
  "did_you_mean": [],
  "search_instead_for": null
}

Each image result is just id (a per-response reference) and passage_id. Resolve the id through GET /v1/images/{image_id} when the user taps it, or up front for the first few you plan to show. For everything else about this endpoint (bible_id access rules, user_intent, query metadata), see the Search APIs guide.

GET /v1/search-images

Search for verse art by query and page through the full result set. Like verse search, the bible_id determines the language searched, so there is no language parameter.

Endpoint URL

Code
GET https://api.youversion.com/v1/search-images

Query Parameters

Parameter	Required	Description
`query`	Yes	The search query string (1–100 characters).
`bible_id`	Yes	A Bible version your app can access (e.g. `3034`). Determines the language searched. An inaccessible id returns `404 Bible version {id} not found`; see Resource Not Found.
`page_size`	No	Number of images to return, 1–99. Defaults to `25`.
`page_token`	No	The `next_page_token` from a previous response.

Example Request

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/search-images?query=love&bible_id=3034&page_size=25"

Example Response


Code
{
  "images": [
    {
      "id": "eyJhbGciOiJFUzI1NiIsImtpZCI6...",
      "passage_id": "1CO.13.4-8"
    },
    {
      "id": "eyJhbGciOiJFUzI1NiIsImtpZCI6...",
      "passage_id": "EPH.3.17-19"
    }
  ],
  "next_page_token": "gAAAAABq2jvon6bUfANAK9-pqQUj4zu7WkkgE74g..."
}

Fetching the Next Page

When next_page_token is non-null, send it back as page_token with the same query, bible_id, and page_size. A token is bound to the search that produced it; reusing it with different parameters returns 400 Invalid page_token.

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/search-images?query=love&bible_id=3034&page_size=25&page_token=$NEXT_PAGE_TOKEN"

Response Fields

Field	Description
`images`	Array of image results, each with `id` (a per-response reference) and `passage_id`.
`next_page_token`	Token for the next page, or `null` when there are no more results.

When nothing matches, this endpoint returns 204 No Content with an empty body, not a 200 with an empty images array.

GET /v1/images

List verse art directly, without going through search. Filter by passage, by language, or both, and page through the results. Every item is the full Image record, so you can render it without a second call; resolve an item through GET /v1/images/{image_id} only if you want a fresh record, for example for attribution. This is the endpoint for "show me all the art for John 3:16" or "give me a gallery of Spanish verse images." Filtering works at the verse level: a single verse or a verse range. Whole-chapter filtering isn't supported yet.

Endpoint URL

Code
GET https://api.youversion.com/v1/images

Query Parameters

Parameter	Required	Description
`passage_id`	No	Return images illustrating this passage: a single verse (`JHN.3.16`) or a verse range (`1CO.13.4-7`). An image matches if it illustrates any verse in the range. Chapter-level identifiers such as `JHN.3` are not supported yet; pass a verse range that covers the chapter instead. A string that isn't a passage reference returns `400 Invalid passage_id`.
`language_ranges[]`	No	Filter by the art's language, tried in order. Resolution stops at the first tag the image library recognizes, even if it has no art for your filter, and a regional tag such as `es-MX` doesn't fall back to `es`; see Language selection. `*` returns every language. An unrecognized range format returns `400`. Omit to return every language.
`page_size`	No	Number of images to return, 1–99. Defaults to `25`.
`page_token`	No	The `next_page_token` from a previous response.

Combining passage_id and language_ranges[] narrows to images matching both.

Example Request

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/images?passage_id=JHN.3.16&language_ranges[]=en&page_size=2"

Example Response


Code
{
  "data": [
    {
      "id": "eyJhbGciOiJFUzI1NiIsImtpZCI6...",
      "image_url": "https://cdn.youversion.com/images/base/eyJhbGciOiJFUzI1NiIsImtpZCI6.../1280x2276.jpg",
      "passage_id": "JHN.3.16",
      "attribution": "© YouVersion",
      "language_tag": "en",
      "width": 1280,
      "height": 2276,
      "aspect_ratio": 0.562
    },
    {
      "id": "eyJhbGciOiJFUzI1NiIsImtpZCI6...",
      "image_url": "https://cdn.youversion.com/images/base/eyJhbGciOiJFUzI1NiIsImtpZCI6.../1280x2276.jpg",
      "passage_id": "JHN.3.16",
      "attribution": "© YouVersion",
      "language_tag": "en",
      "width": 1280,
      "height": 2276,
      "aspect_ratio": 0.562
    }
  ],
  "total_size": 12,
  "next_page_token": "gAAAAABqvRXLXys3jrlwO7ExA-7srlaBe_0HUkop..."
}

Response Fields

Field	Description
`data`	Array of full Image records. Each item's `id` is a per-response reference; resolve it through `GET /v1/images/{image_id}` only if you want a fresh copy of the full record.
`total_size`	Total matches across all pages. Only populated when you pass `passage_id`. A language-only or unfiltered browse returns `null` here because the catalog is large and an exact count isn't available; keep paging until `next_page_token` is `null`.
`next_page_token`	Token for the next page, or `null` when there are no more results.

A filter that matches nothing returns 204 No Content with an empty body — no data array, no total_size — not a 200 with an empty data array, and not a 404.

Browsing a language

Leave off passage_id to walk a language's whole catalog. Expect total_size: null and a lot of pages:

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/images?language_ranges[]=es&page_size=50"

Page tokens are bound to the filter that produced them. You can change page_size between pages, but changing passage_id or language_ranges[] with an old token returns 400 Invalid page_token.

GET /v1/images/{image_id}

Resolve an id into the full Image record. Every id is a per-response reference, whether it came from Verse of the Day, unified search, the /v1/images collection, or search-images, and the record's id is itself a reference minted for this response.

Endpoint URL

Code
GET https://api.youversion.com/v1/images/{image_id}

Path Parameters

Parameter	Required	Description
`image_id`	Yes	The opaque id exactly as the API returned it.

Example Request

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/images/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6OTU2MzTSuDmYPvbDHD-9UateZkHP"

Example Response


Code
{
  "id": "cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6OTU2MzTSuDmYPvbDHD-9UateZkHP",
  "image_url": "https://cdn.youversion.com/images/base/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6OTU2MzTSuDmYPvbDHD-9UateZkHP/1080x1920.jpg",
  "passage_id": "1CO.13.4-8",
  "attribution": "© YouVersion",
  "language_tag": "en",
  "width": 1080,
  "height": 1920,
  "aspect_ratio": 0.562
}

Then load the bytes at the size you need, using image_url exactly as returned plus ?size=:

Code
<img
  src="https://cdn.youversion.com/images/base/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6OTU2MzTSuDmYPvbDHD-9UateZkHP/1080x1920.jpg?size=card"
  width="1080" height="1920"
  alt="1 Corinthians 13:4-8"
  loading="lazy"
/>
<figcaption>© YouVersion</figcaption>

Setting width and height from the record (or a CSS aspect-ratio: 0.562) keeps the page from jumping while the image loads.

An id that doesn't resolve returns 404 Image not found, whether it was mistyped, forged, or belongs to an image that no longer exists.

Putting it together

A daily-verse card, start to finish:

Call GET /v1/verse-of-the-days/{day}?language_ranges[]={user language}&language_ranges[]=en.
Fetch the verse text for passage_id from the passages API with the user's Bible.
If image_id is non-null, call GET /v1/images/{image_id} and load image_url with ?size=card added behind the text, with attribution in the corner. If it's null, render the text on your own background, or repeat step 1 with only language_ranges[]=en if you'd rather show English art.
Cache each response for as long as its Cache-Control header allows, and re-fetch when it expires.

A "verse art" tab in your search results:

Call GET /v1/search-unified?... as you already do and render the images array as thumb-size tiles, resolving each id as it scrolls into view.
When the user wants more, switch to GET /v1/search-images with the same query and bible_id and page with next_page_token.
On tap, show the card or full rendition and offer the passage_id as a link into the reader.

Optional: Bible App branding overlay

We publish the Bible App mark as a lower-third branding overlay for verse art. If you'd like your images to carry it, it's hosted on the CDN:

https://cdn.youversion.com/branding/bible-app-overlay-white.png

It's a 660 × 156 PNG on a transparent background: the Bible App icon beside a white "Bible App" wordmark, so it's meant to sit on top of the art rather than on a light page.

The overlay is entirely optional. YouVersion doesn't require it, and it doesn't replace attribution, which you still show wherever the image appears.

If you use it, these suggestions give the cleanest result:

Layer it over the art at render time. Use a positioned element in HTML and CSS, an overlay view in a native layout, or a second draw call when you composite onto a canvas to export a share image. Both the art and the mark are served with Access-Control-Allow-Origin: *, so load them with crossOrigin = "anonymous" and the canvas stays exportable.
Keep it in the lower third, clear of the verse text on the art, with some padding from the edge.
Size it relative to the image, not in fixed pixels, so it scales with thumb, card, and full. A width of roughly a third of the image is a good starting point. The file is 660 pixels wide, so it stays sharpest when it's drawn at or below that many device pixels; on a 2× screen, that's about 330 CSS pixels.
Keep its proportions. Scale it evenly rather than cropping or stretching it.
Mind the contrast. The wordmark is white. Where the bottom of an image is light, put a subtle dark gradient behind the mark, or leave the mark off that image.
Skip it where it can't be read, such as thumb-size tiles in a dense grid.

On a web page, that can be as little as an absolutely positioned image inside a wrapper, with an optional gradient behind it:

Code
<div class="verse-art">
  <img src="https://cdn.youversion.com/images/base/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6OTU2MzTSuDmYPvbDHD-9UateZkHP/1080x1920.jpg?size=card"
       width="1080" height="1920" alt="1 Corinthians 13:4-8" />
  <img class="verse-art-brand" alt=""
       src="https://cdn.youversion.com/branding/bible-app-overlay-white.png" />
</div>
<!-- Render the Image record's attribution here -->
<p class="verse-art-credit">© YouVersion</p>

<style>
  .verse-art { position: relative; }
  .verse-art > img:first-child { display: block; width: 100%; height: auto; }
  /* Optional: darken the bottom of the art so the white wordmark reads. */
  .verse-art::after {
    content: "";
    position: absolute;
    inset: auto 0 0 0;
    height: 33%;
    background: linear-gradient(transparent, rgb(0 0 0 / 0.6));
    pointer-events: none;
  }
  .verse-art-brand {
    position: absolute;
    z-index: 1;
    left: 50%;
    bottom: 8%;
    width: 33%;
    max-width: 330px;
    transform: translateX(-50%);
    pointer-events: none;
  }
</style>

The mark is decorative, so give it an empty alt and keep the passage in the main image's alt text. It's the same small file for every image, and the CDN serves it with a Cache-Control header, so your browser or image loader will reuse one copy across every image it decorates.

Errors

The Images endpoints use the standard Platform error responses:

Status	When	Examples
`400 Bad Request`	A parameter is syntactically valid but rejected.	`passage_id` that isn't a passage reference; malformed `language_ranges[]` value; a `language_ranges[]` on `search-unified` that matches no language search supports; `page_token` reused with different parameters or corrupted.
`401 Unauthorized`	Missing or invalid App Key.	No `X-YVP-App-Key` header. See Authentication.
`404 Not Found`	The resource isn't available to your app.	`image_id` that doesn't resolve (`Image not found`); a Verse of the Day `day` outside 1–366 (`Not Found`); on `search-images` / `search-unified`, a `bible_id` your app can't access (`Bible version {id} not found`).
`422 Unprocessable Content`	A required parameter is missing or out of range.	Missing `query` or `bible_id` on `search-images`; missing `language_ranges[]` on `search-unified`; `page_size` outside 1–99.
`429 Too Many Requests`	Rate limit exceeded.	Check `Retry-After` before retrying.
`502` / `503`	The upstream image or search service is unavailable.	Retry with backoff; Verse of the Day returns `503 Verse images are temporarily unavailable` when only the art lookup fails.

The CDN returns a plain-text 400 for an invalid or duplicated size parameter; see Picking a size.

For response body shapes, see the error codes reference.

Need Help?

If you need help integrating verse images or have questions about the documentation, please reach out to our support team.

Last modified on November 13, 2026

Search APIs USFM Reference

Guides

Verse Images

Endpoint	Use it when you want…	Paginated
`GET /v1/verse-of-the-days/{day}`	Today's verse with its image, in the user's language	No
`GET /v1/search-unified`	A search box that returns verses, topics, and images in one call	No
`GET /v1/search-images`	To page through every image that matches a search	Yes
`GET /v1/images`	Every image for a specific verse or passage, or to browse a language's art	Yes
`GET /v1/images/{image_id}`	To turn an `image_id` into a CDN URL, dimensions, and attribution	No

Browse the full request and response schemas in the interactive API reference.

Before You Start

Create your developer account and register your application at platform.YouVersion.com to obtain an App Key.
Every request must include your App Key in the X-YVP-App-Key header. See Authentication for details. No user sign-in is needed; verse images are app-scoped, not user-scoped.

Code
export YVP_APP_KEY='YOUR_APP_KEY_HERE'
export YVP_API_BASE='https://api.youversion.com/v1'

Key Concepts

An image is a record, not a file

The API never returns image bytes. It returns an Image record that points at the CDN:

Field	Description
`id`	A per-response reference to the image: the same value Verse of the Day returns as `image_id` and the search endpoints return as `id`. It is minted for that one response, so don't store, deduplicate, or compare it across responses; see Image ids and references.
`image_url`	The CDN URL for the art, ready to use exactly as given. It carries no App Key parameter; attribution of image loads to your app is handled by the API through the `id` the URL was resolved from. To pick a rendition, add `?size=thumb`, `?size=card`, or `?size=full`; leave it off for full size. See Picking a size.
`passage_id`	The passage the image illustrates: a verse (`JHN.3.16`) or a verse range (`1CO.13.4-8`). Same format the passages API accepts, so you can hand it straight back to fetch the text.
`attribution`	The credit line for the image, for example `© YouVersion`.
`language_tag`	BCP 47 tag of the language the art's text is in, for example `en` or `es`.
`width`, `height`	Native dimensions in pixels.
`aspect_ratio`	`width / height` rounded to three places (`1.0` for square art, `0.562` for 9:16 portrait). Use it to reserve layout space before the image loads.

Image ids and references

A malformed or unknown id returns 404 Image not found.

The text always comes back

No verse art exists for every passage in every language. Every image-bearing endpoint treats the missing-image case as a normal response, never an error:

Verse of the Day returns 200 with the verse and image_id: null.
The /v1/images collection and GET /v1/search-images return 204 No Content with an empty body when nothing matches.
GET /v1/search-unified returns 200 with empty verses, topics, and images arrays, because it's a composite response that always carries query metadata (see Search APIs).

Design your UI with a text-only fallback: treat a null image_id, a 204, and an empty images array from unified search as no art, and check for them rather than catching errors.

Language selection

Code
language_ranges[]=es-MX&language_ranges[]=en

The two endpoints differ in how they treat a regional range:

Verse of the Day falls back through each range's own chain: es-MX tries Mexican Spanish first, then Spanish.
The /v1/images collection stops at the first tag the image library recognizes. Regional tags such as es-MX, pt-BR, and en-US are recognized but currently have no art, so they come back 204 with no art rather than falling back to es, and resolution stops there even if you list es next. Strip the region before calling the collection (send es, not es-MX). Chinese is the exception: its art is tagged by region only, so ask for zh-CN, zh-TW, or zh-HK; a bare zh returns no art.

On Verse of the Day the wildcard * resolves to English; on the /v1/images collection it means "every language."

Search works differently:

GET /v1/search-images takes no language parameter. Its bible_id decides the language searched, exactly as it does for verse search.
GET /v1/search-unified still requires language_ranges[], as it always has, but there each range must exactly match a language search supports. There is no es-MX → es fallback, and * isn't accepted. If none of your ranges match, the request returns 400 with None of the requested language_ranges are supported by search., so end the list with a base tag such as en rather than relying on a regional one alone.

Picking a size

`size`	Width	Good for
`thumb`	320 px	Lists, grids, pickers
`card`	1200 px	Feed cards, detail views, most phone screens
`full`	up to 2048 px	Sharing, wallpapers, hero images
(omitted)	same as `full`	Getting started

Requesting thumb for a grid and card for the detail view is the difference between a download of a few tens of kilobytes and one of several hundred per image. Your users on cellular will notice.

Attribution

If you'd also like to show the Bible App mark on your verse art, see the optional branding overlay. It's a nice touch, not a requirement, and it never replaces attribution.

Caching

The CDN also serves the image bytes with a Cache-Control header on each URL, so let the browser or your image loader cache the bytes for whatever lifetime the header allows.

Images in Verse of the Day

Endpoint URL

Code
GET https://api.youversion.com/v1/verse-of-the-days/{day}
GET https://api.youversion.com/v1/verse-of-the-days

Query Parameters

Parameter	Required	Description
`day` (path)	Yes, on the single-day route	Day of the year, 1–366. January 1 is day 1. A day outside that range returns `404`.
`language_ranges[]`	No	Ordered list of language ranges for the art. Omit it and `image_id` is `null`. The verse text itself is language-independent; you still pick a Bible when you fetch the passage.

Example Request

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/verse-of-the-days/1?language_ranges[]=es-MX&language_ranges[]=en"

Example Response


Code
{
  "day": 1,
  "passage_id": "ISA.43.18-19",
  "image_id": "cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6MTE2MzE2osR6OJpEx1ZVrEFLqeVWsg"
}

The full-year route returns the same shape inside a data array, one item per day.

Rendering it

Two calls get you from "what day is it" to pixels on screen:

Code
# 1. Today's verse, with Spanish art
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/verse-of-the-days/1?language_ranges[]=es&language_ranges[]=en"

# 2. Resolve the image_id to a CDN URL, then load it at card size
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/images/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6MTE2MzE2osR6OJpEx1ZVrEFLqeVWsg"
# -> image_url: https://cdn.youversion.com/images/base/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6MTE2MzE2osR6OJpEx1ZVrEFLqeVWsg/1280x1280.jpg
#    load https://cdn.youversion.com/images/base/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6MTE2MzE2osR6OJpEx1ZVrEFLqeVWsg/1280x1280.jpg?size=card

Language fallback, spelled out

You send	You get art in
`language_ranges[]=en`	English
`language_ranges[]=es-MX`	Mexican Spanish if it exists, otherwise Spanish
`language_ranges[]=fr&language_ranges[]=en`	French on days with French art, `image_id: null` on the others. English is used only if French had no verse art at all.
`language_ranges[]=*`	English
`language_ranges[]=xx-ZZ` (nothing matches)	`image_id: null`, text still returned

Images in unified search

Example Request

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/search-unified?query=love&bible_id=3034&language_ranges[]=en"

Want only images from this endpoint? Narrow it with fields[]:

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/search-unified?query=love&bible_id=3034&language_ranges[]=en&fields[]=images"

Example Response


Code
{
  "verses": [
    { "reference": "JHN.3.16" },
    { "reference": "1CO.13.4" }
  ],
  "topics": [
    { "id": 42, "text": "love", "subtopics": ["trust", "belief"] }
  ],
  "images": [
    {
      "id": "cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6OTU2MzTSuDmYPvbDHD-9UateZkHP",
      "passage_id": "1CO.13.4-8"
    }
  ],
  "user_intent": "topical",
  "did_you_mean": [],
  "search_instead_for": null
}

GET /v1/search-images

Search for verse art by query and page through the full result set. Like verse search, the bible_id determines the language searched, so there is no language parameter.

Endpoint URL

Code
GET https://api.youversion.com/v1/search-images

Query Parameters

Parameter	Required	Description
`query`	Yes	The search query string (1–100 characters).
`bible_id`	Yes	A Bible version your app can access (e.g. `3034`). Determines the language searched. An inaccessible id returns `404 Bible version {id} not found`; see Resource Not Found.
`page_size`	No	Number of images to return, 1–99. Defaults to `25`.
`page_token`	No	The `next_page_token` from a previous response.

Example Request

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/search-images?query=love&bible_id=3034&page_size=25"

Example Response


Code
{
  "images": [
    {
      "id": "eyJhbGciOiJFUzI1NiIsImtpZCI6...",
      "passage_id": "1CO.13.4-8"
    },
    {
      "id": "eyJhbGciOiJFUzI1NiIsImtpZCI6...",
      "passage_id": "EPH.3.17-19"
    }
  ],
  "next_page_token": "gAAAAABq2jvon6bUfANAK9-pqQUj4zu7WkkgE74g..."
}

Fetching the Next Page

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/search-images?query=love&bible_id=3034&page_size=25&page_token=$NEXT_PAGE_TOKEN"

Response Fields

Field	Description
`images`	Array of image results, each with `id` (a per-response reference) and `passage_id`.
`next_page_token`	Token for the next page, or `null` when there are no more results.

When nothing matches, this endpoint returns 204 No Content with an empty body, not a 200 with an empty images array.

GET /v1/images

Endpoint URL

Code
GET https://api.youversion.com/v1/images

Query Parameters

Parameter	Required	Description
`passage_id`	No	Return images illustrating this passage: a single verse (`JHN.3.16`) or a verse range (`1CO.13.4-7`). An image matches if it illustrates any verse in the range. Chapter-level identifiers such as `JHN.3` are not supported yet; pass a verse range that covers the chapter instead. A string that isn't a passage reference returns `400 Invalid passage_id`.
`language_ranges[]`	No	Filter by the art's language, tried in order. Resolution stops at the first tag the image library recognizes, even if it has no art for your filter, and a regional tag such as `es-MX` doesn't fall back to `es`; see Language selection. `*` returns every language. An unrecognized range format returns `400`. Omit to return every language.
`page_size`	No	Number of images to return, 1–99. Defaults to `25`.
`page_token`	No	The `next_page_token` from a previous response.

Combining passage_id and language_ranges[] narrows to images matching both.

Example Request

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/images?passage_id=JHN.3.16&language_ranges[]=en&page_size=2"

Example Response


Code
{
  "data": [
    {
      "id": "eyJhbGciOiJFUzI1NiIsImtpZCI6...",
      "image_url": "https://cdn.youversion.com/images/base/eyJhbGciOiJFUzI1NiIsImtpZCI6.../1280x2276.jpg",
      "passage_id": "JHN.3.16",
      "attribution": "© YouVersion",
      "language_tag": "en",
      "width": 1280,
      "height": 2276,
      "aspect_ratio": 0.562
    },
    {
      "id": "eyJhbGciOiJFUzI1NiIsImtpZCI6...",
      "image_url": "https://cdn.youversion.com/images/base/eyJhbGciOiJFUzI1NiIsImtpZCI6.../1280x2276.jpg",
      "passage_id": "JHN.3.16",
      "attribution": "© YouVersion",
      "language_tag": "en",
      "width": 1280,
      "height": 2276,
      "aspect_ratio": 0.562
    }
  ],
  "total_size": 12,
  "next_page_token": "gAAAAABqvRXLXys3jrlwO7ExA-7srlaBe_0HUkop..."
}

Response Fields

Field	Description
`data`	Array of full Image records. Each item's `id` is a per-response reference; resolve it through `GET /v1/images/{image_id}` only if you want a fresh copy of the full record.
`total_size`	Total matches across all pages. Only populated when you pass `passage_id`. A language-only or unfiltered browse returns `null` here because the catalog is large and an exact count isn't available; keep paging until `next_page_token` is `null`.
`next_page_token`	Token for the next page, or `null` when there are no more results.

A filter that matches nothing returns 204 No Content with an empty body — no data array, no total_size — not a 200 with an empty data array, and not a 404.

Browsing a language

Leave off passage_id to walk a language's whole catalog. Expect total_size: null and a lot of pages:

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/images?language_ranges[]=es&page_size=50"

Page tokens are bound to the filter that produced them. You can change page_size between pages, but changing passage_id or language_ranges[] with an old token returns 400 Invalid page_token.

GET /v1/images/{image_id}

Endpoint URL

Code
GET https://api.youversion.com/v1/images/{image_id}

Path Parameters

Parameter	Required	Description
`image_id`	Yes	The opaque id exactly as the API returned it.

Example Request

Code
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \
  "$YVP_API_BASE/images/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6OTU2MzTSuDmYPvbDHD-9UateZkHP"

Example Response


Code
{
  "id": "cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6OTU2MzTSuDmYPvbDHD-9UateZkHP",
  "image_url": "https://cdn.youversion.com/images/base/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6OTU2MzTSuDmYPvbDHD-9UateZkHP/1080x1920.jpg",
  "passage_id": "1CO.13.4-8",
  "attribution": "© YouVersion",
  "language_tag": "en",
  "width": 1080,
  "height": 1920,
  "aspect_ratio": 0.562
}

Then load the bytes at the size you need, using image_url exactly as returned plus ?size=:

Code
<img
  src="https://cdn.youversion.com/images/base/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6OTU2MzTSuDmYPvbDHD-9UateZkHP/1080x1920.jpg?size=card"
  width="1080" height="1920"
  alt="1 Corinthians 13:4-8"
  loading="lazy"
/>
<figcaption>© YouVersion</figcaption>

Setting width and height from the record (or a CSS aspect-ratio: 0.562) keeps the page from jumping while the image loads.

An id that doesn't resolve returns 404 Image not found, whether it was mistyped, forged, or belongs to an image that no longer exists.

Putting it together

A daily-verse card, start to finish:

Call GET /v1/verse-of-the-days/{day}?language_ranges[]={user language}&language_ranges[]=en.
Fetch the verse text for passage_id from the passages API with the user's Bible.
If image_id is non-null, call GET /v1/images/{image_id} and load image_url with ?size=card added behind the text, with attribution in the corner. If it's null, render the text on your own background, or repeat step 1 with only language_ranges[]=en if you'd rather show English art.
Cache each response for as long as its Cache-Control header allows, and re-fetch when it expires.

A "verse art" tab in your search results:

Call GET /v1/search-unified?... as you already do and render the images array as thumb-size tiles, resolving each id as it scrolls into view.
When the user wants more, switch to GET /v1/search-images with the same query and bible_id and page with next_page_token.
On tap, show the card or full rendition and offer the passage_id as a link into the reader.

Optional: Bible App branding overlay

We publish the Bible App mark as a lower-third branding overlay for verse art. If you'd like your images to carry it, it's hosted on the CDN:

https://cdn.youversion.com/branding/bible-app-overlay-white.png

It's a 660 × 156 PNG on a transparent background: the Bible App icon beside a white "Bible App" wordmark, so it's meant to sit on top of the art rather than on a light page.

The overlay is entirely optional. YouVersion doesn't require it, and it doesn't replace attribution, which you still show wherever the image appears.

If you use it, these suggestions give the cleanest result:

Layer it over the art at render time. Use a positioned element in HTML and CSS, an overlay view in a native layout, or a second draw call when you composite onto a canvas to export a share image. Both the art and the mark are served with Access-Control-Allow-Origin: *, so load them with crossOrigin = "anonymous" and the canvas stays exportable.
Keep it in the lower third, clear of the verse text on the art, with some padding from the edge.
Size it relative to the image, not in fixed pixels, so it scales with thumb, card, and full. A width of roughly a third of the image is a good starting point. The file is 660 pixels wide, so it stays sharpest when it's drawn at or below that many device pixels; on a 2× screen, that's about 330 CSS pixels.
Keep its proportions. Scale it evenly rather than cropping or stretching it.
Mind the contrast. The wordmark is white. Where the bottom of an image is light, put a subtle dark gradient behind the mark, or leave the mark off that image.
Skip it where it can't be read, such as thumb-size tiles in a dense grid.

On a web page, that can be as little as an absolutely positioned image inside a wrapper, with an optional gradient behind it:

Code
<div class="verse-art">
  <img src="https://cdn.youversion.com/images/base/cHJlcmVuZGVyZWQtdmVyc2UtaW1hZ2U6OTU2MzTSuDmYPvbDHD-9UateZkHP/1080x1920.jpg?size=card"
       width="1080" height="1920" alt="1 Corinthians 13:4-8" />
  <img class="verse-art-brand" alt=""
       src="https://cdn.youversion.com/branding/bible-app-overlay-white.png" />
</div>
<!-- Render the Image record's attribution here -->
<p class="verse-art-credit">© YouVersion</p>

<style>
  .verse-art { position: relative; }
  .verse-art > img:first-child { display: block; width: 100%; height: auto; }
  /* Optional: darken the bottom of the art so the white wordmark reads. */
  .verse-art::after {
    content: "";
    position: absolute;
    inset: auto 0 0 0;
    height: 33%;
    background: linear-gradient(transparent, rgb(0 0 0 / 0.6));
    pointer-events: none;
  }
  .verse-art-brand {
    position: absolute;
    z-index: 1;
    left: 50%;
    bottom: 8%;
    width: 33%;
    max-width: 330px;
    transform: translateX(-50%);
    pointer-events: none;
  }
</style>

Errors

The Images endpoints use the standard Platform error responses:

Status	When	Examples
`400 Bad Request`	A parameter is syntactically valid but rejected.	`passage_id` that isn't a passage reference; malformed `language_ranges[]` value; a `language_ranges[]` on `search-unified` that matches no language search supports; `page_token` reused with different parameters or corrupted.
`401 Unauthorized`	Missing or invalid App Key.	No `X-YVP-App-Key` header. See Authentication.
`404 Not Found`	The resource isn't available to your app.	`image_id` that doesn't resolve (`Image not found`); a Verse of the Day `day` outside 1–366 (`Not Found`); on `search-images` / `search-unified`, a `bible_id` your app can't access (`Bible version {id} not found`).
`422 Unprocessable Content`	A required parameter is missing or out of range.	Missing `query` or `bible_id` on `search-images`; missing `language_ranges[]` on `search-unified`; `page_size` outside 1–99.
`429 Too Many Requests`	Rate limit exceeded.	Check `Retry-After` before retrying.
`502` / `503`	The upstream image or search service is unavailable.	Retry with backoff; Verse of the Day returns `503 Verse images are temporarily unavailable` when only the art lookup fails.

The CDN returns a plain-text 400 for an invalid or duplicated size parameter; see Picking a size.

For response body shapes, see the error codes reference.

Need Help?

If you need help integrating verse images or have questions about the documentation, please reach out to our support team.

Last modified on November 13, 2026

Search APIs USFM Reference