# API routes Every /api route the platform serves, generated from the dispatcher and the OpenAPI declarations: its bounded context, parameters, cache policy and /api/v1 twin. - Page: - Updated: 2026-10-24 - From the Sri Guru Granth Sahib Ji — Knowledge Base wiki. Sri Guru Granth Sahib Ji is quoted verbatim, cited by Ang, and never altered. --- 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](https://docs.gurbanisoul.com/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`).