Shape API

The shape API allows one to retrieve information about the shape of an Index on Sefaria. The shape refers to some basic statistics about the Index- most prominently the number of chapters and segments per chapter.

GET /api/shape/:title

Path Parameters

title - A valid node title or a path to a category, separated by /.

Example requests:

/api/shape/Genesis
/api/shape/Pesach_Haggadah
/api/shape/Talmud/Bavli

Query Parameters

The following two query parameters can be passed in calls to the Shape API to further filter results.

Parameter	Type	Default value	Explanation
`depth`	`int`	`2`	The `depth` parameter in the query string indicates how many levels in the category tree to descend. If `depth=0`is passed, then the returned JSON descends to end of tree.
`dependents`	`bool`	`false`	The `dependents` parameter, if true, includes dependent texts. By default, they are filtered out.

Example Responses

Simple Texts

For simple texts, the response returns a dict with keys that contains the following fields:

{
	"section": Category immediately above book
	"heTitle": Hebrew title of node
	"length": Number of chapters
	"chapters": List of Chapter Lengths 
	"title": English title of node
	"book": English title of Book
}

Sample response for sefaria.org/api/shape/Jonah:

[
  {
    "section": "Prophets",
    "heTitle": "יונה",
    "title": "Jonah",
    "length": 4,
    "chapters": [
      16,
      11,
      10,
      11
    ],
  "book": "Jonah",
  "heBook": "יונה"
  }
]

Complex Texts

For complex texts or categories, the Shape API will return a list of dicts for each text within that category or text.

Here is a snippet of what is returned when querying the Shape API for the category Liturgy. To see the full response, try the full query here.

[
  ...
	{
		"section": "Siddur",
		"heTitle": "סידור אשכנז, ימי חול, תפילת שחרית, הכנה לתפילה, מה טובו",
		"title": "Siddur Ashkenaz, Weekday, Shacharit, Preparatory Prayers, Ma Tovu",
		"length": 1,
		"chapters": 1,
		"book": "Siddur Ashkenaz",
		"heBook": "סידור אשכנז"
	},
	{
		"section": "Siddur",
		"heTitle": "סידור אשכנז, ימי חול, תפילת שחרית, הכנה לתפילה, אדון עולם",
		"title": "Siddur Ashkenaz, Weekday, Shacharit, Preparatory Prayers, Adon Olam",
		"length": 1,
		"chapters": 10,
		"book": "Siddur Ashkenaz",
		"heBook": "סידור אשכנז"
	},
	{
		"section": "Siddur",
		"heTitle": "סידור אשכנז, ימי חול, תפילת שחרית, הכנה לתפילה, יגדל",
		"title": "Siddur Ashkenaz, Weekday, Shacharit, Preparatory Prayers, Yigdal",
		"length": 1,
		"chapters": 27,
		"book": "Siddur Ashkenaz",
		"heBook": "סידור אשכנז"
	}
...
]