---
search:
  tags:
    - Passages
    - POST
seo:
  description: >-
    Searches the library with hybrid semantic and keyword retrieval, reranked
    for relevance. Returns passages with their book, author, printed pages and a
    link to…
sidebar:
  label: Search passages
  badge: POST
title: Search passages
type: openapi-operation
---
Searches the library with hybrid semantic and keyword retrieval, reranked for relevance. Returns passages with their book, author, printed pages and a link to the printed page. To restrict results to an author or book, resolve its name to an ID with GET /catalog/lookup first. Body fields not listed here are refused with a 422.

`POST /search`

URL: `https://api.qaf.ai/v1/search`

**Request body** (`application/json`, required)

- `query` (string, required, 1–2000 characters) — What to search for, in Arabic or English.
- `filters` (object) — Restrict results by author, book, death year or genre. Filters match a passage's book and author, not what the passage mentions.
  - `authorIds` (integer[], 1–20 items, each at least 1) — Author IDs, from GET /catalog/lookup or a passage's author.id.
  - `bookIds` (string<uuid>[], 1–20 items) — Book IDs, from GET /catalog/lookup or a passage's book.id.
  - `deathYearAH` (object) — Bounds on the author's death year, in AH. Give at least one; all must hold.
    - `gt` (integer)
    - `gte` (integer)
    - `lt` (integer)
    - `lte` (integer)
  - `genres` (string[], 1–20 items, each one of `creed`, `sects-and-refutations`, `quran-commentary`, `quranic-sciences-and-principles-of-exegesis`, `quran-recitation-and-readings`, `hadith-collections`, `hadith-commentary`, `hadith-sourcing-and-indexes`, `hadith-defects-and-scholarly-questions`, `hadith-sciences`, `principles-of-jurisprudence`, `legal-maxims-and-jurisprudence`, `logic`, `hanafi-fiqh`, `maliki-fiqh`, `shafii-fiqh`, `hanbali-fiqh`, `general-fiqh`, `fiqh-issues`, `islamic-governance-and-judiciary`, `inheritance-and-wills`, `fatwas`, `spirituality-etiquette-and-remembrances`, `prophetic-biography`, `history`, `biographies-and-generations`, `genealogy`, `geography-and-travel`, `arabic-language`, `rare-words-and-dictionaries`, `grammar-and-morphology`, `literature`, `prosody-and-rhyme`, `poetry`, `rhetoric`, `collected-works-and-compilations`, `bibliographies-and-guides`, `medicine`, `general-books`, `other-sciences`) — Genre slugs. A genre describes a book, not a topic, so use one only to search books of that genre.
- `filterOperator` (string, one of `AND`, `OR`) — Combine supplied filter dimensions with AND (default) or OR. Values within each ID list always use OR; all death-year bounds must hold together.
- `limit` (integer, 1–15, default `5`) — Passages to return.
- `excludeIds` (string<uuid>[], up to 200 items) — IDs of passages you already have; the search skips them. Pass the IDs from earlier results to get further passages for the same query.
- `locale` (string, one of `ar`, `en`, default `en`) — Language for book and author names; Arabic names are always included.

Request body example:

```json
{
  "query": "الصبر عند المصيبة"
}
```

**Responses**

- `200` — The matching passages, ranked by relevance.
- `400` — The request can't be processed as sent, such as a filter with an unknown author ID. data.reason, when present, says why.
- `401` — The API key is missing, invalid or revoked.
- `403` — The key's account can't use the API.
- `413` — The request body is larger than 64 KiB.
- `422` — A field is invalid. data.fieldErrors lists the problems by field.
- `429` — Too many requests; data.reason says which limit was reached. For minute, the account's requests per minute, retry after Retry-After seconds. For day, the account's daily search cap, Retry-After is the time until the cap resets. For invalid\_keys, the key doesn't exist or was revoked and this address has sent too many such keys, so fix the key rather than retrying. The X-RateLimit headers describe the account's minute window, so an invalid\_keys refusal, which comes before any key is known, has none.
- `500` — Something went wrong on our side.
- `503` — Qaf could not complete the request in time, or a service it relies on is unavailable. Retry shortly.

Response example, 200:

```json
{
  "results": [
    {
      "id": "d9335f69-e54b-59ae-a78c-50db734b8d50",
      "title": "Fayd al-Qadir — Abd al-Rauf al-Munawi, vol. 4, p. 233",
      "url": "https://app.turath.io/book/21660?print_page=4%2C233",
      "text": "… ٥١٣٤ - (الصبر) الكثير الثواب: الصبر (عند أول صدمة) أي عند فورة المصيبة …",
      "pages": [
        {
          "vol": "4",
          "page": 233
        },
        {
          "vol": "4",
          "page": 234
        }
      ],
      "book": {
        "id": "31f522f9-b85c-5c78-a8ff-dc48ebce183c",
        "title": "Fayd al-Qadir",
        "titleArabic": "فيض القدير"
      },
      "author": {
        "id": 423,
        "name": "Abd al-Rauf al-Munawi",
        "nameArabic": "عبد الرؤوف المناوي"
      },
      "versionId": 21660,
      "sequenceNumber": 4929
    }
  ]
}
```