---
title: Search and read passages
description: Write queries that find the right passages, filter by author, book, genre or death year, get more results, and read the text around a passage.
---

Search finds passages by meaning and by wording, then reranks the matches for relevance. These examples use the API; the [`search`](/mcp/tools#search) and [`fetch`](/mcp/tools#fetch) tools take the same arguments.

## Write the query

- **Ask for the idea.** A question or a short description, such as "patience at the first shock of a calamity", finds passages that discuss it, even in other words.
- **Use Arabic for exact wording.** The texts are Arabic, so an Arabic query also matches passages that use those words, such as a phrase from a hadith: `الصبر عند الصدمة الأولى`.
- **Keep one topic per query.** Run two searches for two questions, rather than one search that mixes them.

A query can be up to 2,000 characters.

```bash cURL
curl https://api.qaf.ai/v1/search \
  -H "Authorization: Bearer $QAF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "patience at the first shock of a calamity", "limit": 5}'
```

```json MCP
{
  "name": "search",
  "arguments": {
    "query": "patience at the first shock of a calamity",
    "limit": 5
  }
}
```

## Filter by author or book

Filters take IDs, not names. Look the name up first, then pass the ID:

```bash
curl "https://api.qaf.ai/v1/catalog/lookup?type=author&query=Ibn%20Hajar%20al-Asqalani" \
  -H "Authorization: Bearer $QAF_API_KEY"
```

```json
{
  "candidates": [
    {
      "type": "author",
      "id": 202,
      "label": "Ibn Hajar al-Asqalani",
      "deathYearAH": 852,
      "deathInexactLabel": null,
      "matchScore": 1
    },
    {
      "type": "author",
      "id": 2939,
      "label": "Bashshar Awwad Maruf",
      "deathYearAH": null,
      "deathInexactLabel": null,
      "matchScore": 0.384
    }
  ]
}
```

When several candidates look alike, choose by death year or by the book you have in mind. Then search that author's books:

```bash cURL
curl https://api.qaf.ai/v1/search \
  -H "Authorization: Bearer $QAF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "النية", "filters": {"authorIds": [202]}}'
```

```json MCP
{
  "name": "search",
  "arguments": {
    "query": "النية",
    "filters": { "authorIds": [202] }
  }
}
```

Filters match a passage's book and author, not what the passage mentions. To find what other scholars said about Ibn Hajar, search for his name instead of filtering by it.

## Filter by genre

A genre describes a book, such as `hadith-commentary` or `hanbali-fiqh`. Use one when you want results from books of that kind; to find passages about a topic, put the topic in the query. [The Qaf library](/library#genres) lists every genre.

```json
{ "query": "الوقف", "filters": { "genres": ["hanbali-fiqh"] } }
```

## Filter by death year

`deathYearAH` limits results to authors who died in a range of Hijri years. This finds passages by authors who died before 500 AH:

```json
{ "query": "الإخلاص", "filters": { "deathYearAH": { "lt": 500 } } }
```

Combine `gt`, `gte`, `lt` and `lte` for a range, such as `{ "gte": 600, "lte": 800 }`. Authors with no recorded death year are left out.

## Combine filters

By default every filter field must match (`"filterOperator": "AND"`): Hanbali books by authors who died before 800 AH. Set `"filterOperator": "OR"` to accept a passage that matches any field. IDs within one list always combine with OR, so `"authorIds": [202, 423]` means either author.

If no book can match the filters together, search returns `400` with `data.reason` `no_matching_books` instead of an empty list.

## Get more results

`limit` returns up to 15 passages. To get further passages for the same query, send the IDs you already have in `excludeIds`, up to 200:

```json
{
  "query": "الصبر عند المصيبة",
  "limit": 15,
  "excludeIds": [
    "d9335f69-e54b-59ae-a78c-50db734b8d50",
    "c89a5395-46f6-5416-afb5-5e55e66e11f7"
  ]
}
```

## Read around a passage

A passage is a short excerpt. To read the argument it belongs to, ask for its neighbours with `radius`, up to five on each side:

```bash cURL
curl "https://api.qaf.ai/v1/passages/d9335f69-e54b-59ae-a78c-50db734b8d50?radius=2" \
  -H "Authorization: Bearer $QAF_API_KEY"
```

```json MCP
{
  "name": "fetch",
  "arguments": {
    "id": "d9335f69-e54b-59ae-a78c-50db734b8d50",
    "radius": 2
  }
}
```

The response has the passage, plus `before` and `after` in reading order. Each neighbour has its own `id`, so you can keep reading from either end. A passage near the start or end of a book has fewer neighbours.