The Search APIs let your app find Bible verses and related topics for a query, and surface suggested (as-you-type) and trending search queries. There are four endpoints, each tuned for a different job:
| Endpoint | Use it when you want… | Paginated |
|---|---|---|
GET /v1/search-results | One combined snapshot of top verses and topics 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-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
The verse-oriented endpoints (search-results and search-verses) 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, verse search 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 a specific Bible version and therefore the language searched. The verse-oriented endpoints (search-results,search-verses) use it and take no language parameter.language_ranges[]is an ordered list of RFC 4647 Basic language ranges. The topic- and query-oriented endpoints (search-results,search-topics,search-queries) use it. Ranges are matched by exact membership against the languages search supports, and the first supported range is used. Repeat the parameter to supply multiple ranges, in preference order:
Code
Supply concrete language tags. A bare wildcard (language_ranges[]=*) cannot resolve to a supported language and returns 400 None of the requested language_ranges are supported by search.
Query metadata
Every verse and unified-results response includes query metadata so you can build "did you mean" experiences. search-verses and search-results 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-results 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
Only search-verses is paginated, using page_size and page_token. When more results are available, its response includes a next_page_token; send it back as page_token in your next request. The search-results, search-topics, and search-queries endpoints are unpaginated — each returns a single fixed set of results with no page_size or page_token.
GET /v1/search-results
Search the Platform for Bible verses and related topics in a single call, returning one combined set of top results per kind. This is the best starting point for a general search box. It is unpaginated — when you need to page through the full set of verses or topics for a single kind, use search-verses or search-topics.
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 list of language ranges for topic results (e.g. language_ranges[]=en). |
user_intent | No | A hint about what the searcher is looking for. See Search intent. Defaults to unknown. |
fields[] | No | Result kinds to include: verses and/or topics. Repeat to pass multiple (fields[]=verses&fields[]=topics). Omit to return all kinds. 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). |
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 and topics arrays (query metadata is still included) — not a 204. Check the array lengths, not the status code, 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-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). 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 (including a bare *); 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-results / search-verses, 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.