Getting Started

API Usage

Copy page

The REST API gives you direct access to the same Scripture catalogue that powers 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 an application.
• Copy the App Key that is generated for the app. The API expects it in the X-YVP-App-Key header for every request.
• Review the authentication guide if you need to act on behalf of a signed-in YouVersion user.

Choose an Environment

All URLs share the /v1 base path.

• Production: https://api.youversion.com/v1
• Development: https://api-dev.youversion.com/v1

The response includes standard rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining). Design your integration to back off when you are approaching the limit.

Make Your First Request

Fetch John 3:16 from the NIV using cURL:

Code
 
curl -H "X-YVP-App-Key: YOUR_APP_KEY" \
     https://api.youversion.com/v1/bibles/111/books/JHN/chapters/3/verses/16

The same request using JavaScript (Node.js):

Code
 
async function getVerse() {
  const response = await fetch("https://api.youversion.com/v1/bibles/111/books/JHN/chapters/3/verses/16", {
    headers: {
      "X-YVP-App-Key": "YOUR_APP_KEY"
    }
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return response.json();
}

getVerse().then(console.log).catch(console.error);

Or with Python:

Code
 
import requests

def get_verse():
    headers = {"X-YVP-App-Key": "YOUR_APP_KEY"}
    url = "https://api.youversion.com/v1/bibles/111/books/JHN/chapters/3/verses/16"
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()

print(get_verse())

Authenticate Users When Needed

Most Bible content only requires the App Key header. For user-scoped operations—such as accessing reading plans or profile information—perform a YouVersion sign-in to obtain an access token. Include it alongside your App Key:

Code
 
curl -H "X-YVP-App-Key: YOUR_APP_KEY" \
     -H "Authorization: Bearer USER_YVP_TOKEN" \
     https://api.youversion.com/v1/user/profile

Explore Core Endpoints

Common patterns while building with the API:

Code
 
# List available Bible versions
curl -H "X-YVP-App-Key: YOUR_APP_KEY" \
     https://api.youversion.com/v1/bibles

# List books in a specific Bible
curl -H "X-YVP-App-Key: YOUR_APP_KEY" \
     https://api.youversion.com/v1/bibles/111/books

# Fetch an entire chapter
curl -H "X-YVP-App-Key: YOUR_APP_KEY" \
     https://api.youversion.com/v1/bibles/111/books/MAT/chapters/1/verses

Browse every route, schema, and sample payload from the interactive API reference.

Handle Errors Gracefully

Inspect the HTTP status code, then log or surface the error message returned by the API. This JavaScript example retries API calls once on transient failures:

Code
 
async function getBibles(retryCount = 0) {
  const response = await fetch("https://api.youversion.com/v1/bibles", {
    headers: {
      "X-YVP-App-Key": "YOUR_APP_KEY"
    }
  });

  if (!response.ok) {
    if (response.status >= 500 && retryCount < 1) {
      return getBibles(retryCount + 1);
    }

    const errorBody = await response.text();
    throw new Error(`Request failed (${response.status}): ${errorBody}`);
  }

  return response.json();
}

Common Parameters

Language Ranges

When requesting Bible versions, you can specify language preferences:

Code
 
curl -H "X-YVP-App-Key: YOUR_APP_KEY" \
     "https://api.youversion.com/v1/bibles?language_ranges=en,es,fr"

Pagination

Many endpoints support pagination using the next_page_token parameter:

Code
 
curl -H "X-YVP-App-Key: YOUR_APP_KEY" \
     "https://api.youversion.com/v1/bibles?next_page_token=2"

Need Help?

Reach out to the YouVersion Platform support team from the developer portal if you run into issues or have feature requests. The team can help with rate-limit increases, data questions, or onboarding guidance.