---
title: Quickstart
description: Create a Qaf API key, store it, search the library and read the passages around a result, with cURL, TypeScript and Python examples.
---

1. **Create an API key**

    Open [Settings › API keys](https://qaf.ai/login?redirect=%2F%3Fsettings%3Dapi-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.

2. **Store the key**

    Keep the key in an environment variable rather than in your code:

    ```bash
    export QAF_API_KEY="qaf_sk_…"
    ```

3. **Search the library**

    Send a query in Arabic or English to `POST /v1/search`:

    ```bash cURL
    curl https://api.qaf.ai/v1/search \
      -H "Authorization: Bearer $QAF_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query": "الصبر عند المصيبة", "limit": 3}'
    ```

    ```ts TypeScript
    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);
    ```

    ```python Python
    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:

    ```json
    {
      "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
    }
    ```

4. **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`:

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

    ```ts TypeScript
    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);
    ```

    ```python Python
    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"]))
    ```

## Next steps

**[Search and read passages](/guides/search)**

Filter by author, book, genre or death year, and page through results.

**[Cite passages](/guides/citations)**

Show the book, author and printed page for every passage you use.

**[Errors](/api/errors)**

Read the error format and decide what to retry.

**[API reference](/reference)**

Every endpoint, field and limit.