--- title: "Ref" method: GET path: "/api/ref/{tref}" tags: ["Ref"] --- # Ref `GET /api/ref/{tref}` 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`. ## Response `200` Returns reference metadata. If the reference string is invalid, returns `{"is_ref": false}` with HTTP 200. - RefJSON — The JSON returned from the `ref` endpoint. Contains metadata about a validated text reference, including its type, structure, and navigation information. The fields returned vary based on the `node_type`. - `is_ref` boolean — Whether the provided string is a valid Sefaria reference. - `normalized` string — The normalized (canonical) form of the reference string. - `hebrew` string — The Hebrew form of the reference string. - `url_ref` string — A URL-friendly form of the reference (spaces replaced with underscores, etc.). - `index_title` string — 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. - `navigation_refs` object — An object containing related references for navigating within the text. - `shortest_path_to_root` string[] — An array of references representing the hierarchical path from the book level down to the immediate parent. Empty array if at book level. - `first_available_section_ref` string, nullable — The first section-level reference that has available text content. - `prev_segment_ref` string, nullable — The previous segment-level reference. Only present for segment-level refs. - `next_segment_ref` string, nullable — The next segment-level reference. Only present for segment-level refs. - `prev_section_ref` string, nullable — The previous section-level reference. Only present for section-level refs. - `next_section_ref` string, nullable — The next section-level reference. Only present for section-level refs. - `first_subref` string — The first sub-reference within this ref. Present for non-segment-level refs with depth. - `last_subref` string — The last sub-reference within this ref. Present for non-segment-level refs with depth. - `depth` integer — The depth of the text structure (e.g. 2 for Chapter/Verse). Present for JaggedArrayNode and DictionaryEntryNode. - `address_types` string[] — The address type for each level of depth (e.g. ["Perek", "Pasuk"]). Present for JaggedArrayNode and DictionaryEntryNode. - `section_names` string[] — Human-readable names for each level of depth (e.g. ["Chapter", "Verse"]). Present for JaggedArrayNode and DictionaryEntryNode. - `start_indexes` integer[] — The numeric index values for the start of this reference at each depth level. Present for JaggedArrayNode and DictionaryEntryNode. - `start_labels` string[] — The display labels for the start of this reference at each depth level. Present for JaggedArrayNode and DictionaryEntryNode. - `end_indexes` integer[] — 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_labels` string[] — 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. - `children` string[] — The primary titles of child nodes. Present only for SchemaNode. - `lexicon_name` string — The name of the lexicon (dictionary). Present for DictionaryNode and DictionaryEntryNode. - `headword` string — The headword of the dictionary entry. Present only for DictionaryEntryNode. - `sheet_id` integer — The ID of the source sheet. Present only for SheetNode. - `default_child_node` object — Information about the default child node, if the current node has one. A default child is a child node that represents the primary content of a schema node. - `node_type` string — The type of the default child node. - `node_index` integer — The index of the default child within the parent's children array. - `depth` integer — The depth of the default child. Present only when the default child is a JaggedArrayNode. - `address_types` string[] — The address type for each level of depth. Present only when the default child is a JaggedArrayNode. - `section_names` string[] — Human-readable names for each level of depth. Present only when the default child is a JaggedArrayNode. - `lexicon_name` string — The lexicon name. Present only when the parent is a DictionaryNode. ## Other responses - `404` — Returned when the reference string causes a parsing error. --- [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)