api.bible

Interface: IBibleApi

Implementation tier: T1 (foundation) / T2 (iterate, tokens)

Read Bible text, list modules and books, iterate over verses, parse references, register custom Bible text providers, and respond to verse navigation events.

Permissions

• bible:read
• bible:provide (for registerProvider)

Methods

getVerse

getVerse(verseId: number, opts?: { module?: string }): Promise<BibleVerseDto>

Get a single verse from the active or specified module.

Parameters:

Name	Type	Required	Description
verseId	number	Yes
opts	{ module?: string }	No

Returns: Promise<BibleVerseDto>

---

getRange

getRange(
  start: number,
  end: number,
  opts?: { module?: string },
): Promise<BibleVerseDto[]>

Get a range of verses (inclusive). Max range size: 500 verses.

Parameters:

Name	Type	Required	Description
start	number	Yes
end	number	Yes
opts	{ module?: string }	No

Returns: Promise<BibleVerseDto[]>

---

listModules

listModules(): Promise<BibleModuleInfoDto[]>

List installed Bible modules with metadata.

Returns: Promise<BibleModuleInfoDto[]>

---

listBooks

listBooks(moduleId?: string): Promise<BibleBookDto[]>

List the books in a Bible module (with chapter counts).

Parameters:

Name	Type	Required	Description
moduleId	string	No

Returns: Promise<BibleBookDto[]>

---

iterateVerses

iterateVerses(opts: IterateVersesOpts): Promise<VerseIterationResult>

Cursor-based iteration across verses. Required for extensions that need to scan the corpus (custom indexes, embeddings, alignment data). Max page size is 1000; the host may return fewer than requested. The host guarantees stable iteration order across calls with the same opts.

Parameters:

Name	Type	Required	Description
opts	IterateVersesOpts	Yes

Returns: Promise<VerseIterationResult>

---

parseReference

parseReference(
  input: string,
  locale?: string,
): Promise<ParsedReferenceDto | null>

Parse a reference string. Locale-aware.

Parameters:

Name	Type	Required	Description
input	string	Yes
locale	string	No

Returns: Promise<ParsedReferenceDto | null>

---

getVerseTokens

getVerseTokens(
  verseId: number,
  opts?: { module?: string },
): Promise<VerseTokenDto[] | null>

Get token-level data for a verse if the module exposes it (interlinear, Strong's, morphology). Returns null if the module has no token data.

Parameters:

Name	Type	Required	Description
verseId	number	Yes
opts	{ module?: string }	No

Returns: Promise<VerseTokenDto[] | null>

---

navigateToVerse

navigateToVerse(verseId: number): Promise<void>

Programmatically navigate the primary Bible pane to a specific verse. The host resolves after the renderer has processed the navigation request and fires onDidChangeActiveVerse once the verse is visible.

Requires bible:read permission (navigation is a read-adjacent action).

Parameters:

Name	Type	Required	Description
verseId	number	Yes

Returns: Promise<void>

---

registerProvider

registerProvider(provider: BibleProviderDescriptor): Promise<DisposableHandle>

Register a custom Bible text provider. The host treats it as another installed module. Requires bible:provide permission.

Parameters:

Name	Type	Required	Description
provider	BibleProviderDescriptor	Yes

Returns: Promise<DisposableHandle>

---

Events

onDidChangeActiveVerse

onDidChangeActiveVerse: IEventApi<{ verseId: number; module: string } | null>

Stable event: the user navigated to a new active verse anywhere in the app.

Payload type: { verseId: number; module: string } | null

Subscribe to this event:

const handle = await api.bible.onDidChangeActiveVerse.subscribe((payload) => {
  // Handle event
});

// Later, to unsubscribe:
await handle.dispose();

---

onDidSelectVerseWord

onDidSelectVerseWord: IEventApi<VerseWordSelection>

A token / word inside a verse was selected (click, double-click, or selection).

Payload type: VerseWordSelection

Subscribe to this event:

const handle = await api.bible.onDidSelectVerseWord.subscribe((payload) => {
  // Handle event
});

// Later, to unsubscribe:
await handle.dispose();

---