public · read-only · no auth

Agent & developer docs

the canonical Masnavi, callable — MCP, REST, WebMCP, plain text

Endpoints

The same ten tools, four ways to reach them — pick whichever your client supports.

MCP (streamable HTTP):  POST https://masnavi.ai/mcp
REST + OpenAPI:         https://masnavi.ai/api/  ·  /api/openapi.json
Plain text:             /api/range.txt  ·  /api/section.txt  ·  /corpus.jsonl
WebMCP (in-browser):    navigator.modelContext — tools register on every page

WebMCP needs no connector — an in-browser agent (Chrome/Edge, behind a flag today) discovers the tools just by loading any page. llms.txt has the one-page agent summary.

Citation format

Every beyt has a canonical citation: M{daftar}:{beyt_in_daftar} with daftar ∈ 1..6 — e.g. M3:1278. A global index g:{n} (1..25635) is also accepted. Localized page URLs exist for every language (/ar/beyt/M1:1, /tr/d/2, …) — same content, chrome and default rendering in that language.

Tools

search(query, daftar?, limit=10, offset=0)

Full-text search over the Persian text. Ranked beyts with citations and section context.

search_meaning(query, daftar?, limit=10)

Semantic search, any language. Finds the beyts closest in meaning to the query — a theme, feeling, or idea in English, Persian, Spanish, … — e.g. “feeling separated from your origin” → M1:1. Each hit carries a similarity score.

lookup(citation? | daftar+beyt_in_daftar | beyt_global, before=0, after=0)

One beyt plus optional surrounding context (before/after capped at 20).

verify(text, fuzzy_threshold=0.82)

The anti-hallucination tool. Pass a candidate Rumi quote; get exact / fuzzy / not_found with citations. Call it before repeating any Rumi quote.

get_section(section_id? | slug?)

One full named section (story / بخش) with all its beyts. For stories spanning sections use get_range.

get_range(start, end | start_global, end_global)

All beyts between two endpoints, grouped by section, crossing sections and daftars — up to 500 in one call. The Muʿawiya & Iblis arc (M2:2608 → M2:2775, 168 beyts, 12 sections) is one call instead of fourteen.

find_sections(query, daftar?, limit=30)

Search section titles by Persian phrase → slugs + beyt-global ranges. Combine with get_range.

table_of_contents(daftar?)

Sections with beyt-ranges and counts.

random_beyt(daftar?)

One randomly-selected beyt.

explain(citation)

Per-beyt commentary from primary sources — currently Abdolkarim Soroush's recorded lectures (daftars 1 & 6, AI-reconstructed, with session + timestamp references). Provenance: /sources.

The Divan-e Shams (Rumi's ghazals)

The server also carries Rumi's other great work — the 3,230 ghazals (34,603 beyts) of the دیوان شمس (Divan-e Kabir). Citations: G{ghazal}:{beyt}, e.g. G1393:1 = «مرده بدم زنده شدم…». Human pages: /divan (browse) and /divan/{ghazal} (read + translate).

search_divan(query, limit=10, offset=0)

Full-text search over the ghazal beyts (exact Persian words). REST: GET /api/divan/search.

search_divan_meaning(query, limit=8)

Semantic search, any language. Returns the ghazals closest in meaning to a theme — each with its best-matching couplet as preview and a similarity score. Couplet-level and whole-ghazal vectors are both searched. REST: GET /api/divan/search_meaning.

get_ghazal(number | citation)

One complete ghazal with every beyt, plus prev/next numbers. REST: GET /api/divan/ghazal?number=1393.

On-demand renderings (REST)

Any beyt can be rendered — translation, meaning, explanation, glossary — in 32+ languages. Reads are free and cache-only; generation is rate-limited.

GET  /api/translate_beyt?citation=M1:1&lang=de     cache read — 404 if not generated yet
POST /api/translate_beyt    {"citation","lang"}      generate (rate-limited, cached after)
GET|POST /api/translate_soroush                      same, for Soroush's commentary
GET|POST /api/translate_intro?daftar=1&lang=tr      same, for the six daftar prefaces
GET  /api/languages                                  supported languages + models
GET  /api/beyt/M1:1/explanations                     all commentary for a beyt (JSON)

Everything returned by these endpoints is AI-generated and labeled as such (model, date, confidence) — see /sources for what is human and what is machine on this site.

Plain text & bulk

MCP resources