# The JSON API

The read-only JSON API over the verbatim corpus: what it promises, its 29 routes in five bounded contexts, the two surfaces (/api and /api/v1), caching, and a console to try any route live.

- Page: <https://docs.gurbanisoul.com/api/>
- Updated: 2026-10-23
- Verified against: `c761e51` on 2026-09-27
- From the Sri Guru Granth Sahib Ji — Knowledge Base wiki. Sri Guru Granth Sahib Ji is quoted verbatim, cited by Ang, and never altered.

---

A read-only JSON API over the verbatim corpus, served by a Python standard-library server
(`webapp/serve.py`) from a database opened read-only and immutable. Every scripture line comes back
exactly as printed with its Ang; English is a separate, labelled layer; nothing is ever written.

- [Quickstart](https://docs.gurbanisoul.com/api/quickstart/) — your first calls in five minutes: an Ang, a search, a verification, a composition, citing, errors and caching
- [Using the API](https://docs.gurbanisoul.com/api/using-the-api/) — what you can rely on, what is not promised, being a good client, and what you owe the text
- [API routes](https://docs.gurbanisoul.com/api/routes/) — every route, its bounded context, parameters and cache policy — **generated from the code**
- [API reference](https://docs.gurbanisoul.com/api/reference/) — the full reference with response schemas, generated from `contract/openapi.json`
- [Contract and OpenAPI](https://docs.gurbanisoul.com/api/contract-and-openapi/) — how the spec and the golden vectors are produced from real responses and enforced
- [Error reference](https://docs.gurbanisoul.com/api/errors/) — every error on both surfaces, and the requests that are clamped instead — **generated by calling the server**
- [Versioning and caching](https://docs.gurbanisoul.com/api/versioning-and-caching/) — `/api` vs `/api/v1`, errors, request ids, caching and ETags, the `X-Service` header
- [API changelog](https://docs.gurbanisoul.com/api/changelog/) — what changed for a client, release by release

## Try any route

On the rendered wiki this is a console: pick a route, fill in its parameters (the form comes from
the OpenAPI spec), send the request to the live API and read the response with its headers, or copy
it as a `curl` command. On GitHub, the routes are listed on [API routes](https://docs.gurbanisoul.com/api/routes/).

## What every response promises

- **Verbatim text.** `gurmukhi` is the line as printed, dandas and markers included; cite it as
  *Sri Guru Granth Sahib Ji · Ang N* (`ang` is on every line).
- **Labelled layers.** `translit` is a reading aid; `en` is Dr. Sant Singh Khalsa's translation
  via ShabadOS, attached to a line and never blended into the Gurmukhi.
- **Read-only, bounded.** Every integer parameter is clamped (`_int()`); `limit` and `offset`
  have ceilings; a claim or a query has a maximum length. There is no write route.
- **The same under `/api/v1`.** Every path is also served under `/api/v1/…` with the same body and
  strict error semantics.
- **Security headers on every response**, a request id you can quote, and a header naming the
  service that answered — see [Versioning and caching](https://docs.gurbanisoul.com/api/versioning-and-caching/).

## Where a route lives

The routes are owned by five [bounded contexts](https://docs.gurbanisoul.com/architecture/bounded-contexts-and-gateway/)
— `reader`, `search`, `verify`, `insights`, `knowledge` — each of which opens only the tables it
needs. On staging each context runs as its own function behind the gateway; production (v1.3.10
and 1.4.0) serves them all from one function, `all`, until a later release, after the app is live. A
client never sees the difference except in `X-Service`.