API routes

29 routes, read from webapp/serve.py (ROUTES, _CACHEABLE) and tools/gen_openapi.py. Every route is GET, read-only, and also served under /api/v1/… with the same body and strict errors (unknown endpoint → 404; every error is {"error": {"code", "message", "request_id"}}). Cacheable means Cache-Control: public, max-age=300, s-maxage=3600 with an ETag (a matching If-None-Match answers 304); everything else is no-store. The full reference with response schemas is under API reference; this page is the map.

By bounded context

Context	Routes	Tables it opens
insights	/api/analytics/author · /api/analytics/constellation · /api/analytics/pair · /api/analytics/progression · /api/analytics/raag · /api/analytics/resonance · /api/analytics/sky · /api/analytics/theme · /api/analytics/vaar · /api/analytics/vaars · /api/line_concepts · /api/neighbors · /api/related · /api/themes/network	analytics_meta, author_analytics, author_dialogues, author_distinctive_terms, author_facts, author_mentions, author_resonance, authors, concept_lines, concepts, line_neighbors, lines, raag_analytics, raags, shabad_neighbors, theme_fingerprint, theme_network, translations, vaar_units, vaars
knowledge	/api/forms · /api/timing/clock · /api/timing/divergence · /api/timing/raag	raag_timing_claims, raags, shabd_musical_markers, shabd_poetic_genre, shabd_raag_map, shabd_structural_form, timing_sources
reader	/api/ang/{n} · /api/bani/{key} · /api/banis · /api/health · /api/lines · /api/meta · /api/random · /api/shabad/{comp_id}	authors, bani_lines, banis, concept_lines, concepts, extra_lines, fts, lines, meta, raags, sections, timing_sources, translations
search	/api/search · /api/word	canon_tokens, concept_lines, concepts, fts, fts_en, fts_shabad, lines, translations, variants, word_freq
verify	/api/verify	fts, lines

Every route

Route	Context	What it returns	Parameters	Cache
/api/analytics/author	insights	Author stylometry list, or one author’s profile (radar fingerprint + distinctive terms).	author — optional full — optional (one of 1)	cacheable
/api/analytics/constellation	insights	Concept constellation: a theme’s verses, the solo/shared split, every companion theme with its bond, and the Ang strip.	concept — optional author — optional raag — optional raags — optional rahao — optional (one of 1, true) min_themes — optional (0–8; default 0) ang_min — optional (1–1430; default 1) ang_max — optional (1–1430; default 1430)	cacheable
/api/analytics/pair	insights	Verses carrying two themes, grouped by shabad, with the matched words.	concept — required with — optional alone — optional (one of 1, true) offset — optional (0–100000; default 0) limit — optional (1–200; default 50) author — optional raag — optional raags — optional rahao — optional (one of 1, true) min_themes — optional (0–8; default 0) ang_min — optional (1–1430; default 1) ang_max — optional (1–1430; default 1430)	cacheable
/api/analytics/progression	insights	Theme progression through one raag (binned).	raag — required bins — optional (8–80; default 36) top — optional (2–10; default 7)	cacheable
/api/analytics/raag	insights	Raag analytics list, or one raag’s profile.	raag — optional	cacheable
/api/analytics/resonance	insights	Author resonance chord (semantic-neighbour lift between authors).	min_lines — optional (1–…; default 250) min_lift — optional (0–…; default 1.0) min_edges — optional (1–…; default 8)	cacheable
/api/analytics/sky	insights	Every theme with its verse count, and the theme pairs whose PPMI clears min_ppmi.	min_ppmi — optional (0–4; default 0.7)	cacheable
/api/analytics/theme	insights	A theme card: description, Gurmukhi terms, counts, and where it concentrates.	concept — required	cacheable
/api/analytics/vaar	insights	One Vaar’s anatomy (pauris and saloks, attributed).	id — required (0–2147483647)	cacheable
/api/analytics/vaars	insights	The 22 Vaars.	—	cacheable
/api/ang/{n}	reader	Every verbatim line of one Ang, with its raag, section, authors and the composition it continues.	n — path (1–1430)	cacheable
/api/bani/{key}	reader	One bani’s lines (SGGS lines by pointer, cited by Ang; labelled extra layer).	key — path variant — optional	cacheable
/api/banis	reader	The Nitnem / Gutka bani registry.	—	cacheable
/api/forms	knowledge	Structural, poetic and musical form metadata for one composition.	comp_id — required (0–2147483647)	cacheable
/api/health	reader	Integrity self-test: line/Ang counts, FTS, verbatim Mool Mantar, ੴ count, live verify, bani registry.	—	no-store
/api/line_concepts	insights	Concepts carried by each line (Study Trail).	ids — required	cacheable
/api/lines	reader	Verbatim lines by id (used to repair saved Study-Trail pins).	ids — required	cacheable
/api/meta	reader	Build identity and corpus statistics (version, commit, counts).	—	no-store
/api/neighbors	insights	Semantic neighbours of a line (exact sparse cosine; relatedness bands in the UI).	line_id — required (0–2147483647) limit — optional (1–50; default 10)	cacheable
/api/random	reader	A complete structural unit (Hukam) chosen at random.	—	no-store
/api/related	insights	Related compositions (theme-profile cosine).	comp_id — required (0–2147483647)	cacheable
/api/search	search	Search the Granth through the ranked waterfall (exact FTS, seeker lexicon, variants, English, passage, fold).	q — required (≤ 300 chars) mode — optional (one of auto, gurmukhi, roman, english, first, theme; default auto) limit — optional (0–200; default 50) offset — optional (0–1000000; default 0)	no-store
/api/shabad/{comp_id}	reader	Every verbatim line of one composition, heading run included.	comp_id — path (0–2147483647)	cacheable
/api/themes/network	insights	Theme co-occurrence network (PPMI + Jaccard).	concept — optional min_ppmi — optional (0–…; default 0) limit — optional (1–2000; default 200)	cacheable
/api/timing/clock	knowledge	Raag-timing claims on the pahar clock (attributed claims, never facts).	—	cacheable
/api/timing/divergence	knowledge	Raags whose sources disagree on timing (divergence preserved, never adjudicated).	—	cacheable
/api/timing/raag	knowledge	Timing claims for one raag, with sources.	name — required	cacheable
/api/verify	verify	Is this quotation really in the Granth? Returns a verdict, confidence and the matched line.	q — required (≤ 600 chars) ang — optional (1–1430)	no-store
/api/word	search	Occurrences of one Gurmukhi word.	w — required	cacheable

How this page stays true

tools/gen_route_table.py --check runs in the docs job: if a route is added to the dispatcher or to the OpenAPI declarations without regenerating this page, the build fails. The two code tables are held to each other by a unit test, and contract/openapi.json is regenerated from real responses (tools/gen_openapi.py --check in web-ci · python).