Migrate from the partner API
Move from the deprecated partner search API at /public/v1/search to the Qaf API v1, with the request and response fields mapped one by one.
The partner search API at https://api.qaf.ai/public/v1/search is deprecated. It keeps working for now, and no shutdown date is set. Its responses carry these headers:
Deprecation: @1794614400
Link: <https://developers.qaf.ai/api/migrate>; rel="deprecation"; type="text/html"The Deprecation date is 14 November 2026. When a shutdown date is set, we will announce it in the changelog and add a Sunset header first.
The Qaf API v1 replaces it with hybrid semantic and keyword search, reranked for relevance, plus passage reading, catalog lookup and Qur’an verses.
1. Create a new key
Partner keys (qaf_live_…) don’t work with v1, and v1 keys don’t work with the partner API. Create a key in Settings › API keys on qaf.ai; see Authentication. The header stays the same:
Authorization: Bearer qaf_sk_…2. Change the URL
| Partner API | API v1 |
|---|---|
POST https://api.qaf.ai/public/v1/search |
POST https://api.qaf.ai/v1/search |
3. Change the request body
The v1 search body refuses fields it doesn’t define with a 422, so a request that still sends topK or authorIds at the top level fails instead of running unfiltered. Moving categoryIds or versionIds into filters as they are fails the same way: v1 refuses filters.categoryIds and filters.versionIds.
| Partner field | v1 field | Notes |
|---|---|---|
query (1–500 characters) |
query (1–2,000 characters) |
Trimmed before searching. |
mode (semantic or keyword) |
none | v1 always runs hybrid search and reranks the matches. Remove the field. |
topK (1–50, default 10) |
limit (1–15, default 5) |
Page further with excludeIds; see Search and read passages. |
authorIds |
filters.authorIds |
The same author IDs, at most 20. |
categoryIds |
filters.genres |
Genre slugs instead of IDs, at most 20. The genre table maps each ID to its slug. |
versionIds |
filters.bookIds |
No v1 filter takes edition IDs. Use the book’s UUID, from a passage’s book.id or from catalog lookup. At most 20. |
| (filters always combined with OR) | filterOperator |
v1 requires every filter field by default (AND). Set "filterOperator": "OR" to keep the partner API’s behaviour. |
For example, this partner request:
{ "query": "الصبر", "topK": 10, "authorIds": [423], "categoryIds": [7] }becomes:
{
"query": "الصبر",
"limit": 10,
"filters": { "authorIds": [423], "genres": ["hadith-commentary"] },
"filterOperator": "OR"
}4. Read the new response
v1 returns { "results": [passage, …] } like the partner API, with different passage fields:
| Partner field | v1 field |
|---|---|
id |
id, unchanged. Old IDs work with GET /v1/passages/{id}. |
text |
text: the edition’s text, with vowel marks where the edition has them. The partner API returned it with vowel marks removed. |
footnotes (null when empty) |
footnotes, left out when empty |
pages |
pages, unchanged |
author_id |
author.id, with author.name and author.nameArabic |
version_id |
versionId |
sequence_number |
sequenceNumber |
category_ids |
none. Look up the book with catalog lookup to get its categoryId. |
score |
none. Results come best match first. |
| none | title: the book, author and first printed page as one line |
| none | url: a link to the printed page, for citations |
| none | book: id, title and titleArabic |
5. Handle the new errors and limits
- Errors have the same
{ code, status, message, data }shape, with new codes. See Errors. - The limit is 60 requests a minute per account, across all keys, and 1,000 searches a day. See Rate limits.
If something in your integration has no v1 equivalent, email us at contact@qaf.ai.