sefaria-sdk

Zero-dependency TypeScript SDK for the Sefaria API. Provides typed access to Jewish texts, translations, search, topics, and more.

Install

npm install sefaria-sdk
# or
bun add sefaria-sdk

Quick start

Using createClient

import { createClient } from 'sefaria-sdk';

const sefaria = createClient();

const result = await sefaria.getText('Genesis 1:1');
if (result.ok) {
  console.log(result.data.versions[0].text);
}

Standalone functions

import { getText, searchText } from 'sefaria-sdk';

const result = await getText('Berakhot 2a');
if (result.ok) {
  console.log(result.data.ref);
}

Error handling

Every function returns a Result<T, R> — either { ok: true, data: T } or { ok: false, reason: R }.

import { getText, SefariaReason } from 'sefaria-sdk';

const result = await getText('Genesis 1:1', { language: 'english' });

if (!result.ok) {
  switch (result.reason) {
    case SefariaReason.NoTranslation:
      console.log('No translation available');
      break;
    case SefariaReason.NoVersion:
      console.log('No version found');
      break;
  }
}

Network and HTTP errors throw typed exceptions:

import { getText, NetworkError, ApiError, NotFoundError } from 'sefaria-sdk';

try {
  await getText('Genesis 1:1');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Not found:', err.endpoint);
  } else if (err instanceof NetworkError) {
    console.log('Network issue:', err.message);
  } else if (err instanceof ApiError) {
    console.log(`API error ${err.status}:`, err.message);
  }
}

API reference

Texts

Function	Description
getText(ref, options?)	Fetch a text passage by reference
getVersions(title, options?)	List available versions of a text
getLanguages(options?)	List all available languages
getTranslations(language, options?)	List translations for a language
getRandomText(options?)	Get a random text reference

Links

Function	Description
getLinks(ref, options?)	Get links/connections for a reference
getRelated(ref, options?)	Get related content for a reference
getRefTopicLinks(ref, options?)	Get topic links for a reference

Search

Function	Description
searchText(query, options?)	Full-text search across the library
searchInBook(query, book, options?)	Search within a specific book
semanticSearch(query, options?)	Semantic/vector search

Topics

Function	Description
getTopic(slug, options?)	Get a topic by slug
getAllTopics(options?)	List all topics

Calendar

Function	Description
getCalendar(options?)	Get today's calendar readings

Names

Function	Description
resolveName(name, options?)	Resolve/autocomplete a text name

Manuscripts

Function	Description
getManuscripts(ref, options?)	Get manuscript images for a reference

Dictionary

Function	Description
lookupWord(word, options?)	Look up a word in dictionaries

Categories

Function	Description
getIndex(title, options?)	Get index metadata for a text
getTableOfContents(options?)	Get the full table of contents
getShape(name, options?)	Get the shape/structure of a text
getCategory(name, options?)	Get a category and its contents

Utility

Function	Description
findRefs(text, options?)	Find text references in a string
getTerm(name, options?)	Look up a term/schema node

Configuration

Options can be passed to createClient() or in each function's options bag.

Option	Type	Default	Description
baseUrl	string	https://www.sefaria.org	API base URL
timeout	number	10000	Request timeout in ms
maxRetries	number	2	Retries for 429/5xx errors
fetch	typeof fetch	globalThis.fetch	Custom fetch implementation
signal	AbortSignal	—	Abort signal for cancellation

Per-call config overrides client-level config:

const client = createClient({ timeout: 5000 });

// This call uses timeout: 30000, not 5000
await client.getText('Genesis 1:1', { config: { timeout: 30000 } });

License

MIT