Sign in

v1

latestOpenAPI 3.0.2GNU AGPLv32026-07-245983524.8 KB
Ref

Ref

Validates a text reference (tref) and returns structured metadata about it.

The response varies based on the node_type of the referenced text:

  • JaggedArrayNode: Standard text nodes (e.g. biblical chapters/verses, Talmud pages). Returns depth, address_types, section_names, and positional indexes/labels.
  • SchemaNode: Nodes with named children (e.g. a commentary with an introduction and main text). Returns children list.
  • DictionaryEntryNode: Individual dictionary entries. Returns lexicon_name and headword, plus the JaggedArrayNode fields.
  • DictionaryNode: Dictionary root nodes. Returns lexicon_name.
  • SheetNode: User-created source sheets. Returns sheet_id.

If the node has a default child (a child node that represents the primary content), the response includes a default_child_node object with the child's node_type, node_index, and optionally depth, address_types and sectionNames (for JaggedArrayNode children) or lexicon_name (for DictionaryNode parents).

All types include navigation_refs with shortest_path_to_root (array of ancestor refs from immediate parent to book level) and first_available_section_ref. Segment-level refs also get prev_segment_ref/next_segment_ref, and section-level refs get prev_section_ref/next_section_ref.

get/api/ref/{tref}

Response

Returns reference metadata. If the reference string is invalid, returns {"is_ref": false} with HTTP 200.

is_refboolean

Whether the provided string is a valid Sefaria reference.

normalizedstring

The normalized (canonical) form of the reference string.

hebrewstring

The Hebrew form of the reference string.

url_refstring

A URL-friendly form of the reference (spaces replaced with underscores, etc.).

index_titlestring

The title of the book/index this reference belongs to.

node_type'JaggedArrayNode' | 'SchemaNode' | 'DictionaryNode' | 'DictionaryEntryNode' | 'SheetNode'

The type of the index node. Determines which additional fields are present in the response.

depthinteger

The depth of the text structure (e.g. 2 for Chapter/Verse). Present for JaggedArrayNode and DictionaryEntryNode.

address_typesstring[]

The address type for each level of depth (e.g. ["Perek", "Pasuk"]). Present for JaggedArrayNode and DictionaryEntryNode.

section_namesstring[]

Human-readable names for each level of depth (e.g. ["Chapter", "Verse"]). Present for JaggedArrayNode and DictionaryEntryNode.

start_indexesinteger[]

The numeric index values for the start of this reference at each depth level. Present for JaggedArrayNode and DictionaryEntryNode.

start_labelsstring[]

The display labels for the start of this reference at each depth level. Present for JaggedArrayNode and DictionaryEntryNode.

end_indexesinteger[]

The numeric index values for the end of this reference at each depth level. For non-range refs, same as start_indexes. Present for JaggedArrayNode and DictionaryEntryNode.

end_labelsstring[]

The display labels for the end of this reference at each depth level. For non-range refs, same as start_labels. Present for JaggedArrayNode and DictionaryEntryNode.

childrenstring[]

The primary titles of child nodes. Present only for SchemaNode.

lexicon_namestring

The name of the lexicon (dictionary). Present for DictionaryNode and DictionaryEntryNode.

headwordstring

The headword of the dictionary entry. Present only for DictionaryEntryNode.

sheet_idinteger

The ID of the source sheet. Present only for SheetNode.

Example response

{
  "is_ref": true,
  "normalized": "Genesis 1:1",
  "hebrew": "בראשית א׳:א׳",
  "url_ref": "Genesis.1.1",
  "index_title": "Genesis",
  "node_type": "JaggedArrayNode",
  "navigation_refs": {
    "shortest_path_to_root": [
      "Genesis",
      "Genesis 1"
    ],
    "first_available_section_ref": "Genesis 1",
    "prev_segment_ref": null,
    "next_segment_ref": "Genesis 1:2"
  },
  "depth": 2,
  "address_types": [
    "Perek",
    "Pasuk"
  ],
  "section_names": [
    "Chapter",
    "Verse"
  ],
  "start_indexes": [
    1,
    1
  ],
  "start_labels": [
    "1",
    "1"
  ],
  "end_indexes": [
    1,
    1
  ],
  "end_labels": [
    "1",
    "1"
  ]
}