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:
| Endpoint | Use it when you want… | Paginated |
|---|---|---|
GET /v1/search-unified | One combined set of top verses, topics, and images for a query | No |
GET /v1/search-verses | To page through the full list of matching verses | Yes |
GET /v1/search-topics | The full set of topics related to a query, to pivot to other verses on the same topic | No |
GET /v1/search-images | To page through the verse images that match a query | Yes |
GET /v1/search-queries | Suggested (as-you-type) or trending search strings | 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-Keyheader. See Authentication for details.
Code
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_idselects the Bible version and the language for verse results.search-unified,search-verses, andsearch-imagesrequire it.search-versesandsearch-imagestake 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 bysearch-unified,search-topics, andsearch-queries. Suggested and trending queries both usesearch-queries. Repeat the parameter for multiple preferences, in preference order:
Code
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).
| Field | Description |
|---|---|
user_intent | The intent the search service resolved for the query (unknown, topical, text, or reference). Nullable. Returned by search-verses and search-unified only. |
did_you_mean | Alternative spellings the search service suggests for the query (array of strings; empty when there are none). |
search_instead_for | A 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
Query Parameters
| Parameter | Required | Description |
|---|---|---|
query | Yes | The search query string (1–100 characters). |
bible_id | Yes | The 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[] | Yes | Ordered language ranges for the request, such as language_ranges[]=en. See Language selection. |
user_intent | No | A hint about what the searcher is looking for. See Search intent. Defaults to unknown. |
fields[] | No | Result 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
Code
Example Response
Code
Response Fields
| Field | Description |
|---|---|
verses | Array of verse results (reference only). See verse results are references. |
topics | Array of related topics (id, text, subtopics). |
images | Array 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_intent | The intent the search service resolved for the query. Nullable. |
did_you_mean | Alternative spellings suggested for the query. |
search_instead_for | A 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:
| Value | Use when… |
|---|---|
unknown | You are not sure what the user wants. This is the default and is always safe. |
text | The user is searching for words or phrases that appear in the verse text (e.g. love your enemies). |
topical | The user is exploring a theme or subject (e.g. anxiety, forgiveness). |
reference | The 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
Query Parameters
| Parameter | Required | Description |
|---|---|---|
query | Yes | The search query string (1–100 characters). |
bible_id | Yes | The 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_intent | No | A hint about what the searcher is looking for. See Search intent. Defaults to unknown. |
page_size | No | Number of verse results to return, between 1 and 99. Defaults to 25. |
page_token | No | The next_page_token from a previous response, to fetch the next page. |
Example Request
Code
Example Response
Code
Fetching the Next Page
When next_page_token is non-null, send it back as page_token:
Code
Response Fields
| Field | Description |
|---|---|
verses | Array of verse results (reference only). |
user_intent | The intent the search service resolved for the query. Nullable. |
did_you_mean | Alternative spellings suggested for the query. |
search_instead_for | A corrected query the results were returned for, if any. Nullable. |
next_page_token | Token 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
Query Parameters
| Parameter | Required | Description |
|---|---|---|
query | Yes | The search query string (1–100 characters). |
language_ranges[] | Yes | Ordered list of language ranges (e.g. language_ranges[]=en). |
Example Request
Code
Example Response
Code
Response Fields
| Field | Description |
|---|---|
topics | Array of related topics (id, text, subtopics). id is nullable. |
did_you_mean | Alternative spellings suggested for the query. |
search_instead_for | A corrected query the topics were returned for, if any. Nullable. |
total_size | The 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:
Code
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
Query Parameters
| Parameter | Required | Description |
|---|---|---|
query | Yes | The search query string (1–100 characters). |
bible_id | Yes | The 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_size | No | Number of image results to return, between 1 and 99. Defaults to 25. |
page_token | No | The next_page_token from a previous response, to fetch the next page. |
Example Request
Code
Example Response
Code
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:
Code
Response Fields
| Field | Description |
|---|---|
images | Array of image results. Each item has id and passage_id. Resolve id with GET /v1/images/{image_id}. |
next_page_token | Token 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(withlanguage_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(withlanguage_ranges[]) for recently popular searches. Whentrending=true,queryis ignored.
Sending neither query nor trending=true returns 400 Either query (for suggestions) or trending=true is required.
Endpoint URL
Code
Query Parameters
| Parameter | Required | Description |
|---|---|---|
language_ranges[] | Yes | Ordered list of language ranges (e.g. language_ranges[]=en). Use * to match all languages. The first supported range is used. |
query | Conditionally | The partial query for as-you-type suggestions. Required unless trending=true. Ignored when trending=true. |
trending | Conditionally | Set 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
Code
Example Request — Trending
Code
Example Response
Code
Response Fields
| Field | Description |
|---|---|
data | Array 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:
| Status | When | Examples |
|---|---|---|
400 Bad Request | A 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 Unauthorized | Missing or invalid App Key. | No X-YVP-App-Key header, or an unrecognized key. See Authentication. |
404 Not Found | On 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 Content | A 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 Requests | Rate limit exceeded. | Check the Retry-After header before retrying. |
502 Bad Gateway | The 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.