Ganjoor RMuseum API
Agent-ready OpenAPI document · curated by JenticMediaContent DeliveryapiKey471 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Read classical Persian poems, poets, categories, and recitations from Ganjoor; submit corrections, manage bookmarks, and access museum artifact metadata.
Use for: Retrieve a random Persian poem of the day, Get a specific Hafez ghazal by its poem id, List all books by a given Persian poet, Find all poems in a category by category id
Not supported: Does not handle modern publishing, payments, or live event streaming - use for classical Persian poetry archive access and cultural artifact management only.
Jentic publishes the only available OpenAPI specification for RMuseum API, keeping it validated and agent-ready. The RMuseum API powers Ganjoor.net, the largest open archive of classical Persian poetry, and exposes 470+ endpoints for browsing poets, books, categories, individual poems and couplets, audio recitations, artifact images, comments, bookmarks, and AI-generated summaries. The same backend supports museum-style cultural artifact metadata (the 'RMuseum' name) alongside the poetry archive. Auth uses a bearer token in the Authorization header for write and user-scoped operations; many read endpoints are public.
Install Jentic One Beta
Connect the RMuseum API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the RMuseum API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fganjoor.net%2Fganjoor" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fganjoor.net%2Fganjoor" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with RMuseum API.
Retrieve a specific poem by id with /api/ganjoor/poem/{id}, including its couplets and metadata
Pull a random Persian poem from the archive via /api/ganjoor/poem/random for daily-poem features
Browse poet categories and tables of contents through /api/ganjoor/cat/{id}
Bookmark specific poems or individual couplets per authenticated user via /api/ganjoor/bookmark
Submit and moderate poem and category corrections through the /api/ganjoor/poem/correction and /api/ganjoor/cat/correction endpoints
Manage cultural artifact records and image syncing via the /api/artifacts/ganjoor endpoints
Use Cases
Patterns agents use RMuseum API for, with concrete tasks.
★ Daily Persian Poem Channel
Send a daily Persian poem with translation context to users via email, RSS, or a chat bot. The agent calls /api/ganjoor/poem/random, formats the couplets, and posts to the destination. Avoids hand-curating a daily classical-poetry digest.
Call GET /api/ganjoor/poem/random, take the title and first 4 couplets, and post them to the configured channel each morning
Poet Anthology Browser
Build a reading app or research tool that lets users navigate a poet's full corpus by book and category. The agent uses /api/ganjoor/cat/{id} to walk the table of contents and /api/ganjoor/poem/{id} to load each poem. Supports literature classrooms and Persian-language learning apps.
GET /api/ganjoor/cat/{id} to list a poet's books, then for each child id call GET /api/ganjoor/poem/{id} and assemble a paginated reader view
Crowdsourced Correction Workflow
Let community editors propose fixes to misprinted couplets and have moderators review them. The agent submits to /api/ganjoor/poem/correction on behalf of a signed-in user and pulls /api/ganjoor/poem/correction/next for moderators. Keeps the canonical archive accurate while distributing review work.
POST /api/ganjoor/poem/correction with the poem id and corrected couplet text, then have a moderator agent fetch GET /api/ganjoor/poem/correction/next and call moderate on it
Agent-Led Research Assistant Through Jentic
Connect an AI agent to the Ganjoor archive so it can answer cultural-literature queries with citations to specific poems and couplets. The agent discovers the API via Jentic, loads the relevant operation, and returns the source poem id and couplet index in its answer. Brings classical Persian poetry into general-purpose research agents that previously could only quote from training data.
Use Jentic search query 'retrieve a Persian poem' to load the ganjoor_get_poem tool, execute with the poem id, and return the title, poet, and couplets
Key Endpoints
471 endpoints — jentic publishes the only available openapi specification for rmuseum api, keeping it validated and agent-ready.
METHOD
PATH
DESCRIPTION
GET
/api/ganjoor/poem/{id}
Retrieve a specific poem with its couplets
GET
/api/ganjoor/poem/random
Return a random poem from the archive
GET
/api/ganjoor/cat/{id}
Retrieve a category or poet table of contents
GET
/api/ganjoor/poets
List poets in the archive
POST
/api/ganjoor/poem/correction
Submit a correction for a poem
POST
/api/users/login
Log in and obtain a bearer token
GET
/api/ganjoor/poem/{id}
Retrieve a specific poem with its couplets
GET
/api/ganjoor/poem/random
Return a random poem from the archive
GET
/api/ganjoor/cat/{id}
Retrieve a category or poet table of contents
GET
/api/ganjoor/poets
List poets in the archive
POST
/api/ganjoor/poem/correction
Submit a correction for a poem
POST
/api/users/login
Log in and obtain a bearer token
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the RMuseum API by hand means formatting its 'bearer {token}' Authorization header against api.ganjoor.net and mapping its large set of poem, category, and poet endpoints yourself. Through Jentic you install once, import the RMuseum API from the API Directory, store the token once, and your agent calls it.
Permission scoping
RMuseum puts the poem and category ids in the URL path (/api/ganjoor/poem/{id}, /api/ganjoor/cat/{id}), so a rule can pin your agent to reading specific poems or categories and nothing else. You choose the operations it may call, so submitting a poem correction is not included unless you add it.
Credential isolation
Your RMuseum bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'get a Persian poem by id' or 'fetch a random poem', and Jentic returns the matching RMuseum operation with its input schema so the agent calls the right endpoint without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using RMuseum API through Jentic.
Why is there no official OpenAPI spec for RMuseum API?
Ganjoor.net does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call RMuseum API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.
What authentication does the RMuseum API use?
User-scoped endpoints require a bearer token in the Authorization header in the format 'bearer {token}', obtained via POST /api/users/login. Many read endpoints (random poem, public categories) work without auth. Through Jentic the token is stored encrypted in the vault.
Can I retrieve a random Persian poem with the RMuseum API?
Yes. GET /api/ganjoor/poem/random returns a randomly selected poem from the entire Ganjoor archive, including its title, poet reference, and full set of couplets, with no query parameters required.
How do I submit a correction for a misprinted poem?
Authenticate first, then POST /api/ganjoor/poem/correction with the poem id and the proposed couplet text. Submissions enter a moderation queue accessible at /api/ganjoor/poem/correction/next for editors with the moderator role.
What are the rate limits for the RMuseum API?
The OpenAPI does not declare formal rate-limit headers. Treat HTTP 429 as a back-off signal and avoid tight loops over the 471 endpoints, especially the correction queue and bookmark mutation routes.
How do I read Persian poems through Jentic?
Install with pip install jentic, search 'retrieve a Persian poem', load the schema for the ganjoor_get_poem operation, and execute with a poem id. Jentic handles bearer-token injection if your call hits an authenticated route.
Can I limit what my agent is allowed to do with the RMuseum API?
Yes. Because you run Jentic One yourself, your own rules decide which RMuseum operations and which bearer token your agent may use. Since poem and category ids sit in the URL path (/api/ganjoor/poem/{id}, /api/ganjoor/cat/{id}), you can pin the agent to reading specific poems or categories and nothing more. Write operations such as POST /api/ganjoor/poem/correction stay off limits unless you explicitly allow them.
GET STARTED