Read a passage

Returns a passage by ID, with up to radius neighbouring passages on each side, in reading order. Neighbours carry their own IDs, so you can keep reading from either end.

GET/passages/{id}

Authorization

AuthorizationBearer token · headerrequired

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

Path parameters

idstring<uuid>required

A passage ID from search results or from another passage's neighbours.

Query parameters

radiusinteger

Neighbouring passages to include on each side.

min 0 · max 5 · default: 0

localestring

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

default: "en"

Allowed:aren

Responses

200

The passage and its neighbours.

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.

beforeobject[]required

Preceding passages, in reading order.

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.

afterobject[]required

Following passages, in reading order.

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.

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

404

No passage has this ID.

codestringrequired

Allowed:NOT_FOUND

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

Parameters

idpath*A passage ID from search results or from another passage's neighbours.radiusqueryNeighbouring passages to include on each side.localequeryLanguage for book and author names; Arabic names are always included.

Request

curl -X GET 'https://api.qaf.ai/v1/passages/d9335f69-e54b-59ae-a78c-50db734b8d50' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

const response: Response = await fetch("https://api.qaf.ai/v1/passages/d9335f69-e54b-59ae-a78c-50db734b8d50", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

import requests

response = requests.get(
    "https://api.qaf.ai/v1/passages/d9335f69-e54b-59ae-a78c-50db734b8d50",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json"
    },
)

Response

{
  "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,
  "before": [
    {
      "id": "0d4b07f3-22a9-596d-8c73-9cd01630967f",
      "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
        }
      ],
      "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": 4928
    }
  ],
  "after": [
    {
      "id": "e16a944f-0af5-51d8-9c75-6ac535d3c92a",
      "title": "Fayd al-Qadir — Abd al-Rauf al-Munawi, vol. 4, p. 234",
      "url": "https://app.turath.io/book/21660?print_page=4%2C234",
      "text": "… لأن الصبر يدخل في كل باب بل في كل مسألة من مسائل الدين …",
      "pages": [
        {
          "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": 4930
    }
  ]
}

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

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

{
  "code": "NOT_FOUND",
  "status": 404,
  "message": "No passage has this ID."
}

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