Quick start
Ask for today's Hukamnama. There is nothing to sign up for, and any website or app may call it, from a server or straight from a browser.
curl https://api.gurbanisoul.com/v1/hukamnama/today “Today” is the date in Amritsar (UTC+05:30), wherever the request comes from. The Hukamnama usually appears after about 05:30 in the morning there. Until then the answer says "status": "pending" and names the latest published date in latest.
Endpoints
https://api.gurbanisoul.com
GET /v1/hukamnama/today- The Hukamnama for the current date in Amritsar, or a pending answer before it is published.
GET /v1/hukamnama/YYYY-MM-DD- One day, by its Amritsar date. The archive begins on
2026-11-01. GET /v1/hukamnama?limit=7- The latest published days, newest first: from 1 to 30 of them, 7 when
limitis left out. Addinclude=linesto get every line of each day. GET /v1/hukamnama/index- Every published day, newest first, with its date, Ang and hash and without the text. For an archive or a sitemap.
GET /v1/status- Whether today's Hukamnama is published yet, and the latest published date.
The response
A published day carries the whole shabad, line by line. This is the record for 2026-11-11; here the text is replaced by “…” and only the first two of its 7 lines are shown.
{
"amritsar_date": "2026-11-11",
"status": "published",
"ang": 680,
"first_line_id": 29497,
"last_line_id": 29503,
"comp_id": 2699,
"opening_line_id": 29498,
"opening_gurmukhi": "…",
"opening_translit": "…",
"line_count": 7,
"range_sha256": "61975a8dea4d5174e173a5c6d1f3b761653f19ba7029b4386d03a475ed7689f4",
"scripture_sha256": "0eff4bae60cfcf1c63ae4ac14c2ecf255a9457edc0bebaf627aa28dedb89c84f",
"citation": "Sri Guru Granth Sahib Ji · Ang 680",
"published_at": "2026-11-11T00:25:03+00:00",
"credit": "Located by Ang from the Hukamnama published by SGPC (hs.sgpc.net); text from Sri Guru Granth Sahib Ji.",
"ang_end": 680,
"raag": "ਧਨਾਸਰੀ",
"author": "Guru Arjan Dev Ji (M5)",
"url": "https://gurbanisoul.com/en/hukamnama/2026-11-11",
"attribution": {
"text": "Hukamnama · Sri Harmandir Sahib, via Gurbani Soul",
"url": "https://gurbanisoul.com/en/hukamnama/2026-11-11"
},
"terms_url": "https://gurbanisoul.com/en/developers#terms",
"lines": [
{
"id": 29497,
"ang": 680,
"gurmukhi": "…",
"translit": "…",
"is_heading": true,
"is_rahao": false,
"author": "Guru Arjan Dev Ji (M5)"
},
{
"id": 29498,
"ang": 680,
"gurmukhi": "…",
"translit": "…",
"is_heading": false,
"is_rahao": false,
"author": "Guru Arjan Dev Ji (M5)"
}
]
} amritsar_date- The day this Hukamnama belongs to, in Amritsar. Show this date, not your visitor's.
statuspublishedorpending. A pending answer has no lines.ang,ang_end- The Ang the shabad opens on and the Ang it ends on.
citation- The citation to show with the text.
lines- Every line, in order.
gurmukhiis the line, verbatim.translitis a rule-based transliteration.is_headingmarks a heading andis_rahaothe Rahao line. author,raag- The author and the raag. When a day's lines are by more than one author, as in a Vaar, the day's
authorisnulland each line carries its own. range_sha256,scripture_sha256range_sha256proves the lines, as shown below.scripture_sha256names the edition of the text they were read from.published_at- When the day was published here, in UTC.
lines[].en,translation- An English translation by Dr. Sant Singh Khalsa, where it is included. It is a separate, labelled layer: never present it as the Gurbani.
Check the text yourself
Join the gurmukhi of every line with a newline, take the SHA-256 of the UTF-8 bytes, and compare it with range_sha256. If they differ, show nothing: late is better than wrong.
const res = await fetch("https://api.gurbanisoul.com/v1/hukamnama/today");
const day = await res.json();
if (day.status === "published") {
const text = day.lines.map((line) => line.gurmukhi).join("\n");
const bytes = new TextEncoder().encode(text);
const digest = await crypto.subtle.digest("SHA-256", bytes);
const hex = [...new Uint8Array(digest)]
.map((b) => b.toString(16).padStart(2, "0"))
.join("");
if (hex !== day.range_sha256) throw new Error("lines do not match range_sha256");
} Before a day is published here, its lines are read from the same text as the Knowledge Base and proved against this hash. SGPC's page is used only to find the shabad; no character is taken from it.
If a line ever looks wrong, tell us.
Showing the Hukamnama
- Show the Gurmukhi exactly as it arrives. Do not correct, shorten, re-space or reorder it.
- Show the whole shabad. Where there is no room for it, link to the day's page (
url) instead of cutting it. - Name it “Hukamnama · Sri Harmandir Sahib”, give its Amritsar date, and show the citation.
- Call it “today's” only while its date is still the date in Amritsar.
- Keep the transliteration and any translation apart from the Gurmukhi, each under its own label.
- Do not call it official. SGPC publishes the Hukamnama; this API finds the shabad by Ang and serves its text from Sri Guru Granth Sahib Ji.
Credit
Wherever you show the Hukamnama, credit it with a link to the day's page:
<a href="https://gurbanisoul.com/en/hukamnama/2026-11-11">Hukamnama · Sri Harmandir Sahib, via Gurbani Soul</a> Each record carries these words and the link in attribution. Gurbani Soul is not affiliated with SGPC.
Embed it without code
For a Gurdwara's website or a blog: paste this where the Hukamnama should appear. It runs no script and sets no cookie.
<iframe src="https://gurbanisoul.com/embed/hukamnama?lang=en&theme=auto"
title="Hukamnama · Sri Harmandir Sahib" loading="lazy"
style="width:100%;max-width:640px;height:520px;border:0"></iframe> lang can be en, pa, fr, and theme can be auto, light, dark.
Feeds
The same days as feeds, for feed readers and automations:
https://gurbanisoul.com/feeds/hukamnama.xmlhttps://gurbanisoul.com/feeds/hukamnama.json
Reliability and limits
- The API is run with care but without a guarantee. When a day cannot be proved it is held back: late rather than wrong.
- Answers are cached, today's for about a minute and past days for a day. Send
If-None-Matchwith theETagyou hold and an unchanged answer costs nothing. - Once a minute is as often as anyone needs to ask. Too many requests are answered with
429and aRetry-Afterheader. - Errors are JSON with
error,codeandrequest_id. - Version 1 only grows. Fields may be added; none is renamed or removed without twelve months' notice.
Terms
- The API is free to use. There is no key, no account and no charge.
- Credit the Hukamnama as shown above, with the link.
- Do not alter the Gurmukhi, and do not present it as official or as coming from SGPC.
- The API is provided as it is, without warranty. Use that harms the service may be limited or blocked.
Questions, or building something for a Gurdwara? Write to support@gurbanisoul.com.