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.
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.
query Parameters
passage_idThe 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.
bible_idThe Bible version identifier
page_sizeThe 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.
page_tokenThe page token to retrieve results from.
List notes, optionally filtered by passage_id and bible_id. › Responses
Successful request
next_page_tokenToken to send to server when retrieving the next page of results.
Create a note.
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_idRequest UUID for idempotent create retries.
contentThe text content of the note.
statusWhether 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.
titleAn optional short title for the note.
color^[0-9a-f]{6}$The note's associated color in hex format.
passagelanguage_tag^[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).
tagsLabels to apply to this note.
Create a note. › Responses
Note created successfully
idThe unique identifier of the note.
contentThe text content of the note.
statusWhether 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.
titleAn optional short title for the note.
color^[0-9a-f]{6}$The note's associated color in hex format.
passagelanguage_tagThe 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).
tagsLabels the user has applied to this note.
created_dtWhen the note was created.
updated_dtWhen the note was last updated. Null if it has never been updated.
Get a note by id.
Get a single note belonging to the authenticated user by its id.
path Parameters
note_idThe unique identifier of the note.
Get a note by id. › Responses
Successful request
idThe unique identifier of the note.
contentThe text content of the note.
statusWhether 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.
titleAn optional short title for the note.
color^[0-9a-f]{6}$The note's associated color in hex format.
passagelanguage_tagThe 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).
tagsLabels the user has applied to this note.
created_dtWhen the note was created.
updated_dtWhen the note was last updated. Null if it has never been updated.
Update a note.
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.
path Parameters
note_idThe unique identifier of the note.
Update a note. › Request Body
titleAn optional short title for the note.
contentThe text content of the note.
color^[0-9a-f]{6}$The note's associated color in hex format.
passagelanguage_tag^[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).
tagsLabels to apply to this note.
statusWhether 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.
Update a note. › Responses
Note updated successfully
idThe unique identifier of the note.
contentThe text content of the note.
statusWhether 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.
titleAn optional short title for the note.
color^[0-9a-f]{6}$The note's associated color in hex format.
passagelanguage_tagThe 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).
tagsLabels the user has applied to this note.
created_dtWhen the note was created.
updated_dtWhen the note was last updated. Null if it has never been updated.