---
title: "Find Refs"
method: POST
path: "/api/find-refs"
tags: ["Misc"]
---

# Find Refs

`POST /api/find-refs`

Initially designed to find links on websites using [Sefaria's Linker](https://www.sefaria.org/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.

## Request body

- FindRefsPOSTRequest — A properly formatted POST request for the Find Refs API
  - `text` object, required — Initially designed for websites, this API expects the `text` field to contain both a `body` and a `title`. When parsing arbitrary text feel free to just use `body` and pass an empty string `''` to `title`
    - `body` string
    - `title` string
  - `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`.

## Response `200`

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

- FindRefsAPIResponse — A response to the Find Refs API
  - `title` object — Information about any references found in the `title` field of the POST request
    - `results` object[]
      - `startChar` integer — The index of the starting character of the match
      - `endChar` integer — The index of the ending character of the match
      - `text` string — The matched reference
      - `linkFailed` boolean
      - `refs` Ref[]
    - `refData` object
      - `RefTitle` object
        - `heRef` string — The Hebrew equivalent of the canonical ref
        - `url` string — The URL this ref can be found at on Sefaria
        - `primaryCategory` string — The primary category this ref belongs to on Sefaria
  - `body` object — Information about any references found in the `body` field of the POST request
    - `results` object[]
      - `startChar` integer — The index of the starting character of the match
      - `endChar` integer — The index of the ending character of the match
      - `text` string — The matched reference
      - `linkFailed` boolean
      - `refs` Ref[]
    - `refData` object
      - `RefTitle` object
        - `heRef` string — The Hebrew equivalent of the canonical ref
        - `url` string — The URL this ref can be found at on Sefaria
        - `primaryCategory` string — The primary category this ref belongs to on Sefaria

## Other responses

- `202` — Task enqueued. Poll `GET /api/async/{task_id}` to retrieve results. When the task completes successfully, the result will have the shape described by `FindRefsAPIResponse`.

---

[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)