YouVersion PlatformYouVersion Platform
PlatformContent LibraryDev Docs
CommunityPartnersSupport

YouVersion Platform

Build applications and integrate with the world's most popular Bible platform.

Platform Products

  • Platform Portal
  • Developer Documentation
  • App Management

Resources

  • Support
  • Press inquiries

Legal

  • Privacy Policy
  • Terms of Use
  • Core Beliefs

© 2026 YouVersion. All rights reserved.

  • Overview
  • API Reference
  • SDKs
  • Changelog
<  Back to Platform
bibles
    Get a Bible collectiongetGet a Bible's datagetGet the index for a BiblegetGet a passage of Bible textgetGet a Book collection for a BiblegetGet a Book's datagetGet a Chapter collection for a BookgetGet a Chapter's datagetGet a Verse collection for a ChaptergetGet a Verse's dataget
data exchange
    Show the data exchange approval page.getComplete the data exchange approval flow.postCreate a data exchange token.post
fonts
    Get a collection of fonts supported in the Platform.getGet details about a specific font family in the Platform.getGet a browser-consumable stylesheet for a specific font family.get
highlights
    Get a collection of highlights for a user.getCreate or update a highlight on a passage.postClear highlights for a passage.delete
languages
    Get a collection of languages supported in the Platform.getGet details about a specific language in the Platform.get
licenses
    Get a collection of licensesgetGet the partner supplied licenses of a developerget
notes
    List notes, optionally filtered by passage_id and bible_id.getCreate a note.postGet a note by id.getDelete a note.deleteUpdate a note.patch
organizations
    Get a collection of organizations in the Platform.getGet details about a specific organization in the Platform.getGet bibles associated with a specific organization in the Platform.getGet video playlists associated with a specific organization in the Platform.getGet an organization video playlist by id.get
permissions
    Get permissions granted to an app.get
search
    Get suggested or trending search queries.getSearch the Platform for videos.getSearch the Platform for Bible verses, topics, images, and videos.getSearch the Platform for topics related to a query.getSearch the Platform for Bible verses.getSearch the Platform for verse images.get
verse of the days
    Get the verse of the day calendar for an entire year.getGet the verse of the day for a specific day of the year.get
videos
    Get a collection of videos.getGet a video resource by id.get
apps
    Get details about a specific app in the Platform.get
images
    List verse-art images, optionally filtered by language and/or verse.getResolve a verse-art image id to its full metadata.get
Schemas
Transformers
Transformers

notes

Endpoint

Endpoints for managing a user's notes, optionally attached to a passage of Scripture. Use these to list, create, update, and delete notes.

Every notes endpoint returns X-YVP-Correlation-Id on a successful response. It also returns the header on an error that the endpoint raised explicitly, for example a missing or insufficient OAuth scope, or "no such note". The header is absent from a 422 from request body or query validation. It is also absent from an unexpected 5xx that the endpoint did not raise itself.


List notes, optionally filtered by passage_id and bible_id.

GET
https://api.youversion.com
/v1/notes

Returns a paginated list of the authenticated user's notes, newest first. Optional passage_id and bible_id query parameters filter the list.

passage_id narrows the list to notes with an overlapping passage. A verse (JHN.3.16) matches notes that cover that verse. A verse range in one chapter (JHN.3.16-18) matches notes that share any of its verses. Same-chapter verses joined by + (JHN.3.16+JHN.3.18) match notes that share any of them. A chapter (JHN.3) matches notes anywhere in that chapter, in any Bible version. It returns 400 for a malformed value.

bible_id narrows the list to notes attached to that Bible translation. A note with no passage never matches it. When you set both, the endpoint combines passage_id and bible_id with AND. A well-formed bible_id that matches no notes is not an error.

A page can hold fewer than page_size notes, or none, while next_page_token is present. Keep following it until it is null. Every parameter except page_size must match the call that produced the page_token.

List notes, optionally filtered by passage_id and bible_id. › query Parameters

passage_id
​string

The passage identifier: a single verse or a verse range, e.g. JHN.3.16 or 1CO.13.4-7. Each operation's description states which forms it accepts.

Example: MAT.1.1
bible_id
​integer · int32

The Bible version identifier

Example: 3034
page_size
​integer · min: 1 · max: 99

The number of items to return in the collection. Must be between 1 and 99. Use the next_page_token from the response as page_token to retrieve the following page. Unlike page_size, this parameter has no unbounded * mode — collections using it are always paged.

Example: 25
Default: 25
page_token
​string

The page token to retrieve results from.

Example: eyJzdGFydF9hdCI6IDI2fQ==

List notes, optionally filtered by passage_id and bible_id. › Responses

Successful request

​object[] · readOnly · required
next_page_token
​string | null · readOnly

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

Example: eyJzdGFydF9hdCI6IDI2fQ==
GET/v1/notes
curl --request GET \ --url https://api.youversion.com/v1/notes
shell
Example Responses
{ "data": [ { "id": "40638", "title": "Morning reflection", "content": "This verse reminds me to trust the process.", "color": "44aa44", "passage": { "bible_id": 3034, "passage_id": "JHN.3.16" }, "language_tag": "en", "tags": [ "faith", "hope" ], "status": "private", "created_dt": "2026-10-23T17:00:00Z", "updated_dt": "2026-10-23T17:05:00Z" } ], "next_page_token": "eyJzdGFydF9hdCI6IDI2fQ==" }
json
application/json

Create a note.

POST
https://api.youversion.com
/v1/notes

Creates a new note for the authenticated user. request_id makes retries of the same create idempotent. A note attaches to at most one passage. An unrecognized field anywhere in the request body, including on passage, returns 400 instead of a silent drop.

Create a note. › Request Body

request_id
​string · uuid · required

Request UUID for idempotent create retries.

Example: 2f8c5d2e-6f6c-4b4f-9b36-8c1b5a17d3f9
content
​string · minLength: 1 · required

The text content of the note.

Example: This verse reminds me to trust the process.
status
​string · enum · required

Whether the note is visible only to its author (private) or to others (public). Other visibility states the backing service may hold (such as draft or friends) are not part of the YVP contract: values outside the enum are rejected with 400, a note in another state reads as 404, and lists never include them.

Enum values:
private
public
Example: private
title
​string | null

An optional short title for the note.

Example: Morning reflection
color
​string | null · pattern: ^[0-9a-f]{6}$

The note's associated color in hex format.

Example: 44aa44
passage
​object | null
language_tag
​string | null · pattern: ^[a-z]{2}(-[A-Z]{2})…

The language of this note: a two-letter ISO 639-1 code, optionally followed by a hyphen and a two-letter ISO 3166-1 region code (for example, en-US).

Example: en
tags
​array | null

Labels to apply to this note.

Example: ["faith","hope"]

Create a note. › Responses

Note created successfully

A note a user has written, optionally attached to a passage of Scripture.
id
​string · readOnly · required

The unique identifier of the note.

Example: 40638
content
​string · required

The text content of the note.

Example: This verse reminds me to trust the process.
status
​string · enum · required

Whether the note is visible only to its author (private) or to others (public). Other visibility states the backing service may hold (such as draft or friends) are not part of the YVP contract: values outside the enum are rejected with 400, a note in another state reads as 404, and lists never include them.

Enum values:
private
public
Example: private
title
​string | null

An optional short title for the note.

Example: Morning reflection
color
​string | null · pattern: ^[0-9a-f]{6}$

The note's associated color in hex format.

Example: 44aa44
passage
​object | null
language_tag
​string | null

The language of this note: a two-letter ISO 639-1 code, optionally followed by a hyphen and a two-letter ISO 3166-1 region code (for example, en-US).

Example: en
tags
​array | null

Labels the user has applied to this note.

Example: ["faith","hope"]
created_dt
​string · date-time · readOnly

When the note was created.

Example: 2026-10-23T17:00:00Z
updated_dt
​string | null · date-time · readOnly

When the note was last updated. Null if it has never been updated.

Example: 2026-10-23T17:05:00Z
POST/v1/notes
curl --request POST \ --url https://api.youversion.com/v1/notes \ --header 'Content-Type: application/json' \ --data ' { "request_id": "2f8c5d2e-6f6c-4b4f-9b36-8c1b5a17d3f9", "title": "Morning reflection", "content": "This verse reminds me to trust the process.", "color": "44aa44", "passage": { "bible_id": 3034, "passage_id": "JHN.3.16" }, "language_tag": "en", "tags": [ "faith", "hope" ], "status": "private" } '
shell
Example Request Body
{ "request_id": "2f8c5d2e-6f6c-4b4f-9b36-8c1b5a17d3f9", "title": "Morning reflection", "content": "This verse reminds me to trust the process.", "color": "44aa44", "passage": { "bible_id": 3034, "passage_id": "JHN.3.16" }, "language_tag": "en", "tags": [ "faith", "hope" ], "status": "private" }
json
Example Responses
{ "id": "40638", "title": "Morning reflection", "content": "This verse reminds me to trust the process.", "color": "44aa44", "passage": { "bible_id": 3034, "passage_id": "JHN.3.16" }, "language_tag": "en", "tags": [ "faith", "hope" ], "status": "private", "created_dt": "2026-10-23T17:00:00Z", "updated_dt": "2026-10-23T17:05:00Z" }
json
application/json

Get a note by id.

GET
https://api.youversion.com
/v1/notes/{note_id}

Get a single note belonging to the authenticated user by its id.

Get a note by id. › path Parameters

note_id
​string · required

The unique identifier of the note.

Example: 40638

Get a note by id. › Responses

Successful request

A note a user has written, optionally attached to a passage of Scripture.
id
​string · readOnly · required

The unique identifier of the note.

Example: 40638
content
​string · required

The text content of the note.

Example: This verse reminds me to trust the process.
status
​string · enum · required

Whether the note is visible only to its author (private) or to others (public). Other visibility states the backing service may hold (such as draft or friends) are not part of the YVP contract: values outside the enum are rejected with 400, a note in another state reads as 404, and lists never include them.

Enum values:
private
public
Example: private
title
​string | null

An optional short title for the note.

Example: Morning reflection
color
​string | null · pattern: ^[0-9a-f]{6}$

The note's associated color in hex format.

Example: 44aa44
passage
​object | null
language_tag
​string | null

The language of this note: a two-letter ISO 639-1 code, optionally followed by a hyphen and a two-letter ISO 3166-1 region code (for example, en-US).

Example: en
tags
​array | null

Labels the user has applied to this note.

Example: ["faith","hope"]
created_dt
​string · date-time · readOnly

When the note was created.

Example: 2026-10-23T17:00:00Z
updated_dt
​string | null · date-time · readOnly

When the note was last updated. Null if it has never been updated.

Example: 2026-10-23T17:05:00Z
GET/v1/notes/{note_id}
curl --request GET \ --url https://api.youversion.com/v1/notes/:note_id
shell
Example Responses
{ "id": "40638", "title": "Morning reflection", "content": "This verse reminds me to trust the process.", "color": "44aa44", "passage": { "bible_id": 3034, "passage_id": "JHN.3.16" }, "language_tag": "en", "tags": [ "faith", "hope" ], "status": "private", "created_dt": "2026-10-23T17:00:00Z", "updated_dt": "2026-10-23T17:05:00Z" }
json
application/json

Delete a note.

DELETE
https://api.youversion.com
/v1/notes/{note_id}

Delete a note belonging to the authenticated user.

Delete a note. › path Parameters

note_id
​string · required

The unique identifier of the note.

Example: 40638

Delete a note. › Responses

Note deleted successfully

No data returned
DELETE/v1/notes/{note_id}
curl --request DELETE \ --url https://api.youversion.com/v1/notes/:note_id
shell
Example Responses
No example specified for this content type

Update a note.

PATCH
https://api.youversion.com
/v1/notes/{note_id}

Partially updates a note. At least one field is required. Omitted fields keep their current value. A note attaches to at most one passage. Explicit null clears title, color, passage, language_tag, or tags. Content and status cannot be null, and the request returns 400 for an unrecognized field anywhere in the body, including on passage.

Update a note. › path Parameters

note_id
​string · required

The unique identifier of the note.

Example: 40638

Update a note. › Request Body

A partial update to a note. Only the fields present in the request body are changed; omitted fields keep their current value. At least one field is required. Explicit null clears title, color, passage, language_tag, and tags; null is not accepted for content or status.
title
​string | null

An optional short title for the note.

Example: Morning reflection
content
​string · minLength: 1

The text content of the note.

Example: This verse reminds me to trust the process.
color
​string | null · pattern: ^[0-9a-f]{6}$

The note's associated color in hex format.

Example: 44aa44
passage
​object | null
language_tag
​string | null · pattern: ^[a-z]{2}(-[A-Z]{2})…

The language of this note: a two-letter ISO 639-1 code, optionally followed by a hyphen and a two-letter ISO 3166-1 region code (for example, en-US).

Example: en
tags
​array | null

Labels to apply to this note.

Example: ["faith","hope"]
status
​string · enum

Whether the note is visible only to its author (private) or to others (public). Other visibility states the backing service may hold (such as draft or friends) are not part of the YVP contract: values outside the enum are rejected with 400, a note in another state reads as 404, and lists never include them.

Enum values:
private
public
Example: private

Update a note. › Responses

Note updated successfully

A note a user has written, optionally attached to a passage of Scripture.
id
​string · readOnly · required

The unique identifier of the note.

Example: 40638
content
​string · required

The text content of the note.

Example: This verse reminds me to trust the process.
status
​string · enum · required

Whether the note is visible only to its author (private) or to others (public). Other visibility states the backing service may hold (such as draft or friends) are not part of the YVP contract: values outside the enum are rejected with 400, a note in another state reads as 404, and lists never include them.

Enum values:
private
public
Example: private
title
​string | null

An optional short title for the note.

Example: Morning reflection
color
​string | null · pattern: ^[0-9a-f]{6}$

The note's associated color in hex format.

Example: 44aa44
passage
​object | null
language_tag
​string | null

The language of this note: a two-letter ISO 639-1 code, optionally followed by a hyphen and a two-letter ISO 3166-1 region code (for example, en-US).

Example: en
tags
​array | null

Labels the user has applied to this note.

Example: ["faith","hope"]
created_dt
​string · date-time · readOnly

When the note was created.

Example: 2026-10-23T17:00:00Z
updated_dt
​string | null · date-time · readOnly

When the note was last updated. Null if it has never been updated.

Example: 2026-10-23T17:05:00Z
PATCH/v1/notes/{note_id}
curl --request PATCH \ --url https://api.youversion.com/v1/notes/:note_id \ --header 'Content-Type: application/json' \ --data ' { "title": "Morning reflection", "content": "This verse reminds me to trust the process.", "color": "44aa44", "passage": { "bible_id": 3034, "passage_id": "JHN.3.16" }, "language_tag": "en", "tags": [ "faith", "hope" ], "status": "private" } '
shell
Example Request Body
{ "title": "Morning reflection", "content": "This verse reminds me to trust the process.", "color": "44aa44", "passage": { "bible_id": 3034, "passage_id": "JHN.3.16" }, "language_tag": "en", "tags": [ "faith", "hope" ], "status": "private" }
json
Example Responses
{ "id": "40638", "title": "Morning reflection", "content": "This verse reminds me to trust the process.", "color": "44aa44", "passage": { "bible_id": 3034, "passage_id": "JHN.3.16" }, "language_tag": "en", "tags": [ "faith", "hope" ], "status": "private", "created_dt": "2026-10-23T17:00:00Z", "updated_dt": "2026-10-23T17:05:00Z" }
json
application/json

licensesorganizations