CanonRAG · Dharma Access

API Reference

CanonRAG API

CanonRAG is a retrieval API for the Buddhist canon — Pali, Chinese, Sanskrit, and Tibetan. It exposes hybrid vector + full-text search across 59,000+ indexed passages with Buddhist entity normalisation, so queries in any language or script resolve to the same concepts.

All endpoints return JSON. The /v1/ask endpoint uses Claude to synthesise retrieved passages into a grounded answer with citations.

Base URL

https://api.canonrag.dharmaaccess.org

Authentication

Pass your API key in the X-API-Key header. Keys can be obtained from the API key page. Unauthenticated requests are accepted but subject to stricter rate limits and produce no usage logs.

bash

curl -X POST https://api.canonrag.dharmaaccess.org/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: crag_your_key_here" \
  -d '{"query": "cessation of suffering"}'

Keys are SHA-256 hashed on our end. The raw key is shown once at creation and cannot be retrieved. If you lose your key, generate a new one — old keys remain active until you contact us to deactivate them.

POST /v1/search

Hybrid passage retrieval. Runs vector similarity (Voyage multilingual-2 embeddings) and full-text search in parallel across all three database accounts, fuses results with Reciprocal Rank Fusion (0.7 vector / 0.3 keyword), and applies a +0.25 score boost for passages containing entities resolved from the query.

Request body

querystringrequired

The search query. Any language or script — entity names in Pali, Sanskrit, Chinese, or Tibetan are normalised to the same concept (e.g. nibbāna, nirvāṇa, 涅槃, myang 'das all resolve identically).

traditionsstring[]optional · default all

Filter by tradition. Valid values: theravada, mahayana, vajrayana, sanskrit. Omit to search all traditions.

languagesstring[]optional · default all

Filter by language (ISO 639-3). Valid values: en, pli, lzh, san, bo.

collectionsstring[]optional · default all

Filter by collection (e.g. mn, dn, sn, an, agama, vinaya).

top_kintegeroptional · default 8

Number of passages to return. Maximum 20.

bash

curl -X POST https://api.canonrag.dharmaaccess.org/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: crag_your_key_here" \
  -d '{
    "query": "mindfulness of breathing",
    "traditions": ["theravada"],
    "top_k": 5
  }'

Response

json

{
  "query": "mindfulness of breathing",
  "resolved_entities": [
    {
      "id": 12,
      "english": "mindfulness",
      "pali": "sati",
      "sanskrit": "smṛti",
      "chinese": "念",
      "tibetan": "dran pa",
      "type": "concept"
    }
  ],
  "passages": [
    {
      "chunk_id": 4821,
      "text": "Breathing in long, he knows: 'I breathe in long'...",
      "reference": "MN 118:17.1–17.4",
      "sutta_id": "mn118",
      "title_english": "Mindfulness of Breathing",
      "title_pali": "Ānāpānasati Sutta",
      "tradition": "theravada",
      "language": "en",
      "collection": "mn",
      "translator": "Bhikkhu Sujato",
      "corpus": "suttacentral",
      "url": "https://suttacentral.net/mn118/en/sujato",
      "score": 0.847
    }
  ],
  "search_accounts": 3,
  "latency_ms": 312
}

Ask the Canon (Playground only)

Ask the Canon is available exclusively through the CanonRAG Playground. It is not exposed as a callable API endpoint. It uses Claude to synthesise retrieved passages into a grounded answer with citations — every claim is attributed to a specific passage; the model does not draw on training knowledge.

To build Q&A features in your own application, call /v1/search to retrieve passages, then pass them to your own LLM with a system prompt requiring citation. This gives you full control over model choice, cost, and output format.

GET /v1/text/{uid}

Retrieve the full chunked text of a canonical work by its external identifier. For SuttaCentral texts, use the sutta UID (e.g. mn1, dn15). For CBETA texts, use the T-number (e.g. T0001).

Parameters

uidstring (path)required

The external identifier of the text.

langstring (query)optional · default en

Language of the text to retrieve (ISO 639-3). A single text may have entries in multiple languages.

bash

# Retrieve Mindfulness of Breathing sutta
curl "https://api.canonrag.dharmaaccess.org/v1/text/mn118?lang=en" \
  -H "X-API-Key: crag_your_key_here"

Response

json

{
  "uid": "mn118",
  "title_english": "Mindfulness of Breathing",
  "title_pali": "Ānāpānasati Sutta",
  "tradition": "theravada",
  "language": "en",
  "collection": "mn",
  "translator": "Bhikkhu Sujato",
  "url": "https://suttacentral.net/mn118/en/sujato",
  "corpus": "suttacentral",
  "chunks": [
    {
      "chunk_index": 0,
      "chunk_text": "So I have heard...",
      "reference": "MN 118:1.1",
      "chapter": null,
      "section": null
    }
  ]
}

GET /v1/entity/{id}

Retrieve an entity from the Buddhist entity normalisation layer. Entities are seeded with cross-tradition equivalences — a single entity record links nibbāna, nirvāṇa, 涅槃, and myang 'das. Entity IDs are returned in /v1/search responses under resolved_entities.

bash

curl "https://api.canonrag.dharmaaccess.org/v1/entity/1" \
  -H "X-API-Key: crag_your_key_here"

Response

json

{
  "id": 1,
  "entity_type": "concept",
  "pali": "nibbāna",
  "sanskrit": "nirvāṇa",
  "classical_chinese": "涅槃",
  "tibetan": "myang 'das",
  "english_preferred": "nirvana",
  "english_alternates": ["liberation", "cessation", "extinguishment"],
  "traditions": ["theravada", "mahayana", "vajrayana"],
  "description": "The unconditioned cessation of craving and the end of the cycle of rebirth.",
  "name_variants": [
    { "name_text": "nibbāna",  "language": "pli", "script": "Latin",    "is_primary": true },
    { "name_text": "nirvāṇa", "language": "san", "script": "Latin",    "is_primary": true },
    { "name_text": "涅槃",    "language": "lzh", "script": "Chinese",  "is_primary": true },
    { "name_text": "myang 'das", "language": "bo", "script": "Latin",  "is_primary": true }
  ]
}

Traditions & languages

traditions

theravadaTheravāda · Pali Tipiṭaka — SuttaCentral

mahayanaMahāyāna · Chinese canon — CBETA Taishō

vajrayanaVajrayāna · Tibetan — 84000 translations

sanskritSanskrit · IAST texts — GRETIL

languages (ISO 639-3)

enEnglish

pliPali

lzhClassical Chinese

sanSanskrit (IAST)

boTibetan

Rate limits

Tier	Daily limit	Per-minute cap	Cost
Anonymous	No daily limit	60/min	Free
Free ← current	100 / day	60/min	Free
Developer	2,000 / day	—	Coming soon
Production	Unlimited	—	Coming soon

Daily limits reset at midnight UTC. Exceeding a limit returns HTTP 429.

Error codes

Status	Meaning
400	Bad request — missing or invalid parameter (e.g. empty query)
401	Invalid or inactive API key
404	Text or entity not found
422	Request body failed validation (malformed JSON or wrong types)
429	Rate limit exceeded — daily limit or per-minute cap hit
500	Internal server error
504	Upstream timeout — LLM generation exceeded 55 s

All error responses follow the shape:

json

{ "detail": "Error description here." }

Data coverage

Corpus	Tradition	Texts	Chunks	License
SuttaCentral (bilara-data)	Theravāda · Pali	MN, DN, SN, AN + partial	~6,400	CC0 / CC BY
CBETA Taishō	Mahāyāna · Classical Chinese	T0001–T0278	~15,980	CC BY-NC
GRETIL	Sanskrit	227 Buddhist texts (IAST)	~14,680	Open
84000 (Kangyur & Tengyur)	Vajrayāna · English translations	385 texts	~22,280	CC BY-NC

Embeddings: Voyage AI multilingual-2 (1024-dim, multilingual). Storage: PostgreSQL + pgvector across three regional Supabase instances (Tokyo, Singapore, Seoul), queried in parallel and fused at the API layer. Full canon migration to a single server is planned when the first paid tier launches.

CanonRAG v1.0.0 · Dharma AccessGet API Key →