For AI agents: use /llms.txt for the Nakafa content index.
Last updated: September 20, 2026
Nakafa provides public, machine-readable access to multilingual learning materials and bounded Quran references. These interfaces suit agents and applications that need typed inputs, predictable errors, and canonical content references. They are read-only, require no Nakafa account, and do not expose private learner records, purchases, or account actions.
These public interfaces were verified live against Nakafa commit 927d7f681a43acb205d8abcbd63101a8ecd31b41: the REST index, OpenAPI contract, and MCP endpoint return the same release identity, and @nakafa/cli@0.1.1 is available from npm with verifiable provenance.
At that revision, api.ts owns REST, route.ts owns MCP, document.ts generates OpenAPI, and program.ts owns the CLI command surface.
The canonical API base is https://api.nakafa.com/v1. Start with the service index and use search to find a relevant item. Retrieve a result by content ID only when it includes markdown_url. A try-out catalog result without markdown_url is citation-only and links to its canonical application URL. The API also exposes the published taxonomy and bounded Quran verse references.
GET /v1: service identity and discovery linksGET /v1/health: service healthGET /v1/search: search by query, section, locale, limit, and offsetGET /v1/content?ref=...: retrieve an exact content ID or canonical URLGET /v1/taxonomy: inspect the published taxonomyGET /v1/quran/{surah}: retrieve a typed verse rangeSearch returns 10 results by default and accepts at most 10 per request. The search window contains at most 10 results, with offset from 0 to 9. When using a smaller limit, follow has_more and next_offset to read the next page within that window. Clients should budget for no more than 120 requests per 60 seconds from one IP and handle HTTP 429 responses with backoff.
curl "https://api.nakafa.com/v1/search?query=linear%20equations&locale=en&limit=5"The Nakafa OpenAPI 3.1 contract describes every public operation, input, response, and example. Compatible additions remain in v1. A breaking change requires a new major path.
Convex-owned API failures use RFC 9457 Problem Details with the media type application/problem+json. Each response includes a stable code, a human-readable detail, a concrete resolution, and a traceable request_id. A Vercel Firewall HTTP 429 can stop a request before it reaches Convex, so clients must treat that platform-owned response as an exception and retry with backoff.
{
"type": "https://nakafa.com/problems/invalid-request",
"title": "Invalid request",
"status": 400,
"detail": "Unknown query parameter: page.",
"instance": "/v1/search",
"code": "INVALID_REQUEST",
"resolution": "Use only these query parameters: limit, locale, offset, query, section.",
"request_id": "request-example"
}The canonical MCP endpoint is https://mcp.nakafa.com/mcp. Use MCP when an agent already supports tool discovery and structured tool calls. Use REST for ordinary HTTP integrations or generated OpenAPI clients. Both interfaces execute the same Convex-owned capability and verify the same signed Aksara publication.
The server exposes four read-only tools:
nakafa_search_contentnakafa_get_contentnakafa_get_taxonomynakafa_get_quran_referenceModern clients use Streamable HTTP. Protocol 2026-07-28 replaces the legacy initialize lifecycle with server/discover and a per-request _meta envelope. A client discovers the supported revision first, then lists or calls tools with the same envelope. Nakafa accepts this documented protocol revision and reports every supported revision through discovery. Server identity and capabilities come from the server/discover response. The stateless Nakafa endpoint does not expose a separate GET manifest.
POST /mcp HTTP/1.1
Host: mcp.nakafa.com
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover
{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"example-client","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}
###
POST /mcp HTTP/1.1
Host: mcp.nakafa.com
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/list
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"example-client","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}The official Node 24 package is @nakafa/cli, with the executable nakafa. It calls the public REST API and prints compact JSON by default. Add --pretty for readable output or --api-base when verifying a local or independently hosted compatible API endpoint.
npm install --global @nakafa/cli
nakafa search linear equations
nakafa quran 1 --from-verse 1 --to-verse 7 --pretty
nakafa mcpThe CLI preserves Problem Details JSON on standard error and uses stable nonzero exit categories for invocation, API, and network or server failures.