# Nakafa Developer Resources > For AI agents: use [llms.txt](https://nakafa.com/llms.txt) for the site index. Markdown versions are available by appending `.md` to content URLs or sending `Accept: text/markdown`. URL: https://nakafa.com/en/developers Source: https://raw.githubusercontent.com/nakafaai/aksara/11c10d705985738d79e314865fa46c0cd824756b/packages/corpus/pages/developers/en.mdx Use Nakafa's public REST API, OpenAPI contract, MCP server, and command-line client in reliable education workflows. --- # Nakafa Developer Resources Last updated: August 27, 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. ## Verified implementation These public interfaces were verified live against Nakafa commit [`2fae54fec31b7cd630a56933b613fa5b9504695a`](https://github.com/nakafaai/nakafa.com/commit/2fae54fec31b7cd630a56933b613fa5b9504695a): the REST index and OpenAPI contract return the same release identity, the canonical MCP bridge completes protocol discovery, and `nakafa-cli@0.1.0` is available from npm. At that revision, [`api.ts`](https://github.com/nakafaai/nakafa.com/blob/2fae54fec31b7cd630a56933b613fa5b9504695a/packages/backend/convex/routes/agent/api.ts) owns REST, [`route.ts`](https://github.com/nakafaai/nakafa.com/blob/2fae54fec31b7cd630a56933b613fa5b9504695a/packages/backend/convex/routes/agent/mcp/route.ts) owns MCP, [`document.ts`](https://github.com/nakafaai/nakafa.com/blob/2fae54fec31b7cd630a56933b613fa5b9504695a/packages/backend/agent/openapi/document.ts) generates OpenAPI, and [`program.ts`](https://github.com/nakafaai/nakafa.com/blob/2fae54fec31b7cd630a56933b613fa5b9504695a/packages/cli/src/program.ts) owns the CLI command surface. ## Public REST API The canonical API base is [https://api.nakafa.com/v1](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 links - `GET /v1/health`: service health - `GET /v1/search`: search by query, section, locale, limit, and offset - `GET /v1/content?ref=...`: retrieve an exact content ID or canonical URL - `GET /v1/taxonomy`: inspect the published taxonomy - `GET /v1/quran/{surah}`: retrieve a typed verse range Search returns 10 results by default and accepts at most 50 per request. Use `offset`, `has_more`, and `next_offset` to continue a result set without guessing. Clients should budget for no more than 120 requests per 60 seconds from one IP and handle HTTP 429 responses with backoff. File: search.sh ```bash curl "https://api.nakafa.com/v1/search?query=linear%20equations&locale=en&limit=5" ``` ## OpenAPI and errors The [Nakafa OpenAPI 3.1 contract](https://api.nakafa.com/openapi.json) 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. File: problem.json ```json { "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" } ``` ## Model Context Protocol The canonical MCP endpoint is [https://nakafa.com/mcp](https://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_content` - `nakafa_get_content` - `nakafa_get_taxonomy` - `nakafa_get_quran_reference` Modern 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. File: mcp.http ```http POST /mcp HTTP/1.1 Host: 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: 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":{}}}} ``` ## Command line 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. File: nakafa-cli.sh ```bash npm install --global nakafa-cli nakafa search linear equations nakafa quran 1 --from-verse 1 --to-verse 7 --pretty nakafa mcp ``` The CLI preserves Problem Details JSON on standard error and uses stable nonzero exit categories for invocation, API, and network or server failures. ## Machine-readable discovery - [Developer page](https://nakafa.com/en/developers) - [Agent instructions](https://nakafa.com/skill.md) - [Root agent index](https://nakafa.com/llms.txt) - [OpenAPI 3.1](https://api.nakafa.com/openapi.json)