Skip to content
Developers
Esc
↑↓navigate↵open⌘Jpreview
On this page

API overview

The Qaf API v1 at api.qaf.ai/v1. Endpoints, request and response format, authentication, the OpenAPI document, request IDs and the versioning policy.

The Qaf API lets your own code search and read the Qaf library. It runs the same operations as the MCP server and returns the same JSON.

https://api.qaf.ai/v1

Endpoints

Endpoint Does MCP tool
POST /v1/search Searches passages, optionally filtered by author, book, genre or death year. search
GET /v1/passages/{id} Reads a passage, with up to five neighbouring passages on each side. fetch
GET /v1/catalog/lookup Resolves an author or book name to IDs for search filters. lookup_catalog
GET /v1/quran/verses Gets the Arabic text of Qur’an verses, with the surah name and an English translation. get_quran_verses

The API reference lists every field, limit and response. The Qaf library explains the passage fields, IDs and genres.

Requests and responses

  • Format: requests and responses are JSON in UTF-8. Send Content-Type: application/json with a request body.
  • Parameters: POST /v1/search takes a JSON body. The GET endpoints take query parameters, and the passage ID goes in the path.
  • HEAD: works wherever GET does. It returns the same status and headers without the body, and counts toward the rate limit like a GET.
  • Unknown fields: the search body refuses fields it doesn’t define with a 422, so a misspelled filter fails instead of being ignored.
  • Body size: a request body over 64 KiB gets a 413.
  • Names: fields are camelCase, such as sequenceNumber. Set locale to ar for Arabic book and author names; it defaults to en.

Authentication

Send an API key from qaf.ai Settings › API keys as a bearer token:

Authorization: Bearer qaf_sk_…

Keep keys on your server. See Authentication.

Limits

Each account can make 60 requests a minute and 1,000 searches a day, across all its keys. See Rate limits.

OpenAPI document

The OpenAPI 3.1 document for v1 is at:

https://api.qaf.ai/v1/openapi.json

It needs no key. Use it to generate a client or to give an agent the exact schema. It is the same document this site’s API reference is built from.

Request IDs

Every response has an X-Request-Id header, including errors. The only exception is the answer to a browser’s CORS preflight (OPTIONS) request. When you email us at contact@qaf.ai about a response, include it.

Browsers

The API accepts cross-origin requests from any site, so the reference’s Try it panel can call it. That doesn’t make it safe to put a key in a web page or an app: anyone who loads the page can read the key. Call the API from your server.

Versioning

v1 changes only in ways that keep existing clients working. Write your client to:

  • ignore response fields it doesn’t know;
  • handle enum values and error codes it doesn’t know, such as a new genre slug or a new lookup candidate type.

These changes can happen in v1 without notice:

  • new endpoints and new optional request fields;
  • new response fields, enum values and error codes;
  • higher limits.

Renaming or removing a field, tightening a type or a limit, or changing a default needs a new version, v2. When part of v1 is deprecated, its responses carry Deprecation and Link headers that point to a migration guide, and the changelog says so.