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
Getting Started
    YouVersion Platform OverviewAPI Usage
Guides
    Display Bible HTMLLanguage rangesSign-in APIsSearch APIsVerse ImagesUSFM ReferenceError Codes
Useful Links
    YouVersionGitHub
Guides

Search APIs

Start with an SDK. If a YouVersion SDK supports your language or framework, we recommend using it for search. See the search guide for JavaScript and TypeScript, React web, React Native Expo, Swift, or Kotlin.

Use the REST endpoints below when you need a direct API integration.

The Search APIs let your app find Bible verses, related topics, and verse images for a query, and return suggested (as-you-type) and trending search queries. There are five endpoints, each for a different job:

EndpointUse it when you want…Paginated
GET /v1/search-unifiedOne combined set of top verses, topics, and images for a queryNo
GET /v1/search-versesTo page through the full list of matching versesYes
GET /v1/search-topicsThe full set of topics related to a query, to pivot to other verses on the same topicNo
GET /v1/search-imagesTo page through the verse images that match a queryYes
GET /v1/search-queriesSuggested (as-you-type) or trending search stringsNo

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.
TerminalCode
export YVP_APP_KEY='YOUR_APP_KEY_HERE'

Key Concepts

Verse results are references, never text

Verse results carry a scripture reference only — a single USFM string such as JHN.3.16. They do not include the Bible version, passage text, or any other verse fields. Resolve the text for a reference through the passages API, where Bible licensing and tier enforcement live.

Verse search requires a Bible your app can access

search-unified, search-verses, and search-images require a bible_id your app is entitled to. This is the same set returned by GET /v1/bibles?language_ranges[]=en without all_available — the Bibles your app is licensed for and that are live in the catalog.

If you pass a bible_id your app cannot access, the endpoint returns 404 Bible version {id} not found. Here a 404 means "not available to this app" (unlicensed or not in the live catalog), not "this ID does not exist." Check your entitled Bibles as described in Resource Not Found before treating it as a bad ID.

Language selection

  • bible_id selects the Bible version and the language for verse results. search-unified, search-verses, and search-images require it. search-verses and search-images take no language-range parameter.
  • language_ranges[] selects the language for topic and image results in unified search, and for topic search, suggestions, and trending queries. It is required by search-unified, search-topics, and search-queries. Suggested and trending queries both use search-queries. Repeat the parameter for multiple preferences, in preference order:
Code
language_ranges[]=en&language_ranges[]=es

Use language_ranges[]=* to match all languages. See Language ranges for matching rules and language preferences.

Query metadata

Every verse and unified-results response includes query metadata so you can build "did you mean" experiences. search-verses and search-unified return all three fields below; search-topics returns did_you_mean and search_instead_for only (no user_intent).

FieldDescription
user_intentThe intent the search service resolved for the query (unknown, topical, text, or reference). Nullable. Returned by search-verses and search-unified only.
did_you_meanAlternative spellings the search service suggests for the query (array of strings; empty when there are none).
search_instead_forA corrected query the results were actually returned for when the service auto-corrected a likely typo, otherwise null. For example, a search for jees may set search_instead_for to jesus and return results for the corrected term.

Pagination

search-verses and search-images are paginated. Both use page_size and page_token. When more results are available, the response includes a next_page_token. Send that value back as page_token in the next request. search-unified, search-topics, and search-queries are unpaginated. Each returns one fixed set of results and takes no page_size or page_token.


GET /v1/search-unified

Search the Platform for Bible verses, related topics, and verse images in one call. The response is one combined set of top results for each kind. This is the starting point for a general search box. The endpoint is unpaginated. For more results, use search-verses or search-images with pagination, or search-topics for the full topic set.

Endpoint URL

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

Query Parameters

ParameterRequiredDescription
queryYesThe search query string (1–100 characters).
bible_idYesThe Bible version identifier your app can access. Determines the language of verse results (e.g. 3034). See Verse search requires a Bible your app can access.
language_ranges[]YesOrdered language ranges for the request, such as language_ranges[]=en. See Language selection.
user_intentNoA hint about what the searcher is looking for. See Search intent. Defaults to unknown.
fields[]NoResult kinds to include. The values are verses, topics, and images. Repeat the parameter to pass more than one, as in fields[]=verses&fields[]=images. Omit it to return every kind. Query metadata is always included.

Example Request

TerminalCode
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \ "https://api.youversion.com/v1/search-unified?query=love&bible_id=3034&language_ranges[]=en"

Example Response

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

Response Fields

FieldDescription
versesArray of verse results (reference only). See verse results are references.
topicsArray of related topics (id, text, subtopics).
imagesArray of related images. Each item has id and passage_id. Pass id to GET /v1/images/{image_id} for the image URL, attribution, and dimensions.
user_intentThe intent the search service resolved for the query. Nullable.
did_you_meanAlternative spellings suggested for the query.
search_instead_forA corrected query the results were returned for, if any. Nullable.

When nothing matches, this endpoint returns 200 OK with empty verses, topics, and images arrays. Query metadata is still included. The endpoint does not return 204. Check the array lengths to detect no results.

Search intent

user_intent is an optional hint that tells the service what kind of match you expect, which can sharpen the ranking:

ValueUse when…
unknownYou are not sure what the user wants. This is the default and is always safe.
textThe user is searching for words or phrases that appear in the verse text (e.g. love your enemies).
topicalThe user is exploring a theme or subject (e.g. anxiety, forgiveness).
referenceThe user typed a scripture reference (e.g. John 3:16, Romans 8).

If you are not confident about the intent, leave the parameter off or send unknown — do not guess, since a wrong hint can skew results.


GET /v1/search-verses

Search for Bible verses and page through the full result set. Like all verse results, responses carry references and metadata only, never passage text. The bible_id determines the language searched, so this endpoint takes no language parameter.

Endpoint URL

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

Query Parameters

ParameterRequiredDescription
queryYesThe search query string (1–100 characters).
bible_idYesThe Bible version identifier your app can access. Determines the language searched (e.g. 3034). See Verse search requires a Bible your app can access.
user_intentNoA hint about what the searcher is looking for. See Search intent. Defaults to unknown.
page_sizeNoNumber of verse results to return, between 1 and 99. Defaults to 25.
page_tokenNoThe next_page_token from a previous response, to fetch the next page.

Example Request

TerminalCode
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \ "https://api.youversion.com/v1/search-verses?query=love&bible_id=3034&page_size=25"

Example Response

Code
{ "verses": [ { "reference": "JHN.3.16" }, { "reference": "1JN.4.8" } ], "user_intent": "text", "did_you_mean": [], "search_instead_for": null, "next_page_token": "example-page-token" }

Fetching the Next Page

When next_page_token is non-null, send it back as page_token:

TerminalCode
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \ "https://api.youversion.com/v1/search-verses?query=love&bible_id=3034&page_token=example-page-token"

Response Fields

FieldDescription
versesArray of verse results (reference only).
user_intentThe intent the search service resolved for the query. Nullable.
did_you_meanAlternative spellings suggested for the query.
search_instead_forA corrected query the results were returned for, if any. Nullable.
next_page_tokenToken for the next page, or null when there are no more results.

When nothing matches, this endpoint returns 200 OK with an empty verses array (and next_page_token: null), not a 204.


GET /v1/search-topics

Return the set of topics related to a query, so a client can pivot to other verses in the same topic (for example, "show me more verses about this topic"). This endpoint is unpaginated — it returns a single fixed set of topics. Its response does not include user_intent; it carries only topics, did_you_mean, search_instead_for, and total_size.

Endpoint URL

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

Query Parameters

ParameterRequiredDescription
queryYesThe search query string (1–100 characters).
language_ranges[]YesOrdered list of language ranges (e.g. language_ranges[]=en).

Example Request

TerminalCode
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \ "https://api.youversion.com/v1/search-topics?query=love&language_ranges[]=en"

Example Response

Code
{ "topics": [ { "id": 42, "text": "love", "subtopics": ["trust", "belief"] } ], "did_you_mean": [], "search_instead_for": null, "total_size": 1 }

Response Fields

FieldDescription
topicsArray of related topics (id, text, subtopics). id is nullable.
did_you_meanAlternative spellings suggested for the query.
search_instead_forA corrected query the topics were returned for, if any. Nullable.
total_sizeThe number of topics returned. Because the endpoint is unpaginated, this is the full count, not a running total across pages.

When no topics match, this endpoint returns 200 OK with an empty topics array and total_size: 0, not a 204.

Pivoting to verses in a topic

Use a topic's text as the query for search-verses to find more verses on the same topic:

TerminalCode
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \ "https://api.youversion.com/v1/search-verses?query=faith&bible_id=3034"

GET /v1/search-images

Search for verse-art images by query and page through the results. bible_id selects the language, so this endpoint takes no language_ranges[] parameter. Each related image has an id and a passage_id.

Pass id to GET /v1/images/{image_id} before you render. Sizes, attribution, and the empty response are documented in Verse Images.

Endpoint URL

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

Query Parameters

ParameterRequiredDescription
queryYesThe search query string (1–100 characters).
bible_idYesThe Bible version identifier your app can access. Determines the language searched (e.g. 3034). See Verse search requires a Bible your app can access.
page_sizeNoNumber of image results to return, between 1 and 99. Defaults to 25.
page_tokenNoThe next_page_token from a previous response, to fetch the next page.

Example Request

TerminalCode
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \ "https://api.youversion.com/v1/search-images?query=love&bible_id=3034&page_size=25"

Example Response

Code
{ "images": [ { "id": "example-image-id", "passage_id": "1CO.13.4-8" } ], "next_page_token": "example-page-token" }

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. Reusing the token with different parameters returns 400 Invalid page_token. Set NEXT_PAGE_TOKEN to the next_page_token value from the previous response:

TerminalCode
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \ "https://api.youversion.com/v1/search-images?query=love&bible_id=3034&page_size=25&page_token=$NEXT_PAGE_TOKEN"

Response Fields

FieldDescription
imagesArray of image results. Each item has id and passage_id. Resolve id with GET /v1/images/{image_id}.
next_page_tokenToken for the next page, or null when there are no more results.

When nothing matches, image search returns 200 OK with images: [] and next_page_token: null. Continue when a page has a non-null token, even if its images array is empty.


GET /v1/search-queries

Return query objects — search strings a user might run — for as-you-type suggestions or trending searches. Suggested and trending share the same schema and are differentiated by parameters. This endpoint is unpaginated.

You must request exactly one of the two modes — language_ranges[] alone is not enough:

  • Suggested: supply query (with language_ranges[]) for as-you-type suggestions. There is no minimum-character restriction (character counts vary across non-Latin scripts, so suggestions are not gated on character position).
  • Trending: supply trending=true (with language_ranges[]) for recently popular searches. When trending=true, query is ignored.

Sending neither query nor trending=true returns 400 Either query (for suggestions) or trending=true is required.

Endpoint URL

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

Query Parameters

ParameterRequiredDescription
language_ranges[]YesOrdered list of language ranges (e.g. language_ranges[]=en). Use * to match all languages. The first supported range is used.
queryConditionallyThe partial query for as-you-type suggestions. Required unless trending=true. Ignored when trending=true.
trendingConditionallySet true to return recently popular searches instead of suggestions. Required unless query is supplied. Defaults to false.

Supply either query (for suggestions) or trending=true (for trending) — not neither.

Example Request — Suggested

TerminalCode
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \ "https://api.youversion.com/v1/search-queries?query=lo&language_ranges[]=en"

Example Request — Trending

TerminalCode
curl -H "X-YVP-App-Key: $YVP_APP_KEY" \ "https://api.youversion.com/v1/search-queries?trending=true&language_ranges[]=en"

Example Response

Code
{ "data": [ { "text": "love", "source": "trending" }, { "text": "loneliness", "source": "community" } ] }

Response Fields

FieldDescription
dataArray of query objects. Each has a text (the suggested or trending string) and an optional source (e.g. community or trending).

When there are no suggestions or no trending rows, this endpoint returns 204 No Content with an empty body — it does not return 200 with an empty data array. Check for the 204 before calling .json(), since parsing an empty body will throw.


Errors

The Search endpoints use the standard Platform error responses. Note that malformed parameters and semantic parameter conflicts return different status codes, so handle both:

StatusWhenExamples
400 Bad RequestA parameter is syntactically valid but rejected for a semantic reason.Invalid fields[] value; a language_ranges[] set with no supported language; search-queries called with neither query nor trending=true.
401 UnauthorizedMissing or invalid App Key.No X-YVP-App-Key header, or an unrecognized key. See Authentication.
404 Not FoundOn search-unified, search-verses, or search-images, the bible_id is not accessible to your app (unlicensed or not in the live catalog). This is not "the ID does not exist."bible_id your app is not entitled to. See Verse search requires a Bible your app can access.
422 Unprocessable ContentA parameter is missing or malformed. The body is a detail[] array, one entry per invalid parameter.Missing query, missing bible_id or language_ranges[], query outside 1–100 characters, invalid user_intent, page_size out of the 1–99 range.
429 Too Many RequestsRate limit exceeded.Check the Retry-After header before retrying.
502 Bad GatewayThe upstream search service is unavailable.Retry with backoff.

search-queries also returns 204 No Content (empty body) when there are no suggestions or trending rows — see GET /v1/search-queries.

For the exact response body shapes — including the detail[] validation array — see the error codes reference, especially Failed Validation for 422 bodies.

Need Help?

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

Last modified on November 17, 2026
Sign-in APIsVerse Images
On this page
  • Before You Start
  • Key Concepts
    • Verse results are references, never text
    • Verse search requires a Bible your app can access
    • Language selection
    • Query metadata
    • Pagination
  • GET /v1/search-unified
    • Endpoint URL
    • Query Parameters
    • Example Request
    • Example Response
    • Response Fields
    • Search intent
  • GET /v1/search-verses
    • Endpoint URL
    • Query Parameters
    • Example Request
    • Example Response
    • Fetching the Next Page
    • Response Fields
  • GET /v1/search-topics
    • Endpoint URL
    • Query Parameters
    • Example Request
    • Example Response
    • Response Fields
    • Pivoting to verses in a topic
  • GET /v1/search-images
    • Endpoint URL
    • Query Parameters
    • Example Request
    • Example Response
    • Fetching the Next Page
    • Response Fields
  • GET /v1/search-queries
    • Endpoint URL
    • Query Parameters
    • Example Request — Suggested
    • Example Request — Trending
    • Example Response
    • Response Fields
  • Errors
  • Need Help?
JSON
JSON
JSON
JSON
JSON