---
title: "Texts (v3)"
method: GET
path: "/api/v3/texts/{tref}"
tags: ["Text"]
---

# Texts (v3)

`GET /api/v3/texts/{tref}`

The most up-to-date way to retrieve texts from Sefaria via the API, with enhanced control over language, language direction, and other parameters.

## Response `200`

Successful retrieval of the desired texts.

- V3TextsJson — The JSON returned from the `v3` `texts/` endpoint.
  - `versions` V3TextVersionsJSON[] — The list of requested `version` objects. It includes all the data that is unique to the requested `versions`.
    - `status` string — Whether or not the text is `"locked"` for further edits from the community.
    - `priority` union — The priority assigned to a version of the text. A higher number will have the text appear higher within the listing of available versions for a specific text on the Sefaria website. (i.e. `Esther A` with a priority of `2`, will appear before `Esther B`, with a priority of `1`)
      - string
      - number, float
    - `license` string — The license for the text, in terms of copyright, and distribution.
    - `versionNotes` string — Notes on the version
    - `formatAsPoetry` union — A boolean indicating whether or not the text (or portions of it) are formatted as poetry.
      - boolean
      - string
    - `digitizedBySefaria` union — An indicator of whether or not Sefaria digitized the text, versus acquiring an already digital copy of a text.
      - boolean
      - string
    - `method` string
    - `heversionSource` string
    - `versionUrl` string — URl for the version
    - `versionTitleInHebrew` string
    - `versionNotesInHebrew` string
    - `shortVersionTitle` string
    - `shortVersionTitleInHebrew` string
    - `extendedNotes` string
    - `extendedNotesHebrew` string
    - `purchaseInformationImage` string — A URL pointing to an image of the hardcopy text available for purchase.
    - `purchaseInformationURL` string — A URL pointing to where one can purchase a hardcopy of this text.
    - `hasManuallyWrappedRefs` string
    - `actualLanguage` string — The [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) language code for the language of the text. We default to 2 letter codes when available, and 3 letter codes when they are not.
    - `languageFamilyName` string — The overarching family for the specific language detailed in `actualLanguage`. For example, `Arabic` would be the overarching family for `judeo-arabic`.
    - `isSource` boolean
    - `isPrimary` boolean — Indicates whether or not this version of the text is determined as the primary version in the Sefaria database.
    - `direction` string — The direction of the text, either `ltr` (left-to-right) or `rtl` (right-to-left). Examples of `ltr` languages include English, French and German. Examples of `rtl` languages are Hebrew and Arabic.
    - `language` string — A holdover from the `v2` API which will eventually be deprecated. This used to indicate the direction of the text, with `en` indicating texts written from left-to-right, and `he` indicating texting written from right-to-left.
    - `versionSource` string — The original source of the digital text.
    - `versionTitle` string — The English title of the Version of text.
    - `text` union — An array of strings containing the text of the specific version. If a segment `Ref` was passed, the array returned will be one-dimensional and contain a string with the specific segment level text. If a bottom level section `Ref` was passed, the array returned will be a two-dimensional array, a list of lists of strings. The outer layer of the array represents the section, and the inner arrays represent the segments.
      - union[]
        - union
          - string
          - string[]
      - string
    - `firstSectionRef` string — The first available `Ref` to the section of text passed in the API.
  - `available_versions` V3AvailableVersionsTextJson[]
    - `status` string — Whether or not the text is `"locked"` for further edits from the community.
    - `priority` string
    - `license` string — The license for the text, in terms of copyright, and distribution.
    - `versionNotes` string — Notes on the version
    - `formatAsPoetry` string
    - `digitizedBySefaria` union
      - string
      - boolean
    - `method` string
    - `heversionSource` string
    - `versionUrl` string — URl for the version
    - `versionTitleInHebrew` string
    - `versionNotesInHebrew` string
    - `shortVersionTitle` string
    - `shortVersionTitleInHebrew` string
    - `extendedNotes` string
    - `extendedNotesHebrew` string
    - `purchaseInformationImage` string — A URL pointing to an image of the hardcopy text available for purchase.
    - `purchaseInformationURL` string — A URL pointing to where one can purchase a hardcopy of this text.
    - `hasManuallyWrappedRefs` string
    - `actualLanguage` string — The [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) language code for the language of the text. We default to 2 letter codes when available, and 3 letter codes when they are not.
    - `languageFamilyName` string — The overarching family for the specific language detailed in `actualLanguage`. For example, `Arabic` would be the overarching family for `judeo-arabic`.
    - `isSource` boolean
    - `isPrimary` boolean — Indicates whether or not this version of the text is determined as the primary version in the Sefaria database.
    - `direction` string — The direction of the text, either `ltr` (left-to-right) or `rtl` (right-to-left). Examples of `ltr` languages include English, French and German. Examples of `rtl` languages are Hebrew and Arabic.
    - `language` string — A holdover from the `v2` API which will eventually be deprecated. This used to indicate the direction of the text, with `en` indicating texts written from left-to-right, and `he` indicating texting written from right-to-left.
    - `title` string — The title of the book.
    - `versionSource` string — The original source of the digital text.
    - `versionTitle` string — The English title of the Version of text.
    - `text` union — An array of strings containing the text of the specific version. If a segment `Ref` was passed, the array returned will be one-dimensional and contain a string with the specific segment level text. If a bottom level section `Ref` was passed, the array returned will be a two-dimensional array, a list of lists of strings. The outer layer of the array represents the section, and the inner arrays represent the segments.
      - union[]
        - union
          - string
          - string[]
      - string
    - `firstSectionRef` string — The first available `Ref` to the section of text passed in the API.
  - `ref` string — A string representing a citation to a Jewish text. A valid `Ref` consists of a title string followed optionally by a section string or a segment string. A title string is any one of the known text titles or title variants in the Sefaria Database.
  - `heRef` string — Hebrew `Ref` for the segment.
  - `sections` unknown[] — An array which corresponds to sectionNames and represents the sections of the text requested. When sectionNames is `["Chapter", "Verse"]` a request for chapter 4 looks like `[4]` while a request for chapter 4, verse 7 would look like `[4, 7]`. _Note, for Talmud, Dafs are represented by a string like "42a" or "12b"_
    - unknown
  - `toSections` unknown[]
    - unknown
  - `sectionRef` string — A string representing a citation to a Jewish text. A valid `Ref` consists of a title string followed optionally by a section string or a segment string. A title string is any one of the known text titles or title variants in the Sefaria Database.
  - `heSectionRef` string
  - `firstAvailableSectionRef` string
  - `isSpanning` boolean
  - `spanningRefs` unknown[]
    - unknown
  - `next` string — Next segment reference in sequence, if last ref, field will be `null`.
  - `prev` string — Previous segment reference in sequence, if first ref, field will be `null`.
  - `title` string — The title of the book these versions correspond to.
  - `book` string — The title of the book that the response comes from.
  - `heTitle` string
  - `primary_category` string
  - `type` string
  - `indexTitle` string — The book title
  - `categories` string[] — A list of categories that a text belongs to.
  - `heIndexTitle` string
  - `isComplex` boolean — Whether or not the text is a "complex" text or not. In Sefaria, a complex text is any text which has a more complicated index structure beyond Chapters/Verses, (e.g. the Talmud). There are a variety of structural differences for a complex text, having to do primarily with its Index, and the way the data is stored. For more on complex texts, see the documentation here.
  - `isDependant` boolean
  - `order` integer[]
  - `collectiveTitle` string — A shortened name of the Index for display in the connection panel (i.e. `Rashi on Genesis` will have a collective title of `Rashi`)
  - `heCollectiveTitle` string — A Hebrew shortened name of the Index for display in the connection panel (i.e. `רש״י על בראשית` will have a collective title of `רש״י`)
  - `alts` unknown[]
    - unknown
  - `lengths` integer[]
  - `length` integer
  - `textDepth` integer — The depth of the text. For example, Genesis will have depth of `2`, since it is comprised of two layers, chapters and verses. Whereas a commentary on Genesis will have a depth of `3`, since it is organized by chapter, verse, and then specific comment on a verse.
  - `sectionNames` string[] — An array containing the type names of the sections of this text. The length of sectionNames gives the depth of the structure of this text. For example, Kohelet `(["Chapter", "Verse"])` has depth 2, while Mishneh Torah `(["Book", "Topic", "Section", "Law"])` has depth 4. Comparing this depth to the depth of sections will show if the request was for the lowest level, or a higher level, of the text.
  - `addressTypes` string[] — A list which length reflects the depth of the text structure, with string values indicating class names for address types for each level
  - `titleVariants` string[] — Various alternative titles used for the text.
  - `heTitleVariants` string[]
  - `index_offsets_by_depth` object
  - `warnings` unknown[] — A list of objects - for any version parameter that has no result there is a readable message and warning code. Codes: `APINoVersion = 101` `APINoLanguageVersion = 102` `APINoSourceText = 103` `APINoTranslationText = 104`
    - unknown

---

[API](https://skmtc.net/sefaria/apis/sefaria-api.md) · [All operations](https://skmtc.net/sefaria/apis/sefaria-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sefaria/sefaria-api/revisions/d29296717011/schema)