Extension API Reference

The extension API is injected into every extension worker as the api parameter in the activate(api) entry point. Each property on the API object is a namespace providing related functionality.

export function activate(api: BibleExtensionAPI) {
  // api.bible, api.commentary, api.ui, etc.
}

Namespaces

Namespace	Interface	Description
api.ai	IAiApi	Reserved namespace for AI integration.
api.auth	IAuthApi	OAuth 2.0 Authorization Code flow with PKCE, token refresh, and opening external URLs.
api.bible	IBibleApi	Read Bible text, list modules and books, iterate over verses, parse references, register custom Bible text providers, and respond to verse navigation events.
api.book	IBookApi	Read book sections, list book modules and their table of contents, iterate sections, and register custom book providers.
api.bookmarks	IBookmarksApi	Manage verse bookmarks and bookmark collections.
api.commands	ICommandsApi	Register extension commands that appear in the command palette and can be bound to keyboard shortcuts.
api.commentary	ICommentaryApi	Read commentary entries, list commentary modules, iterate over entries, and register custom commentary providers.
api.context	IContextApi	Read and write when-context keys used for conditional UI (when-clauses).
api.dictionary	IDictionaryApi	Look up dictionary entries, search dictionaries, list modules, iterate entries, and register custom dictionary providers.
api.events	IEventsApi	Subscribe to host-emitted extension point events (verse rendering, content module hooks, search hooks, workspace lifecycle, etc.).
api.extensions	IExtensionsApi	Call methods exported by other extensions (inter-extension RPC), check activation status, and list API providers.
api.highlights	IHighlightsApi	Create, read, update, and delete verse highlights.
api.l10n	IL10nApi	Localization helpers: resolve translation keys from the extension's catalog and detect locale changes.
api.network	INetworkApi	Make outbound HTTP/HTTPS requests.
api.notes	INotesApi	Create, read, update, and delete user notes.
api.storage	IStorageApi	Key-value storage, OS keychain secrets, read-only settings mirror, and per-extension SQLite databases.
api.tasks	ITasksApi	Run long-running background tasks with progress reporting, cancellation support, and status bar integration.
api.ui	IUiApi	Contribute UI elements: panels, verse decorators, hover providers, context menu items, display modes, status bar items, notifications, quick-picks, input boxes, confirm dialogs, and file pickers.
api.workspace	IWorkspaceApi	Query and manage the workspace layout: get active/open panels, open or close panels, and listen for panel lifecycle events.

Implementation Tiers

Methods are categorized into implementation tiers:

• T1 (Foundation): Core methods available from API version 1.0.0. Locked and stable.
• T2: Additional methods added after the foundation. May arrive in minor version bumps.
• T3 (Future): Reserved for future major features (e.g., AI integration).

Common Patterns

All Methods Are Async

Every API method returns a Promise. The API boundary is an RPC channel between the extension worker and the host process.

const verse = await api.bible.getVerse(43003016); // John 3:16

Events

Events follow the IEventApi<T> pattern. Call .subscribe() to listen and .dispose() on the returned handle to stop.

const handle = await api.bible.onDidChangeActiveVerse.subscribe((payload) => {
  console.log("Active verse:", payload?.verseId);
});

// Cleanup
await handle.dispose();

Disposable Handles

Registration methods (register*) return a DisposableHandle. Call .dispose() to unregister. The host also auto-disposes all registrations when an extension deactivates.

Verse IDs

Verse references use calculated numeric IDs: (book * 1000000) + (chapter * 1000) + verse.

Reference	Verse ID
Genesis 1:1	1001001
John 3:16	43003016
Revelation 22:21	66022021