The JSON API

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.

• Quickstartyour first calls in five minutes: an Ang, a search, a verification, a composition, citing, errors and caching
• Using the APIwhat you can rely on, what is not promised, being a good client, and what you owe the text
• API routesevery route, its bounded context, parameters and cache policy — generated from the code
• API referencethe full reference with response schemas, generated from contract/openapi.json
• Contract and OpenAPIhow the spec and the golden vectors are produced from real responses and enforced
• Error referenceevery error on both surfaces, and the requests that are clamped instead — generated by calling the server
• Versioning and caching/api vs /api/v1, errors, request ids, caching and ETags, the X-Service header
• API changelogwhat 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.

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.

Where a route lives

The routes are owned by five bounded contexts — 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.