Transformers

Schemas

AppSummary

A public app summary resource.

app_id

string · uuid · readOnly · required

name

string · readOnly · required

description

string

website_url

string

status

string · enum

Enum values:

development

live

archived

AppSummaries

A collection of public app summary resources.

object[] · required

Bible

id

integer · readOnly

Bible version identifier

Example: 3034

abbreviation

string · readOnly

Bible version abbreviation

Example: BSB

promotional_content

string · readOnly

Longer form of copyright text provided by the publisher for the given Bible version.

Example: "https://berean.bible/"

copyright

string · readOnly

Short version of the copyright text provided by the publisher for the given Bible version.

Example: "The Holy Bible, Berean Standard Bible, BSB is produced in cooperation with Bible Hub, Discovery Bible, OpenBible.com, and the Berean Bible Translation Committee. This text of God's Word has been dedicated to the public domain."

info

string · readOnly

Additional information about the Bible text version. This is commonly displayed in the reader footer for the Bible.

Example: The Holy Bible

publisher_url

string · readOnly

URL to link to publisher page from the reader's footer

Example:

language_tag

string · readOnly

BCP47 canonical language tag for this Bible version

Example: en

localized_abbreviation

string · readOnly

Localized Bible version abbreviation

Example: BSB

localized_title

string · readOnly

Localized title of Bible version

Example: English: Berean Standard Bible

title

string · readOnly

English title of Bible version

Example: Berean Standard Bible

books

string[] · readOnly

youversion_deep_link

string · readOnly

A deep link to this Bible version inside YouVersion

Example: https://www.bible.com/versions/3034

organization_id

string | null · uuid

BibleIndex

text_direction

string

object[]

Bibles

object[] · readOnly · required

next_page_token

string · readOnly

Token to send to server when retrieving the next page of results.

Example: eyJzdGFydF9hdCI6IDI2fQ==

total_size

integer · int32

Total number of bibles in collection matching parameters.

Example: 42

Book

id

string

Book identifier

Example: GEN

title

string

Book title

Example: Genesis

full_title

string

Full book title if available

Example: The Book of Genesis

abbreviation

string

Book name abbreviation if provided by the publisher

Example: Gen.

canon

string · enum

Canon identifier

Enum values:

new_testament

old_testament

deuterocanon

Example: old_testament

object[]

Chapters in the book

intro

object | null

Books

object[] · readOnly · required

Chapter

id

string

Chapter identifier

Example: 1

passage_id

string

Passage identifier

Example: GEN.1

title

string

Chapter title

Example: 1

object[]

Verses in the chapter

Chapters

object[] · readOnly · required

DataExchangeToken

token

string · required

Opaque single-use token for the data exchange flow. Returned only once.

token_type

string · enum · required

Enum values:

data_exchange

Example: data_exchange

expires_in

integer · int32 · required

Token lifetime in seconds.

Example: 300

DataExchangeTokenCreate

permissions

string[] · minItems: 1 · required

Data exchange permissions for this token.

Enum values:

highlights

Error

message

string · required

Error message

Font

A font family resource with available variants and CDN-backed source files.

id

integer · int32 · required

Stable integer identifier for the font family.

Example: 1

slug

string · required

Stable URL-safe identifier for the font family.

Example: untitled-serif

family

string · required

Canonical font-family name clients should use.

Example: Untitled Serif

object[] · required

Available faces within this font family.

Fonts

object[] · readOnly · required

FontSource

format

string · enum · required

The file format for this source asset.

Enum values:

woff2

ttf

Example: woff2

url

string · uri · required

Fully qualified CDN URL for this font source file.

Example: https://cdn.youversion.com/fonts/untitled-serif/Untitled%20Serif.woff2

FontVariant

weight

integer · enum · int32 · required

Numeric font weight for this variant.

Enum values:

400

500

700

Example: 400

style

string · enum · required

Font style for this variant.

Enum values:

normal

italic

Example: normal

object[] · required

CDN assets available for this specific weight and style.

Highlight

bible_id

integer · int32 · required

Bible version identifier

Example: 3034

passage_id

string · required

The passage identifier (verse USFM format)

Example: MAT.1.1

color

string · pattern: ^[0-9a-f]{6}$ · required

The highlight color in hex format

Example: 44aa44

id

string

The Highlight resource identifier

Example: ZXlKaUlqb3hNVEVzSW1NaU9pSmhZV0ZoWVdFaWZR

HighlightCreateRequest

request_id

string · uuid · required

Request UUID for idempotent create retries.

Example: 2f8c5d2e-6f6c-4b4f-9b36-8c1b5a17d3f9

object · required

Highlights

object[] · readOnly

Language

Region-agnostic language resource keyed by canonical BCP 47 language or language+script. Variants and a simple extensions indicator are included for completeness, but regions and full extension data are excluded.

id

string · pattern: ^[a-z]{2,3}(?:-[A-Z]… · required

Canonical BCP 47 id limited to language or language+script. Region, variants, and extensions are not allowed.

Example: en

language

string · pattern: ^[a-z]{2,3}$ · required

ISO 639 canonical language subtag

Example: sr

script

string | null · pattern: ^[A-Z][a-z]{3}$

ISO 15924 script code if present in id

Example: Latn

script_name

string | null

The English name for the script

Example: Latin

aliases

string[]

Deprecated or legacy subtags mapped during canonicalization for this language.

Example: []

object

Localized display names for the language/script combination

scripts

string[]

All scripts known for this language (CLDR/ISO-15924)

Example: ["Cyrl","Latn"]

variants

string[]

Variants associated with this language (not part of the id)

Example: ["1996","fonipa"]

countries

string[]

Ids of countries where this language is used or supported. Extended details can be retrieved from the countries API with the provided id.

Example: ["RS","BA","ME"]

text_direction

string · enum

Default text direction for this language. ltr is left to right and rtl is right to left.

Enum values:

ltr

rtl

Example: rtl

writing_population

integer · int32

Estimated number of souls that write in this language.

Example: 1327104050

speaking_population

integer · int32

Estimated number of souls that speak in this language.

Example: 1636485840

default_bible_id

integer · int32

The chosen default Bible version for this language.

Example: 3034

Languages

object[] · readOnly · required

next_page_token

string · readOnly

Token to send to server when retrieving the next page of results.

Example: eyJzdGFydF9hdCI6IDI2fQ==

total_size

integer · int32

Total number of languages in collection matching parameters.

Example: 6000

License

id

integer

name

string

version

integer

organization_id

string · uuid

The YouVersion Organization ID that owns this license.

html

string

HTML representation of the license terms.

bible_ids

integer[]

uri

string | null · uri

URI pointing to the license terms.

agreed_dt

string · date-time

The date which the developer id passed agreed to this license or null if not agreed to

yvp_user_id

string · uuid

The YouVersion Platform User id that was logged into the dev portal and agreed to the license

Licenses

object[] · readOnly · required

Organization

The Organization Resource in the Platform.

id

string · uuid · required

The unique identifier of the organization in the Platform.

Example: 550e8400-e29b-41d4-a716-446655440000

parent_organization_id

string | null · uuid

The id of the parent organization if one exists.

Example: 550e8400-e29b-41d4-a716-446655440000

name

string

Publisher's name in the language negotiated by Accept-Language headers. If none match known translations, then the primary language of the publisher is used. Whichever language is chosen will be sent back in the Content-Language header.

Example: Biblica, Inc.

description

string

Description of the organization. It's purpose and goals, values and mission, etc.

Example: This is a lorem ipsum description of the organization and its purpose and goals and what it does and what it does not do.

email

string | null

The contact email address for the organization if provided.

phone

string | null

The contact phone number for the organization if provided.

primary_language

string

The primary language of the organization.

Example: en

website_url

string

The web site for the organization.

Example: https://www.biblica.com

object

The Address Schema belonging to the Organization Resource in the Platform.

Organizations

object[] · readOnly · required

next_page_token

string · readOnly

Token to send to server when retrieving the next page of results.

Example: eyJzdGFydF9hdCI6IDI2fQ==

Passage

id

string · readOnly

A canonical representation of the passage returned

Example: MAT.1.1

content

string · readOnly

The Bible text of the requested passage in either text or html format.

Example: The book of the genealogy of Jesus Christ, the son of David, the son of Abraham.

reference

string · readOnly

A human-readable reference

Example: Matthew 1:1

Playlist

id

integer · readOnly · required

Playlist identifier.

Example: 3669

title

string · readOnly · required

Playlist title.

Example: Teaching Clips

type

string · readOnly · required

Playlist type mapped from upstream playlist_type.

Example: TEACHING_CLIPS

total

integer · readOnly · required

Total number of items in the playlist.

Example: 39

videos

integer[] · readOnly · required

Ordered video ids in the playlist.

Example: [52186,51575]

Playlists

object[] · readOnly · required

next_page_token

string · readOnly

Token to send to server when retrieving the next page of results.

Example: eyJzdGFydF9hdCI6IDI2fQ==

Verse

id

string

Verse identifier

Example: 1

passage_id

string

Passage identifier

Example: GEN.1.1

title

string

Verse title

Example: 1

Verses

object[] · readOnly · required

VerseOfTheDay

day

integer · min: 1 · max: 366 · required

passage_id

string · required

The passage identifier

Example: JHN.3.16

VerseOfTheDays

object[] · required

Video

id

integer · readOnly · required

Video identifier.

Example: 52186

object[] · readOnly · required

Playable video or audio sources.

object[] · readOnly · required

Preview clip sources.

title

string | null · readOnly

Video title.

Example: 1 Samuel 17:45

description

string | null · readOnly

Video description.

Example: Teaching clip description.

references

array | null · readOnly

Bible references associated with the video.

Example: ["1SA.17.45"]

language_tag

string | null · readOnly

BCP 47 language tag for the video.

Example: en

runtime

integer | null · readOnly

Runtime in seconds.

Example: 105

orientation

string | null · enum · readOnly

Video orientation.

Enum values:

landscape

portrait

Example: portrait

object

share_url

string | null · readOnly

Share URL for the video.

Example: https://www.bible.com/en/videos/52186

VideoPlaybackSource

url

string · readOnly · required

URL for the playable video or audio source.

Example: https://video-cdn.youversionapi.com/path/to/asset.ext

format

string · enum · readOnly · required

Source format.

Enum values:

hls

webm

mp4

mp3

Example: hls

VideoThumbnail

url

string | null · readOnly

URL for the thumbnail image.

Example: https://imageproxy.youversionapi.com/640x360/https://storage.googleapis.com/service.youversionapi.com/path/to/image.jpg

width

integer | null · readOnly

Thumbnail width in pixels.

Example: 640

height

integer | null · readOnly

Thumbnail height in pixels.

Example: 360

Transformers

Schemas

AppSummary

A public app summary resource.

app_id

string · uuid · readOnly · required

name

string · readOnly · required

description

string

website_url

string

status

string · enum

Enum values:

development

live

archived

AppSummaries

A collection of public app summary resources.

object[] · required

Bible

id

integer · readOnly

Bible version identifier

Example: 3034

abbreviation

string · readOnly

Bible version abbreviation

Example: BSB

promotional_content

string · readOnly

Longer form of copyright text provided by the publisher for the given Bible version.

Example: "https://berean.bible/"

copyright

string · readOnly

Short version of the copyright text provided by the publisher for the given Bible version.

info

string · readOnly

Additional information about the Bible text version. This is commonly displayed in the reader footer for the Bible.

Example: The Holy Bible

publisher_url

string · readOnly

URL to link to publisher page from the reader's footer

Example:

language_tag

string · readOnly

BCP47 canonical language tag for this Bible version

Example: en

localized_abbreviation

string · readOnly

Localized Bible version abbreviation

Example: BSB

localized_title

string · readOnly

Localized title of Bible version

Example: English: Berean Standard Bible

title

string · readOnly

English title of Bible version

Example: Berean Standard Bible

books

string[] · readOnly

youversion_deep_link

string · readOnly

A deep link to this Bible version inside YouVersion

Example: https://www.bible.com/versions/3034

organization_id

string | null · uuid

BibleIndex

text_direction

string

object[]

Bibles

object[] · readOnly · required

next_page_token

string · readOnly

Token to send to server when retrieving the next page of results.

Example: eyJzdGFydF9hdCI6IDI2fQ==

total_size

integer · int32

Total number of bibles in collection matching parameters.

Example: 42

Book

id

string

Book identifier

Example: GEN

title

string

Book title

Example: Genesis

full_title

string

Full book title if available

Example: The Book of Genesis

abbreviation

string

Book name abbreviation if provided by the publisher

Example: Gen.

canon

string · enum

Canon identifier

Enum values:

new_testament

old_testament

deuterocanon

Example: old_testament

object[]

Chapters in the book

intro

object | null

Books

object[] · readOnly · required

Chapter

id

string

Chapter identifier

Example: 1

passage_id

string

Passage identifier

Example: GEN.1

title

string

Chapter title

Example: 1

object[]

Verses in the chapter

Chapters

object[] · readOnly · required

DataExchangeToken

token

string · required

Opaque single-use token for the data exchange flow. Returned only once.

token_type

string · enum · required

Enum values:

data_exchange

Example: data_exchange

expires_in

integer · int32 · required

Token lifetime in seconds.

Example: 300

DataExchangeTokenCreate

permissions

string[] · minItems: 1 · required

Data exchange permissions for this token.

Enum values:

highlights

Error

message

string · required

Error message

Font

A font family resource with available variants and CDN-backed source files.

id

integer · int32 · required

Stable integer identifier for the font family.

Example: 1

slug

string · required

Stable URL-safe identifier for the font family.

Example: untitled-serif

family

string · required

Canonical font-family name clients should use.

Example: Untitled Serif

object[] · required

Available faces within this font family.

Fonts

object[] · readOnly · required

FontSource

format

string · enum · required

The file format for this source asset.

Enum values:

woff2

ttf

Example: woff2

url

string · uri · required

Fully qualified CDN URL for this font source file.

Example: https://cdn.youversion.com/fonts/untitled-serif/Untitled%20Serif.woff2

FontVariant

weight

integer · enum · int32 · required

Numeric font weight for this variant.

Enum values:

400

500

700

Example: 400

style

string · enum · required

Font style for this variant.

Enum values:

normal

italic

Example: normal

object[] · required

CDN assets available for this specific weight and style.

Highlight

bible_id

integer · int32 · required

Bible version identifier

Example: 3034

passage_id

string · required

The passage identifier (verse USFM format)

Example: MAT.1.1

color

string · pattern: ^[0-9a-f]{6}$ · required

The highlight color in hex format

Example: 44aa44

id

string

The Highlight resource identifier

Example: ZXlKaUlqb3hNVEVzSW1NaU9pSmhZV0ZoWVdFaWZR

HighlightCreateRequest

request_id

string · uuid · required

Request UUID for idempotent create retries.

Example: 2f8c5d2e-6f6c-4b4f-9b36-8c1b5a17d3f9

object · required

Highlights

object[] · readOnly

Language

id

string · pattern: ^[a-z]{2,3}(?:-[A-Z]… · required

Canonical BCP 47 id limited to language or language+script. Region, variants, and extensions are not allowed.

Example: en

language

string · pattern: ^[a-z]{2,3}$ · required

ISO 639 canonical language subtag

Example: sr

script

string | null · pattern: ^[A-Z][a-z]{3}$

ISO 15924 script code if present in id

Example: Latn

script_name

string | null

The English name for the script

Example: Latin

aliases

string[]

Deprecated or legacy subtags mapped during canonicalization for this language.

Example: []

object

Localized display names for the language/script combination

scripts

string[]

All scripts known for this language (CLDR/ISO-15924)

Example: ["Cyrl","Latn"]

variants

string[]

Variants associated with this language (not part of the id)

Example: ["1996","fonipa"]

countries

string[]

Ids of countries where this language is used or supported. Extended details can be retrieved from the countries API with the provided id.

Example: ["RS","BA","ME"]

text_direction

string · enum

Default text direction for this language. ltr is left to right and rtl is right to left.

Enum values:

ltr

rtl

Example: rtl

writing_population

integer · int32

Estimated number of souls that write in this language.

Example: 1327104050

speaking_population

integer · int32

Estimated number of souls that speak in this language.

Example: 1636485840

default_bible_id

integer · int32

The chosen default Bible version for this language.

Example: 3034

Languages

object[] · readOnly · required

next_page_token

string · readOnly

Token to send to server when retrieving the next page of results.

Example: eyJzdGFydF9hdCI6IDI2fQ==

total_size

integer · int32

Total number of languages in collection matching parameters.

Example: 6000

License

id

integer

name

string

version

integer

organization_id

string · uuid

The YouVersion Organization ID that owns this license.

html

string

HTML representation of the license terms.

bible_ids

integer[]

uri

string | null · uri

URI pointing to the license terms.

agreed_dt

string · date-time

The date which the developer id passed agreed to this license or null if not agreed to

yvp_user_id

string · uuid

The YouVersion Platform User id that was logged into the dev portal and agreed to the license

Licenses

object[] · readOnly · required

Organization

The Organization Resource in the Platform.

id

string · uuid · required

The unique identifier of the organization in the Platform.

Example: 550e8400-e29b-41d4-a716-446655440000

parent_organization_id

string | null · uuid

The id of the parent organization if one exists.

Example: 550e8400-e29b-41d4-a716-446655440000

name

string

Example: Biblica, Inc.

description

string

Description of the organization. It's purpose and goals, values and mission, etc.

Example: This is a lorem ipsum description of the organization and its purpose and goals and what it does and what it does not do.

email

string | null

The contact email address for the organization if provided.

phone

string | null

The contact phone number for the organization if provided.

primary_language

string

The primary language of the organization.

Example: en

website_url

string

The web site for the organization.

Example: https://www.biblica.com

object

The Address Schema belonging to the Organization Resource in the Platform.

Organizations

object[] · readOnly · required

next_page_token

string · readOnly

Token to send to server when retrieving the next page of results.

Example: eyJzdGFydF9hdCI6IDI2fQ==

Passage

id

string · readOnly

A canonical representation of the passage returned

Example: MAT.1.1

content

string · readOnly

The Bible text of the requested passage in either text or html format.

Example: The book of the genealogy of Jesus Christ, the son of David, the son of Abraham.

reference

string · readOnly

A human-readable reference

Example: Matthew 1:1

Playlist

id

integer · readOnly · required

Playlist identifier.

Example: 3669

title

string · readOnly · required

Playlist title.

Example: Teaching Clips

type

string · readOnly · required

Playlist type mapped from upstream playlist_type.

Example: TEACHING_CLIPS

total

integer · readOnly · required

Total number of items in the playlist.

Example: 39

videos

integer[] · readOnly · required

Ordered video ids in the playlist.

Example: [52186,51575]

Playlists

object[] · readOnly · required

next_page_token

string · readOnly

Token to send to server when retrieving the next page of results.

Example: eyJzdGFydF9hdCI6IDI2fQ==

Verse

id

string

Verse identifier

Example: 1

passage_id

string

Passage identifier

Example: GEN.1.1

title

string

Verse title

Example: 1

Verses

object[] · readOnly · required

VerseOfTheDay

day

integer · min: 1 · max: 366 · required

passage_id

string · required

The passage identifier

Example: JHN.3.16

VerseOfTheDays

object[] · required

Video

id

integer · readOnly · required

Video identifier.

Example: 52186

object[] · readOnly · required

Playable video or audio sources.

object[] · readOnly · required

Preview clip sources.

title

string | null · readOnly

Video title.

Example: 1 Samuel 17:45

description

string | null · readOnly

Video description.

Example: Teaching clip description.

references

array | null · readOnly

Bible references associated with the video.

Example: ["1SA.17.45"]

language_tag

string | null · readOnly

BCP 47 language tag for the video.

Example: en

runtime

integer | null · readOnly

Runtime in seconds.

Example: 105

orientation

string | null · enum · readOnly

Video orientation.

Enum values:

landscape

portrait

Example: portrait

object

share_url

string | null · readOnly

Share URL for the video.

Example: https://www.bible.com/en/videos/52186

VideoPlaybackSource

url

string · readOnly · required

URL for the playable video or audio source.

Example: https://video-cdn.youversionapi.com/path/to/asset.ext

format

string · enum · readOnly · required

Source format.

Enum values:

hls

webm

mp4

mp3

Example: hls

VideoThumbnail

url

string | null · readOnly

URL for the thumbnail image.

Example: https://imageproxy.youversionapi.com/640x360/https://storage.googleapis.com/service.youversionapi.com/path/to/image.jpg

width

integer | null · readOnly

Thumbnail width in pixels.

Example: 640

height

integer | null · readOnly

Thumbnail height in pixels.

Example: 360