Search and read passages

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 and 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.

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}'

{
  "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:

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

{
  "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:

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

{
  "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 lists every genre.

{ "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:

{ "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:

{
  "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:

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

{
  "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.