SourceTruth API

Semantic search and AI-powered Q&A over 30 pre-indexed canonical corpora — Quran, Bible, Plato, Confucius, and more. No ingestion pipeline. One API key.

Base URL: https://api.sourcetruth.io · Version: 1.0.0

New here? Jump to Quick start to make your first call in under two minutes, or issue a free key now.

Quick start

1. Get a free API key

curl

curl -X POST https://api.sourcetruth.io/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "email": "you@example.com"}'

# → {"key": "st_a1b2c3...", "tier": "free", "daily_limit": 100}

Store the key — it is shown only once.

2. Search a corpus

Python

import requests

r = requests.post(
    "https://api.sourcetruth.io/v1/search",
    headers={"X-API-Key": "st_..."},
    json={
        "query": "What does the Quran say about patience?",
        "corpus_codes": ["quran", "sahih-bukhari"],
        "top_k": 5,
    },
)
for p in r.json()["passages"]:
    print(p["reference"], p["text"][:100])

3. Get a grounded answer (paid tiers)

Python

r = requests.post(
    "https://api.sourcetruth.io/v1/answer",
    headers={"X-API-Key": "st_..."},
    json={
        "question": "What does the Quran say about patience?",
        "corpus_codes": ["quran", "sahih-bukhari"],
    },
)
print(r.json()["answer"])   # grounded prose with numbered citations
print(r.json()["citations"]) # [{"index":1,"reference":"2:153","corpus":"quran",...}]

Authentication

Pass your API key in the X-API-Key request header. Keys are prefixed st_.

Header

X-API-Key: st_a1b2c3d4e5f6...

/v1/search and /v1/corpora accept anonymous requests (rate-limited). /v1/answer requires a paid key.

POST /v1/search

Hybrid semantic + keyword retrieval over indexed corpora. Returns ranked passages with citation metadata. Available to all tiers including free.

Request body

Field	Type	Description
query required	string	Natural language query in any supported language.
corpus_codes optional	string[]	Scope to specific corpora — e.g. `["quran","sahih-bukhari"]`. Takes priority over `traditions` for reranking. See corpus codes.
traditions optional	string[]	Filter by tradition — e.g. `["islam"]`, `["judaism"]`.
languages optional	string[]	Filter by ISO language code — e.g. `["en"]`, `["ara"]`.
collections optional	string[]	Filter by collection within a corpus — e.g. `["hadith"]` to scope within a multi-collection corpus.
top_k optional	integer	Passages to return. Default `8`, max `20`.

Cross-corpus tip: For balanced results across two corpora (e.g. Quran + Hadith, Tanakh + Mishnah), make two scoped calls and merge. A single unscoped call may be dominated by whichever corpus has stronger semantic overlap.

Response

JSON

{
  "query": "What does the Quran say about patience?",
  "passages": [{
    "chunk_id": 18432,
    "text": "O you who have believed, seek help through...",
    "reference": "2:153",
    "tradition": "islam",
    "language": "en",
    "corpus": "quran",
    "score": 0.912
  }],
  "resolved_entities": [],
  "latency_ms": 84
}

POST /v1/answer

Retrieval-augmented generation. Retrieves relevant passages then generates a grounded answer via Claude with numbered inline citations. Requires Starter or Professional.

Request body

Field	Type	Description
question required	string	The question to answer from the corpus.
corpus_codes optional	string[]	Scope retrieval to specific corpora.
traditions optional	string[]	Filter retrieval by tradition.
languages optional	string[]	Filter retrieval by language.
max_passages optional	integer	Passages to retrieve as context. Default `6`, max `10`.

Response

JSON

{
  "question": "What does the Quran say about patience?",
  "answer": "The Quran emphasises patience (sabr) repeatedly.
In 2:153 believers are instructed to seek help
through patience and prayer [1]...

Citations:
[1] 2:153 — Surah Al-Baqarah",
  "citations": [{ "index": 1, "reference": "2:153", "corpus": "quran" }],
  "latency_ms": 1840
}

The answer model is instructed never to invent references from memory. If the retrieved passages don't support an answer, it says so explicitly rather than hallucinating citations.

GET /v1/corpora

Returns all indexed corpora with codes, traditions, languages, and licence metadata. No authentication required. Use returned code values as corpus_codes filter values.

curl

curl https://api.sourcetruth.io/v1/corpora

GET /v1/text/{uid}

Returns the full chunked text of a document by its canonical UID. UID format is corpus-specific — pass the value of chunk_id from a search result, or use corpus reference notation (e.g. 2:153 for Quran, gen-1 for Genesis KJV).

Param	In	Description
uid required	path	Canonical document ID.
lang optional	query	Language code. Default `en`.

GET /v1/entity/{entity_id}

Returns entity metadata and name variants (Sanskrit, Chinese, Tibetan, English). Entity IDs appear in the resolved_entities array of search results when named entities are detected in the query.

POST /v1/keys

Self-issue a free-tier API key. No authentication required. Rate-limited to 5 per hour per IP.

Field	Type	Description
name required	string	Your name or application name.
email required	string	Valid email address.

JSON response

{ "key": "st_a1b2c3...", "tier": "free", "daily_limit": 100,
  "message": "Store this key safely — it will not be shown again." }

DELETE /v1/keys

Immediately revoke your API key. Pass the key in X-API-Key. Irreversible.

GET /health

Health check. No authentication required.

JSON

{ "status": "ok", "version": "1.0.0" }

Corpus codes

Pass these values in corpus_codes to scope any request. Live list always available at GET /v1/corpora.

Code	Name	Tradition	Lang	Licence
quran	Tanzil Quran Corpus	Islam	ara	CC BY 3.0 ‡
sahih-bukhari	Sahih al-Bukhari	Islam	en	Unlicense
sahih-muslim	Sahih Muslim	Islam	en	Unlicense
sunan-abu-dawood	Sunan Abu Dawood	Islam	en	Unlicense
rumi-masnavi	Masnavi (Nicholson)	Islam	en	Public Domain
cbeta	CBETA Chinese Canon	Mahayana	lzh	CC BY-NC †
84000	84000 Translations	Vajrayana	en	CC BY-NC †
tibetan-buddhist	Evans-Wentz Tibetan	Vajrayana	en	Public Domain
bdrc	Buddhist Digital Resource Center	Vajrayana	bo	Open (varies)
kjv	King James Bible	Christianity	en	Public Domain
bible-web	World English Bible	Christianity	en	CC0
bible-asv	American Standard Version	Christianity	en	Public Domain
bible-ylt	Young's Literal Translation	Christianity	en	Public Domain
christian-theology	Patristics (Augustine, Apostolic Fathers)	Christianity	en	Public Domain
tanakh-jps1917	Tanakh (JPS 1917)	Judaism	en	Public Domain
mishnah-silverstein	Mishnah (Silverstein)	Judaism	en	CC BY ‡
bhagavad-gita	Bhagavad Gita (Arnold)	Hinduism	en	Public Domain
upanishads	Principal Upanishads (Müller)	Hinduism	en	Public Domain
yoga-sutras	Yoga Sutras (Johnston)	Hinduism	en	Public Domain
mahabharata	Mahabharata (Ganguli)	Hinduism	en	Public Domain
rigveda	Rigveda (Griffith)	Hinduism	en	Public Domain
sanskrit-classical	Ramayana + Kalidasa	Hinduism	en	Public Domain
sggs	Sri Guru Granth Sahib Ji	Sikhism	pa	Public Domain
classical-chinese	Analects, Tao Te Ching, Art of War	East Asian	en	Public Domain
greek-philosophy	Plato, Aristotle, Stoics	Hellenism	en	Public Domain
classical-latin	Caesar, Virgil, Cicero, Seneca	Classicism	en	Public Domain
political-philosophy	Hobbes, Locke, Rousseau, Mill	Western Phil.	en	Public Domain
western-philosophy	Descartes to Nietzsche	Western Phil.	en	Public Domain
avesta	Zend-Avesta (Darmesteter/Mills)	Zoroastrianism	en	Public Domain
gretil	GRETIL Sanskrit *	Sanskrit	san	Open (varies)

‡ Attribution required. † Non-commercial only. * Always pass corpus_codes: ["gretil"] — excluded from unscoped searches.

Rate limits & tiers

Tier	/search /day	/answer /day	Price
Free	100	—	$0
Starter	1,000	100	$29/mo
Professional	10,000	300	$149/mo

Hard per-minute limits: 60 req/min on /v1/search, 20 req/min on /v1/answer. Exceeded limits return HTTP 429. Upgrade at sourcetruth.io/pricing.

Error codes

Status	Meaning
400	Invalid request — check required fields.
401	Missing or invalid API key.
403	Endpoint requires a paid plan.
404	Resource not found.
429	Daily quota or per-minute rate limit exceeded.
503	Billing not configured.

All errors: {"detail": "..."}

Python

import requests
API_KEY = "st_..."

r = requests.post("https://api.sourcetruth.io/v1/search",
    headers={"X-API-Key": API_KEY},
    json={"query": "nature of suffering", "top_k": 5})
for p in r.json()["passages"]:
    print(p["reference"], p["text"][:120])

JavaScript

const res = await fetch("https://api.sourcetruth.io/v1/search", {
  method: "POST",
  headers: { "X-API-Key": "st_...", "Content-Type": "application/json" },
  body: JSON.stringify({ query: "nature of suffering", top_k: 5 }),
});
const { passages } = await res.json();
passages.forEach(p => console.log(p.reference, p.text.slice(0, 120)));