Sign in

v1

latestOpenAPI 3.0.2GNU AGPLv32026-07-245983524.8 KB
Misc

Find Refs

Initially designed to find links on websites using Sefaria's Linker, the Find Refs API can identify textual references in any arbitrary text that gets sent to it via a structured POST request.

This is an asynchronous API. The endpoint immediately returns a task_id with HTTP 202. You must poll GET /api/async/{task_id} to retrieve the task status. When the task completes successfully, the /api/async/{task_id} response will include a result field containing the same FindRefsAPIResponse object described in the 200 response schema below.

post/api/find-refs

Request body

lang'he' | 'en' required

Either he or en. If not included, it will default to one based on the number of Hebrew or Latin characters in the body of the text.

Example request

{
  "text": {
    "body": "Genesis 1:1 is a citation and also Mishnah Peah 3-4. So is שמות ב",
    "title": "Some thoughts on Sefer Bereishit 1"
  },
  "lang": "en"
}

Response

Shape of the result field returned by GET /api/async/{task_id} on successful completion.

Example response

{
  "title": {
    "results": [
      {
        "startChar": 23,
        "endChar": 34,
        "text": "Bereishit 1",
        "linkFailed": false,
        "refs": [
          "Genesis 1"
        ]
      }
    ],
    "refData": {
      "Genesis 1": {
        "heRef": "בראשית א׳",
        "url": "Genesis.1",
        "primaryCategory": "Tanakh"
      }
    }
  },
  "body": {
    "results": [
      {
        "startChar": 0,
        "endChar": 11,
        "text": "Genesis 1:1",
        "linkFailed": false,
        "refs": [
          "Genesis 1:1"
        ]
      },
      {
        "startChar": 35,
        "endChar": 51,
        "text": "Mishnah Peah 3-4",
        "linkFailed": false,
        "refs": [
          "Mishnah Peah 3-4"
        ]
      }
    ],
    "refData": {
      "Genesis 1:1": {
        "heRef": "בראשית א׳:א׳",
        "url": "Genesis.1.1",
        "primaryCategory": "Tanakh"
      },
      "Mishnah Peah 3-4": {
        "heRef": "משנה פאה ג׳-ד׳",
        "url": "Mishnah_Peah.3-4",
        "primaryCategory": "Mishnah"
      }
    }
  }
}