Quickstart
Create a Qaf API key, store it, search the library and read the passages around a result, with cURL, TypeScript and Python examples.
Create an API key
Open Settings › API keys on qaf.ai and sign in if asked. Select Create key, give the key a name and copy it. The key is shown only once.
Store the key
Keep the key in an environment variable rather than in your code:
export QAF_API_KEY="qaf_sk_…"Search the library
Send a query in Arabic or English to POST /v1/search:
curl https://api.qaf.ai/v1/search \
-H "Authorization: Bearer $QAF_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "الصبر عند المصيبة", "limit": 3}'const response = await fetch("https://api.qaf.ai/v1/search", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.QAF_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ query: "الصبر عند المصيبة", limit: 3 }),
});
if (!response.ok) throw new Error(await response.text());
const { results } = await response.json();
for (const passage of results) console.log(passage.title, passage.url);import os
import requests
response = requests.post(
"https://api.qaf.ai/v1/search",
headers={"Authorization": f"Bearer {os.environ['QAF_API_KEY']}"},
json={"query": "الصبر عند المصيبة", "limit": 3},
timeout=30,
)
response.raise_for_status()
for passage in response.json()["results"]:
print(passage["title"], passage["url"])Each result is a passage with its book, author, printed pages and a link to the page. One result looks like this, with its text shortened:
{
"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
}Read around a passage
Pass a result’s id to GET /v1/passages/{id}. radius adds up to five neighbouring passages on each side, in before and after:
curl "https://api.qaf.ai/v1/passages/d9335f69-e54b-59ae-a78c-50db734b8d50?radius=1" \
-H "Authorization: Bearer $QAF_API_KEY"const id = "d9335f69-e54b-59ae-a78c-50db734b8d50";
const response = await fetch(
`https://api.qaf.ai/v1/passages/${id}?radius=1`,
{ headers: { Authorization: `Bearer ${process.env.QAF_API_KEY}` } }
);
if (!response.ok) throw new Error(await response.text());
const passage = await response.json();
console.log(passage.before.length, passage.text, passage.after.length);import os
import requests
passage_id = "d9335f69-e54b-59ae-a78c-50db734b8d50"
response = requests.get(
f"https://api.qaf.ai/v1/passages/{passage_id}",
headers={"Authorization": f"Bearer {os.environ['QAF_API_KEY']}"},
params={"radius": 1},
timeout=30,
)
response.raise_for_status()
passage = response.json()
print(len(passage["before"]), passage["text"], len(passage["after"]))