Created/edited by GitHub Copilot; pending human review.

Client reference

This page describes how to create a client with @sefaria/api-client and set its options. It also describes the error for a response that doesn't match its contract, the validation helpers, and the generated API functions.

Which release this describes

This page documents the code on the main branch. The source stamp is not an npm release or a development snapshot. This copy was built from commit 6fde603.

Install an exact npm version or use a version-pinned npm CDN module. The npm alpha tag moves between reviewed prereleases. It is not a main-build snapshot. Older pinned releases keep their own behavior and can lack APIs added since. Install and status lists package commands and jsDelivr/UNPKG files.

Client, options, errors and validation

These names are written by hand. Import them from the package root. You can also import some from subpaths:

SefariaCacheOptions, SefariaClient, SefariaClientOptions, createSefariaClient, requireSefariaClient from @sefaria/api-client/client.
ContractIssue, SefariaContractError, SefariaContractErrorOptions from @sefaria/api-client/errors.
GeneratedResponseContract, ResponseSelector, ResponseValidationContext, ResponseValidatorLookup, ValidationResult, getResponseContract, getResponseValidator, validateExternalResponse, validateResponse from @sefaria/api-client/validation.

Functions

createSefariaClient()

function createSefariaClient(options?): SefariaClient;

Creates a frozen generated-SDK client with status-aware response validation.

Documented HTTP error statuses resolve through the generated typed error payloads. A response that violates the generated contract rejects with SefariaContractError. Fetch network failures and aborts reject with the original error.

Parameters

Parameter	Type
`options`	`SefariaClientOptions`

Returns

SefariaClient

getResponseContract()

function getResponseContract(selector): GeneratedResponseContract | undefined;

Returns the generated contract matching an exact method, path, and status.

Parameters

Parameter	Type
`selector`	`ResponseSelector`

Returns

GeneratedResponseContract | undefined

getResponseValidator()

function getResponseValidator(
  contract,
): ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> | undefined;

Returns the Zod schema attached to a generated response contract.

Parameters

Parameter	Type
`contract`	`GeneratedResponseContract`

Returns

| ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> | undefined

validateExternalResponse()

function validateExternalResponse(selector, value, lookup?): ValidationResult;

Validates externally supplied JSON without throwing or requiring a Response.

Parameters

Parameter	Type	Default value
`selector`	`ResponseSelector`	—
`value`	`unknown`	—
`lookup`	`ResponseValidatorLookup`	`getResponseValidator`

Returns

ValidationResult

Classes

SefariaContractError

Error thrown when a Sefaria response violates its generated contract.

Extends

Error

Constructors

Constructor

new SefariaContractError(options): SefariaContractError;

Parameters

Parameter	Type
`options`	`SefariaContractErrorOptions`

Returns

SefariaContractError

Overrides

Error.constructor;

Properties

Property	Modifier	Type	Description
`issues`	`readonly`	readonly `ContractIssue`[]	Structured validation failures.
`method`	`readonly`	`string`	HTTP method from the generated operation contract.
`operationId`	`readonly`	`string`	Generated OpenAPI operation identifier.
`path`	`readonly`	`string`	Generated operation path template.
`response`	`readonly`	`Response`	Original response, preserved for headers and transport metadata.
`status`	`readonly`	`number`	Received HTTP status code.

Interfaces

SefariaClientOptions

Configuration used to create an isolated Sefaria API client.

Properties

Property	Modifier	Type	Description
`baseUrl?`	`readonly`	`string`	API origin. Defaults to `https://www.sefaria.org`.
`cache?`	`readonly`	`false` \| `SefariaCacheOptions`	Bounded per-client response caching. Enabled with defaults when omitted.
`fetch?`	`readonly`	(`input`, `init?`) => `Promise`<`Response`>	Fetch implementation used for requests, testing, or host integration.

SefariaCacheOptions

Limits for one client's bounded in-memory response cache.

Properties

Property	Modifier	Type	Description
`maxBytes?`	`readonly`	`number`	Positive integer maximum decoded response-body bytes retained by one client. Defaults to 10 MiB.
`maxEntries?`	`readonly`	`number`	Positive integer maximum number of admitted responses retained by one client. Defaults to 100.
`ttlMs?`	`readonly`	`number`	Positive finite time-to-live in milliseconds for an admitted response. Defaults to five minutes.

SefariaClient

Branded client accepted by the generated Sefaria SDK operations.

Properties

Property	Modifier	Type	Description
`[sefariaClientBrand]`	`readonly`	`true`	Compile-time brand preventing accidental structural substitutes.
`clearCache`	`readonly`	() => `void`	Removes all responses retained by this client.
`get`	`readonly`	<`TData`, `TError`, `ThrowOnError`>(`options`) => `RequestResult`<`TData`, `TError`, `ThrowOnError`, `"fields"`>	Performs a validated GET request using fields-style responses. A fields-style result exposes the response payload on `data`, a documented error payload on `error`, and the original Fetch `Response` metadata on `response`. Documented HTTP error statuses resolve as typed error payloads. Contract mismatches reject with `SefariaContractError`; network failures and aborts reject with the original error.
`post`	`readonly`	<`TData`, `TError`, `ThrowOnError`>(`options`) => `RequestResult`<`TData`, `TError`, `ThrowOnError`, `"fields"`>	Performs a validated POST request using fields-style responses. A fields-style result exposes the response payload on `data`, a documented error payload on `error`, and the original Fetch `Response` metadata on `response`. Documented HTTP error statuses resolve as typed error payloads. Contract mismatches reject with `SefariaContractError`; network failures and aborts reject with the original error.

ContractIssue

One structured response-contract mismatch.

Properties

Property	Modifier	Type	Description
`instancePath`	`readonly`	`string`	JSON Pointer into the received response value.
`keyword`	`readonly`	`string`	Validator keyword or synthetic contract failure category.
`message?`	`readonly`	`string`	Human-readable diagnostic supplied by the validator.
`schemaPath`	`readonly`	`string`	JSON Pointer identifying the generated schema location.

GeneratedResponseContract

Properties

Property	Modifier	Type
`bodyType`	`readonly`	`"blob"` \| `"json"`
`contentTypes`	`readonly`	readonly `string`[]
`functionName`	`readonly`	`string`
`method`	`readonly`	`"GET"` \| `"POST"`
`operationId`	`readonly`	`string`
`path`	`readonly`	`string`
`schema?`	`readonly`	`ZodType`<`unknown`, `unknown`, `$ZodTypeInternals`<`unknown`, `unknown`>>
`schemaPath`	`readonly`	`string`
`status`	`readonly`	`number`
`validatorName?`	`readonly`	`string`

ResponseSelector

Identifies one documented operation response by method, path, and status.

Properties

Property	Modifier	Type	Description
`method`	`readonly`	`string`	HTTP method; matching is case-insensitive.
`path`	`readonly`	`string`	Generated OpenAPI path template rather than a concrete request URL.
`status`	`readonly`	`number`	HTTP response status code.

SefariaContractErrorOptions

Complete context retained by SefariaContractError.

Properties

Property	Modifier	Type	Description
`issues`	`readonly`	readonly `ContractIssue`[]	Structured validation failures.
`method`	`readonly`	`string`	HTTP method from the generated operation contract.
`operationId`	`readonly`	`string`	Generated OpenAPI operation identifier.
`path`	`readonly`	`string`	Generated operation path template.
`response`	`readonly`	`Response`	Original response, preserved for headers and transport metadata.
`status`	`readonly`	`number`	Received HTTP status code.

Type Aliases

ResponseValidatorLookup

type ResponseValidatorLookup = (contract) => ZodType | undefined;

Resolves the runtime schema used for one generated response contract.

Parameters

Parameter	Type
`contract`	`GeneratedResponseContract`

Returns

ZodType | undefined

ValidationResult

type ValidationResult =
  | {
      issues: readonly [];
      valid: true;
    }
  | {
      issues: readonly ContractIssue[];
      valid: false;
    };

Non-throwing validation result for externally supplied response-shaped JSON.

Generated functions by namespace

The client has 60 generated functions, one for each endpoint in the corrected API description. The functions are grouped into namespaces that follow the sections of Sefaria's API, and each namespace is exported from the package root. Call a function with a client and its request options, for example text.getV3Texts({ client, path: { tref: "Micah 6:8" } }).

Options type describes the path, query, and body options that the function accepts.
Responses type maps each documented success status to its response body. Errors type, where there is one, does the same for documented error statuses.
Validators check a response body for one status. The client runs them on the responses it receives. You can also call them on JSON from elsewhere.
A binary response has no validator. The client checks only its status and content type.

`text`

Function	Request	Summary	Options type	Responses type	Errors type	Validators
`text.getV3Texts`	`GET /api/v3/texts/{tref}`	Texts (v3)	`GetV3TextsData`	`GetV3TextsResponses`	`GetV3TextsErrors`	`validateGetV3Texts200` (200) `validateGetV3Texts400` (400) `validateGetV3Texts404` (404)
`text.getV1Texts`	`GET /api/texts/{tref}`	Texts (v1)	`GetV1TextsData`	`GetV1TextsResponses`	—	`validateGetV1Texts200` (200)
`text.getTranslations`	`GET /api/texts/translations`	Languages	`GetTranslationsData`	`GetTranslationsResponses`	—	`validateGetTranslations200` (200)
`text.getTranslationsLang`	`GET /api/texts/translations/{lang}`	Translations	`GetTranslationsLangData`	`GetTranslationsLangResponses`	—	`validateGetTranslationsLang200` (200)
`text.getManuscripts`	`GET /api/manuscripts/{tref}`	Manuscripts	`GetManuscriptsData`	`GetManuscriptsResponses`	—	`validateGetManuscripts200` (200)
`text.getTextsRandom`	`GET /api/texts/random`	Random Text	`GetTextsRandomData`	`GetTextsRandomResponses`	—	`validateGetTextsRandom200` (200)
`text.getBulktext`	`GET /api/bulktext/{refs}`	—	`GetBulktextData`	`GetBulktextResponses`	—	`validateGetBulktext200` (200)
`text.getPassages`	`GET /api/passages/{refs}`	—	`GetPassagesData`	`GetPassagesResponses`	—	`validateGetPassages200` (200)
`text.getTextVersions`	`GET /api/texts/versions/{tref}`	Versions	`GetTextVersionsData`	`GetTextVersionsResponses`	—	`validateGetTextVersions200` (200)

`index`

Function	Request	Summary	Options type	Responses type	Errors type	Validators
`index.getV2Index`	`GET /api/v2/raw/index/{index_title}`	Index (v2)	`GetV2IndexData`	`GetV2IndexResponses`	—	`validateGetV2Index200` (200)
`index.getIndex`	`GET /api/index`	Table of Contents	`GetIndexData`	`GetIndexResponses`	—	`validateGetIndex200` (200)
`index.getShape`	`GET /api/shape/{title}`	Shape	`GetShapeData`	`GetShapeResponses`	—	`validateGetShape200` (200)
`index.getAuthorIndexes`	`GET /api/authors/{author_slug}/indexes`	—	`GetAuthorIndexesData`	`GetAuthorIndexesResponses`	—	`validateGetAuthorIndexes200` (200)
`index.getIndexTitles`	`GET /api/index/titles`	—	`GetIndexTitlesData`	`GetIndexTitlesResponses`	—	`validateGetIndexTitles200` (200)
`index.getIndexByTitle`	`GET /api/index/{title}`	—	`GetIndexByTitleData`	`GetIndexByTitleResponses`	—	`validateGetIndexByTitle200` (200)
`index.getIndexV2`	`GET /api/v2/index/{title}`	—	`GetIndexV2Data`	`GetIndexV2Responses`	—	`validateGetIndexV2200` (200)
`index.getCounts`	`GET /api/counts/{title}`	—	`GetCountsData`	`GetCountsResponses`	—	`validateGetCounts200` (200)
`index.getCountsLinks`	`GET /api/counts/links/{cat1}/{cat2}`	—	`GetCountsLinksData`	`GetCountsLinksResponses`	—	`validateGetCountsLinks200` (200)
`index.getCountsWords`	`GET /api/counts/words/{title}/{version}/{language}`	—	`GetCountsWordsData`	`GetCountsWordsResponses`	—	`validateGetCountsWords200` (200)

`related`

Function	Request	Summary	Options type	Responses type	Errors type	Validators
`related.getRelated`	`GET /api/related/{tref}`	Related	`GetRelatedData`	`GetRelatedResponses`	—	`validateGetRelated200` (200)
`related.getRelatedWebsites`	`GET /api/related/{tref}/websites`	Related Web Pages	`GetRelatedWebsitesData`	`GetRelatedWebsitesResponses`	—	`validateGetRelatedWebsites200` (200)
`related.getLinks`	`GET /api/links/{tref}`	Links	`GetLinksData`	`GetLinksResponses`	`GetLinksErrors`	`validateGetLinks200` (200) `validateGetLinks400` (400)
`related.getRefTopicLinks`	`GET /api/ref-topic-links/{tref}`	Ref-Topic-Links	`GetRefTopicLinksData`	`GetRefTopicLinksResponses`	—	`validateGetRefTopicLinks200` (200)
`related.getLinkSummary`	`GET /api/link-summary/{ref}`	—	`GetLinkSummaryData`	`GetLinkSummaryResponses`	—	`validateGetLinkSummary200` (200)

`calendars`

Function	Request	Summary	Options type	Responses type	Errors type	Validators
`calendars.getCalendars`	`GET /api/calendars`	Calendars	`GetCalendarsData`	`GetCalendarsResponses`	—	`validateGetCalendars200` (200)
`calendars.getNextRead`	`GET /api/calendars/next-read/{parasha}`	Next Read	`GetNextReadData`	`GetNextReadResponses`	—	`validateGetNextRead200` (200)
`calendars.getAliyotByParasha`	`GET /api/sheets/{parasha}/get_aliyot`	—	`GetAliyotByParashaData`	`GetAliyotByParashaResponses`	—	`validateGetAliyotByParasha200` (200)
`calendars.getCalendarParashaTopic`	`GET /api/calendars/topics/parasha`	—	`GetCalendarParashaTopicData`	`GetCalendarParashaTopicResponses`	—	`validateGetCalendarParashaTopic200` (200)
`calendars.getCalendarHolidayTopic`	`GET /api/calendars/topics/holiday`	—	`GetCalendarHolidayTopicData`	`GetCalendarHolidayTopicResponses`	—	`validateGetCalendarHolidayTopic200` (200)

`lexicon`

Function	Request	Summary	Options type	Responses type	Errors type	Validators
`lexicon.getWords`	`GET /api/words/{word}`	Lexicon	`GetWordsData`	`GetWordsResponses`	—	`validateGetWords200` (200)
`lexicon.getWordsCompletion`	`GET /api/words/completion/{word}/{lexicon}`	Word Completion	`GetWordsCompletionData`	`GetWordsCompletionResponses`	—	`validateGetWordsCompletion200` (200)

`topic`

Function	Request	Summary	Options type	Responses type	Errors type	Validators
`topic.getV2Topics`	`GET /api/v2/topics/{topic_slug}`	Topic (v2)	`GetV2TopicsData`	`GetV2TopicsResponses`	—	`validateGetV2Topics200` (200)
`topic.getTopicSlug`	`GET /api/topics/{topic_slug}`	Topic (v1)	`GetTopicSlugData`	`GetTopicSlugResponses`	—	`validateGetTopicSlug200` (200)
`topic.getAllTopics`	`GET /api/topics`	All Topics	`GetAllTopicsData`	`GetAllTopicsResponses`	—	`validateGetAllTopics200` (200)
`topic.getTopicsGraph`	`GET /api/topics-graph/{topic_slug}`	Topic Graph	`GetTopicsGraphData`	`GetTopicsGraphResponses`	—	`validateGetTopicsGraph200` (200)
`topic.getRecommendTopics`	`GET /api/recommend/topics/{ref_list}`	Recommended Topics	`GetRecommendTopicsData`	`GetRecommendTopicsResponses`	—	`validateGetRecommendTopics200` (200)
`topic.getRandomByTopic`	`GET /api/texts/random-by-topic`	Random By Topic	`GetRandomByTopicData`	`GetRandomByTopicResponses`	—	`validateGetRandomByTopic200` (200)

`term`

Function	Request	Summary	Options type	Responses type	Errors type	Validators
`term.getTerms`	`GET /api/terms/{name}`	Terms	`GetTermsData`	`GetTermsResponses`	—	`validateGetTerms200` (200)
`term.getName`	`GET /api/name/{name}`	Name	`GetNameData`	`GetNameResponses`	—	`validateGetName200` (200)

`sheets`

Function	Request	Summary	Options type	Responses type	Errors type	Validators
`sheets.getSheet`	`GET /api/sheets/{sheet_id}`	—	`GetSheetData`	`GetSheetResponses`	—	`validateGetSheet200` (200)
`sheets.getSheetsTrendingTags`	`GET /api/sheets/trending-tags`	—	`GetSheetsTrendingTagsData`	`GetSheetsTrendingTagsResponses`	—	`validateGetSheetsTrendingTags200` (200)
`sheets.getSheetModified`	`GET /api/sheets/modified/{sheet_id}/{timestamp}`	—	`GetSheetModifiedData`	`GetSheetModifiedResponses`	—	`validateGetSheetModified200` (200)
`sheets.getUserSheets`	`GET /api/sheets/user/{user_id}`	—	`GetUserSheetsData`	`GetUserSheetsResponses`	—	`validateGetUserSheets200` (200)
`sheets.getUserSheetsPaginated`	`GET /api/sheets/user/{user_id}/{sort_by}/{limiter}/{offset}`	—	`GetUserSheetsPaginatedData`	`GetUserSheetsPaginatedResponses`	—	`validateGetUserSheetsPaginated200` (200)
`sheets.getSheetsBulk`	`GET /api/v2/sheets/bulk/{sheet_id_list}`	—	`GetSheetsBulkData`	`GetSheetsBulkResponses`	—	`validateGetSheetsBulk200` (200)
`sheets.getSheetsTagList`	`GET /api/sheets/tag-list`	—	`GetSheetsTagListData`	`GetSheetsTagListResponses`	—	`validateGetSheetsTagList200` (200)
`sheets.getSheetsTagListSorted`	`GET /api/sheets/tag-list/{sort_by}`	—	`GetSheetsTagListSortedData`	`GetSheetsTagListSortedResponses`	—	`validateGetSheetsTagListSorted200` (200)
`sheets.getUserSheetTags`	`GET /api/sheets/tag-list/user/{user_id}`	—	`GetUserSheetTagsData`	`GetUserSheetTagsResponses`	—	`validateGetUserSheetTags200` (200)
`sheets.getSheetsByRef`	`GET /api/sheets/ref/{ref}`	—	`GetSheetsByRefData`	`GetSheetsByRefResponses`	—	`validateGetSheetsByRef200` (200)
`sheets.getAllSheets`	`GET /api/sheets/all-sheets/{limiter}/{offset}`	—	`GetAllSheetsData`	`GetAllSheetsResponses`	—	`validateGetAllSheets200` (200)

`collections`

Function	Request	Summary	Options type	Responses type	Errors type	Validators
`collections.getCollections`	`GET /api/collections`	—	`GetCollectionsData`	`GetCollectionsResponses`	—	`validateGetCollections200` (200)
`collections.getCollection`	`GET /api/collections/{slug}`	—	`GetCollectionData`	`GetCollectionResponses`	—	`validateGetCollection200` (200)
`collections.getUserCollections`	`GET /api/collections/user-collections/{user_id}`	—	`GetUserCollectionsData`	`GetUserCollectionsResponses`	—	`validateGetUserCollections200` (200)

`misc`

Function	Request	Summary	Options type	Responses type	Errors type	Validators
`misc.postFindRefs`	`POST /api/find-refs`	Find Refs	`PostFindRefsData`	`PostFindRefsResponses`	—	`validatePostFindRefs202` (202)
`misc.postSearchWrapper`	`POST /api/search-wrapper`	Search	`PostSearchWrapperData`	`PostSearchWrapperResponses`	—	`validatePostSearchWrapper200` (200)
`misc.getImgGen`	`GET /api/img-gen/{tref}`	Social Media Image	`GetImgGenData`	`GetImgGenResponses`	—	200: binary body (image/png), no validator
`misc.getCategory`	`GET /api/category/{category_path}`	Category	`GetCategoryData`	`GetCategoryResponses`	—	`validateGetCategory200` (200)
`misc.getProfile`	`GET /api/profile/{slug}`	—	`GetProfileData`	`GetProfileResponses`	—	`validateGetProfile200` (200)
`misc.getAsyncTaskStatus`	`GET /api/async/{task_id}`	Get Async Task Status	`GetAsyncTaskStatusData`	`GetAsyncTaskStatusResponses`	`GetAsyncTaskStatusErrors`	`validateGetAsyncTaskStatus200` (200) `validateGetAsyncTaskStatus202` (202) `validateGetAsyncTaskStatus500` (500)

`ref`

Function	Request	Summary	Options type	Responses type	Errors type	Validators
`ref.getRef`	`GET /api/ref/{tref}`	Ref	`GetRefData`	`GetRefResponses`	`GetRefErrors`	`validateGetRef200` (200) `validateGetRef404` (404)

Generated types, schemas and validators

The package root also exports the generated types, schemas, and validators. This page doesn't list them one by one.

Types, such as GetV3TextsData and GetV3TextsResponses, are TypeScript types. The package exports them from the root and from @sefaria/api-client/contracts.
Zod schemas have names starting with z, such as zCoreV3TextsResponse. The package exports them from the root and from @sefaria/api-client/schemas.
Validators have names such as validateGetV3Texts200, which is the function name plus the status. The package exports them from the root and from @sefaria/api-client/validators.

Reference › Package imports and exports lists every subpath.

Where to go next

Data and text tools › Start here makes your first request.
Handle errors in your code shows how to handle SefariaContractError and failed requests.
The client and Sefaria's API explains how the client is generated.
Corrections to Sefaria's API description lists where the generated contracts differ from Sefaria's published description.

Client reference ​

Which release this describes ​

Client, options, errors and validation ​

Functions ​

createSefariaClient() ​

Parameters ​

Returns ​

getResponseContract() ​

Parameters ​

Returns ​

getResponseValidator() ​

Parameters ​

Returns ​

validateExternalResponse() ​

Parameters ​

Returns ​

Classes ​

SefariaContractError ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Overrides ​

Properties ​

Interfaces ​

SefariaClientOptions ​

Properties ​

SefariaCacheOptions ​

Properties ​

SefariaClient ​

Properties ​

ContractIssue ​

Properties ​

GeneratedResponseContract ​

Properties ​

ResponseSelector ​

Properties ​

SefariaContractErrorOptions ​

Properties ​

Type Aliases ​

ResponseValidatorLookup ​

Parameters ​

Returns ​

ValidationResult ​

Generated functions by namespace ​

text ​

index ​

related ​

calendars ​

lexicon ​

topic ​

term ​

sheets ​

collections ​

misc ​

ref ​

Generated types, schemas and validators ​

Where to go next ​

Client reference

Which release this describes

Client, options, errors and validation

Functions

createSefariaClient()

Parameters

Returns

getResponseContract()

Parameters

Returns

getResponseValidator()

Parameters

Returns

validateExternalResponse()

Parameters

Returns

Classes

SefariaContractError

Extends

Constructors

Constructor

Parameters

Returns

Overrides

Properties

Interfaces

SefariaClientOptions

Properties

SefariaCacheOptions

Properties

SefariaClient

Properties

ContractIssue

Properties

GeneratedResponseContract

Properties

ResponseSelector

Properties

SefariaContractErrorOptions

Properties

Type Aliases

ResponseValidatorLookup

Parameters

Returns

ValidationResult

Generated functions by namespace

`text`

`index`

`related`

`calendars`

`lexicon`

`topic`

`term`

`sheets`

`collections`

`misc`

`ref`

Generated types, schemas and validators

Where to go next