Sefaria's own texts and tools

This page has not been reviewed by a human.

Sefaria publishes its own documentation and tools. This page gives only the two ideas you need to use the toolkit's attributes, then points you to Sefaria for the rest.

References and editions

A reference names a place in Sefaria's library. Sefaria calls it a "ref". Micah 6:8 is a reference.

An edition is one specific text or translation of a work. Sefaria calls it a "version". One work can have many editions, in several languages.

Sefaria marks editions eligible for its primary-text selection with isPrimary. More than one edition can carry the flag. This is usually the Hebrew or original text, but not always. Sefaria's own example is the Kuzari. Its primary edition is Hebrew, although the work was written in Judeo-Arabic.

For the full explanation, read Sefaria's pages on text references and indexes and versions.

How the toolkit picks a translation

By default, Source Card and Bilingual Segment ask Sefaria for its primary edition and its default translation.

To choose a language, set translation-language to a language family name, such as english or french. When you supply no data, the component then asks for a translation in that language. Supplied data is selected locally and never triggers a request.

A preferred translation language can be missing for a text. Depending on its translation-fallback setting, a component then either shows Sefaria's default translation, which isn't always English, or shows that the language is missing. Berakhot 2a:1 is an example.

Which component does which by default, and what it costs in requests, is in Choose what text readers see.

How to tell which edition is shown

An attribution names the edition and its language. It links to the edition's source when Sefaria gives a valid address.

Only some components show an attribution. See Choose what text readers see and Show an attributed passage.

Attributions don't show the edition's license. Each edition has its own. To check the rights for text you plan to reuse, read License and text rights. Sefaria's Copyright and Data Use page and its help article on licensing explain the rules.

When Sefaria's own tools fit

The toolkit fits when you want Sefaria texts inside your own JavaScript page or app, with checked data, cleaned text, or ready-made display elements. Sefaria's tools can fit better, or work alongside it.

Data and code

• API. Use Sefaria's API directly from Python or another language, or when you need data the toolkit doesn't cover. Start with its introduction and the texts endpoint.

Citations and AI

• Linker. The Linker finds citations in your page's text and links them. The toolkit doesn't find citations. The linked article example shows a preview for links you already have.
• MCP servers. The Sefaria MCP lets AI assistants search and read Sefaria. To see the toolkit's Reader inside an AI chat, open Reader inside AI chat.

Sheets and exports

• Source sheets. Use Sefaria's sheets documentation to work with source sheets.
• Data exports. Sefaria-Export offers whole-library bulk data.

Guides and examples

• Educator Playbook. The Educator Playbook is a quick guide to writing raw API code with AI.
• Powered by Sefaria. This list shows projects built on Sefaria.

Learn more: Choose what text readers see · License and text rights