Search passages

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

Authorization

AuthorizationBearer token · headerrequired

An API key from qaf.ai Settings › API keys.

Request body

requiredapplication/json

querystringrequired

What to search for, in Arabic or English.

min length 1 · max length 2000

filtersobject

Restrict results by author, book, death year or genre. Filters match a passage's book and author, not what the passage mentions.

Show properties

authorIdsinteger[]

Author IDs, from GET /catalog/lookup or a passage's author.id.

min items 1 · max items 20

bookIdsstring<uuid>[]

Book IDs, from GET /catalog/lookup or a passage's book.id.

min items 1 · max items 20

deathYearAHobject

Bounds on the author's death year, in AH. Give at least one; all must hold.

Show properties

gtinteger

gteinteger

ltinteger

lteinteger

genresstring[]

Genre slugs. A genre describes a book, not a topic, so use one only to search books of that genre.

min items 1 · max items 20

filterOperatorstring

Combine supplied filter dimensions with AND (default) or OR. Values within each ID list always use OR; all death-year bounds must hold together.

Allowed:ANDOR

limitinteger

Passages to return.

min 1 · max 15 · default: 5

excludeIdsstring<uuid>[]

IDs of passages you already have; the search skips them. Pass the IDs from earlier results to get further passages for the same query.

max items 200

localestring

Language for book and author names; Arabic names are always included.

default: "en"

Allowed:aren

Responses

200

The matching passages, ranked by relevance.

resultsobject[]required

Show properties

Array of object

idstring<uuid>required

Stable passage ID. Read it with GET /passages/{id}, or skip it in a later search with excludeIds.

titlestringrequired

Book, author and printed page.

urlstring<uri>required

Opens the printed page in the Turath reader; cite it.

textstringrequired

The passage's Arabic text as printed in the edition, with vowel marks where the edition has them.

footnotesstring

pagesobject[]required

Printed volume and page numbers the passage spans.

Show properties

Array of object

volstring | nullrequired

Show properties

Any of:

string

string

null

null

pagenumber | nullrequired

Show properties

Any of:

number

number

null

null

bookobjectrequired

Show properties

idstring<uuid>required

titlestringrequired

titleArabicstringrequired

authorobjectrequired

Show properties

idintegerrequired

namestringrequired

nameArabicstringrequired

versionIdintegerrequired

The printed edition the passage comes from.

sequenceNumberintegerrequired

Position within the edition.

400

The request can't be processed as sent, such as a filter with an unknown author ID. data.reason, when present, says why.

codestringrequired

Allowed:BAD_REQUEST

statusintegerrequired

messagestringrequired

dataobject

Show properties

reasonstring

401

The API key is missing, invalid or revoked.

codestringrequired

Allowed:UNAUTHORIZED

statusintegerrequired

messagestringrequired

403

The key's account can't use the API.

codestringrequired

Allowed:FORBIDDEN

statusintegerrequired

messagestringrequired

413

The request body is larger than 64 KiB.

codestringrequired

Allowed:PAYLOAD_TOO_LARGE

statusintegerrequired

messagestringrequired

422

A field is invalid. data.fieldErrors lists the problems by field.

codestringrequired

Allowed:INPUT_VALIDATION_FAILED

statusintegerrequired

messagestringrequired

dataobject

Show properties

formErrorsstring[]required

fieldErrorsobjectrequired

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.

codestringrequired

Allowed:RATE_LIMITED

statusintegerrequired

messagestringrequired

dataobject

Show properties

retryAfterintegerrequired

Seconds to wait.

min 0

reasonstringrequired

Which limit was reached: minute, the account's requests per minute; day, its searches per day; or invalid_keys, a key that doesn't exist or was revoked, from an address that has sent too many such keys.

Allowed:minutedayinvalid_keys

500

Something went wrong on our side.

codestringrequired

Allowed:INTERNAL_SERVER_ERROR

statusintegerrequired

messagestringrequired

503

Qaf could not complete the request in time, or a service it relies on is unavailable. Retry shortly.

codestringrequired

Allowed:SERVICE_UNAVAILABLE

statusintegerrequired

messagestringrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Bodyapplication/json

Request body

Request

curl -X POST 'https://api.qaf.ai/v1/search' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "الصبر عند المصيبة"
}'

const response: Response = await fetch("https://api.qaf.ai/v1/search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"query\": \"الصبر عند المصيبة\"\n}"
});

import requests

response = requests.post(
    "https://api.qaf.ai/v1/search",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"query\": \"الصبر عند المصيبة\"\n}",
)

Response

{
  "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
    }
  ]
}

{
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "The request can't be processed as sent.",
  "data": {
    "reason": "string"
  }
}

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "Invalid API key."
}

{
  "code": "FORBIDDEN",
  "status": 403,
  "message": "This Qaf account can't use the API."
}

{
  "code": "PAYLOAD_TOO_LARGE",
  "status": 413,
  "message": "The request body is larger than 64 KiB."
}

{
  "code": "INPUT_VALIDATION_FAILED",
  "status": 422,
  "message": "The request has invalid fields.",
  "data": {
    "formErrors": [
      "string"
    ],
    "fieldErrors": {
      "property1": [
        "string"
      ],
      "property2": [
        "string"
      ]
    }
  }
}

{
  "code": "RATE_LIMITED",
  "status": 429,
  "message": "Too many requests. Try again later.",
  "data": {
    "retryAfter": 0,
    "reason": "minute"
  }
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "message": "Something went wrong on our side. Try again later."
}

{
  "code": "SERVICE_UNAVAILABLE",
  "status": 503,
  "message": "Qaf could not complete this request. Try again shortly."
}