YouVersion Platform provides SDKs for several popular coding languages, as well as the REST API which gives you direct access to the same services which power the SDKs. Use it when you need a fully custom integration, to automate content workflows, or to support platforms where an SDK is not yet available.
Before You Start
Create your developer account and register your application at platform.YouVersion.com. Accept the license agreements for the Bible versions you want to use.
App Keys
Copy the App Key from your app in the Platform Portal. Replace YOUR_APP_KEY_HERE
with that value and export it in your terminal:
Code
Send the key in the X-YVP-App-Key header for the content API requests in this guide:
Code
For user sign-in, follow Sign-in APIs. For a missing or invalid App Key, see Authentication Errors.
Base URL
The production content API base URL is https://api.youversion.com/v1.
Make Your First Request
Fetch the text of John 3:16 from the BSB using cURL:
Code
Or perform that same request with Python:
Code
Core Bible API Concepts
To get the Bible text for a given verse, passage or chapter, use the passages API as seen above.
Browse every endpoint and its response format in the interactive API reference.
Bible collections return their items in data. A request for one Bible returns the
Bible object directly.
If you are placing passage HTML on a web page, follow Display Bible HTML to add Bible CSS, the Fonts API stylesheet, and the required Bible version attribution. It includes both a direct REST example and a simpler JavaScript SDK path.
List Available Bible Versions
Use language_ranges[] to select languages. Repeat the parameter to supply more
than one preference; see Language ranges.
Code
Get Bible and Book Metadata
Get the BSB's metadata:
Code
List its books:
Code
List verse metadata for John chapter 3:
Code
Passage IDs
The passages API takes a passage_id in USFM format. It accepts four forms:
| Form | Example | Returns |
|---|---|---|
| Single verse | JHN.3.16 | John 3:16 |
| Verse range within one chapter | JHN.3.16-18 | John 3:16-18 |
| Whole chapter | JHN.3 | John chapter 3 |
| Book introduction | GEN.INTRO | The introduction to Genesis |
A range cannot cross a chapter boundary. A request for JHN.14.31-15.2 returns 404 Not Found with a message such as Bible passage JHN.14.31-15.2 for version 3034 not found.
To fetch a passage that spans chapters, request each chapter's verses separately and join the text in your app:
Code
Book identifiers such as JHN are listed in the USFM reference.
Pagination
Some endpoints support pagination using the page_size and page_token parameters.
You can request up to 99 items per page.
When more results are available, the response includes a next_page_token; send that back as page_token in your next request to fetch the following page.
Handle Errors and Rate Limits
Check the HTTP status before parsing a response body. The Error Codes guide covers response formats, App Key failures, and rate limits and retry handling.
For an SDK integration, start with the SDK overview.
Need Help?
If you need help integrating with our API or have questions about the documentation, please reach out to our support team.