Skip to main content

Node.js Client

The official Node.js client for the Hey Bible API provides a type-safe way to interact with the API from your JavaScript or TypeScript applications.

npm version

Installation​

npm install @hey-bible/client

Quick Start​

import { Configuration, HeyBibleApi } from '@hey-bible/client';

const config = new Configuration({
  apiKey: process.env.HEY_BIBLE_API_KEY,
});

const api = new HeyBibleApi(config);

Usage​

Search Verses​

Look up verses by book and chapter (saves the lookup to your account):

// Look up a verse range (defaults to ESV)
const result = await api.searchGet({
  book: 'John',
  chapter: 3,
  startVerse: 16,
  endVerse: 18,
});
console.log(result.verse);

// Look up a whole chapter in a specific translation
const psalm = await api.searchGet({ book: 'Psalms', chapter: 23, bibleId: 'kjv' });

List Bibles and Books​

// Available translations
const bibles = await api.biblesGet();

// The 66 books with codes and chapter counts
const books = await api.booksGet();

Get Notes​

Retrieve your notes with their associated verses:

// Get all notes
const notes = await api.notesGet({});

// Get a specific note by ID
const note = await api.notesGet({ id: 456 });

// Paginate through notes
const page = await api.notesGet({ limit: 10, offset: 0 });

Get Images​

Retrieve your saved images:

// Get all images
const images = await api.imagesGet({});

// Get a specific image by ID (returns signed URL)
const image = await api.imagesGet({ id: 789 });

// Paginate through images
const page = await api.imagesGet({ limit: 10, offset: 0 });

Configuration Options​

The Configuration class accepts the following options:

OptionTypeDescription
apiKeystringYour Hey Bible API key
basePathstringOverride the API base URL (default: https://api.heybible.app)
headersobjectAdditional headers to include in requests

Error Handling​

The client throws a ResponseError when the API returns an error response:

import { ResponseError } from '@hey-bible/client';

try {
  const result = await api.searchGet({ book: 'John', chapter: 3 });
} catch (error) {
  if (error instanceof ResponseError) {
    console.error('API Error:', error.response.status);
  }
}

TypeScript Support​

The client is written in TypeScript and includes full type definitions. All response types are automatically inferred:

import { HeyBibleApi, SearchGet200Response } from '@hey-bible/client';

const result: SearchGet200Response = await api.searchGet({ book: 'John', chapter: 3 });

Environment Support​

The client works in the following environments:

  • Node.js
  • Webpack
  • Browserify
  • ES5+ (with a Promises/A+ library)
  • ES6+