Understanding Passage Spans

API.Bible lets you request a range of verses in a single API call—for example, Romans 8:1–11 or the entire Sermon on the Mount. This article explains how to format passage IDs, what limits apply, and what information is returned.

What a Passage Span Is

A passage span is a continuous range of verses defined by a start verse and an end verse. You specify the range using a Passage ID, which is created by joining the starting Verse ID and ending Verse ID with a hyphen:

{startVerseId}-{endVerseId}  

A few examples:

• JHN.3.1-JHN.3.16   — John 3:1 through John 3:16
• GEN.1.1-GEN.2.3   — Genesis 1:1 through Genesis 2:3
• 1CO.16.1-2CO.1.23   — 1 Corinthians 16:1 through 2 Corinthians 1:23

The start and end verses don't have to be in the same chapter — and as the last example shows, a passage span can even cross book boundaries.

The 200-Verse Limit

A single passage request returns a maximum of 200 verses. If your requested range is longer than 200 verses, the API will return the first 200 and stop there. Because the response is truncated at 200 verses, the returned id reflects the actual passage included in the response — not the range you asked for — so you can always check how far the result extends.

For example, requesting GEN.1.1-EXO.1.1   (all of Genesis) would return only the first 200 verses, with an id of GEN.1.1-GEN.8.16  . To retrieve the full text, you'd break the range into smaller chunks and make multiple requests in sequence.

What the Response Includes

A successful passage request returns all of the following in a single response:

• Content — the full text of every verse in the range, formatted as HTML, JSON, or plain text depending on the content-type   parameter you pass (HTML is the default)
• Reference — a human-readable citation for the full range, such as "John 3:1-16"
• Verse count — the number of verses included in the result
• Copyright notice — the attribution text required by the Bible publisher for display in your app

Passage vs. Individual Verse Requests

The main practical difference between the Passage endpoint and the Verse endpoint is scope. A passage request bundles an entire range of verses into one response and one API call. A verse request returns a single verse and includes additional metadata like navigation pointers (previous/next verse) and FUMS tracking data.

If your app is displaying a passage for reading — a pericope, a devotional text, or a longer Scripture block — the Passage endpoint is generally the best choice. If you're building verse-level navigation or need per-verse FUMS tracking, the Verse endpoint gives you more granular control. Using a Passage request is typically more efficient than making many individual Verse requests because the entire range is returned in a single API call.

In summary: A Passage ID is created by joining two Verse IDs, can span chapters or books, returns up to 200 verses in one request, and is the recommended endpoint for displaying longer sections of Scripture.