Tirth API · Guide
Get started
The Tirth API lets your platform sell Tirth's pujas, samuhik pujas and yatra packages inside your own product. You pay from prepaid credit at the Tirth Agent net price, Tirth performs the puja or runs the yatra, and your system hears about every stage. This guide goes from a test key to a first booking in the sandbox.
Before you start
- Apply for access. Tirth's partnerships team reviews every application.
- When your application reaches the sandbox stage, you get a test secret key. It starts with
tirth_test_sk_and is shown once: keep it in your secret store, never in code or a repository. - Every example here reads the key from an environment variable,
TIRTH_API_KEY. None of them holds a real key.
Hosts
| Environment | Base URL | Keys it takes |
|---|---|---|
| Sandbox | https://sandbox.api.tirth.com/v2 | tirth_test_sk_… only |
| Live | https://api.tirth.com/v2 | tirth_live_sk_… only |
The sandbox has its own database, fixture products with fake prices, and test credit. Production refuses a test key and the sandbox refuses a live key, each with 401 unauthenticated.
1. Find a product
List pujas with GET /v2/pujas. Each product carries its variants, and a quote names one variant by its id. Samuhik pujas and yatra packages have their own lists, GET /v2/samuhik-pujas and GET /v2/packages.
curl "https://sandbox.api.tirth.com/v2/pujas?limit=5" \
-H "Authorization: Bearer $TIRTH_API_KEY"2. Check the dates
GET /v2/pujas/{id}/availability answers which dates can be booked, each with its tithi where the calendar has that day. A date is available or not, and on_request when Tirth confirms it after you book: the API never says how many seats are left.
curl "https://sandbox.api.tirth.com/v2/pujas/pj_01JE5K7R2M8Q4T6V9X3B0C1D2F/availability?from=2026-12-01&to=2026-12-31" \
-H "Authorization: Bearer $TIRTH_API_KEY"3. Ask for a quote
A quote prices one variant on one date, for a number of people. Packages count adults, child_with_bed, child_without_bed and infant; other products may send people.
curl https://sandbox.api.tirth.com/v2/quotes \
-H "Authorization: Bearer $TIRTH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"variant_id": "var_01JE5K7R2M8Q4T6V9X3B0C1D3G",
"service_date": "2026-12-12",
"travellers": { "people": 2 }
}'The answer is your price, the Tirth Agent net price with GST, held until an IST time 30 minutes on. Amounts are integer paise:
{
"quote_id": "qt_01JE5K9A4C6E8G0J2M4P6R8T0V",
"confirmation": "instant",
"net_total": 459000,
"net_amount": 437143,
"tirth_gst": 21857,
"reference_retail_price": 510000,
"price_locked_until": "2026-12-04T14:35:00+05:30",
"price_locked_until_text": "2:35 PM IST, Fri 4 Dec 2026",
"hold": null,
"decision_within_hours": null,
"lines": []
}The lines are left out above. Quotes and seat holds explains each field.
4. Book it
Book the quote before its lock ends, with your own partner_reference and a new Idempotency-Key. A puja takes the names read in the sankalp; a package takes its travellers, one of them the lead.
curl https://sandbox.api.tirth.com/v2/bookings \
-H "Authorization: Bearer $TIRTH_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"quote_id": "qt_01JE5K9A4C6E8G0J2M4P6R8T0V",
"partner_reference": "ORD-2026-000123",
"sankalp": { "names": [{ "name": "Asha Verma", "gotra": "Kashyap" }] }
}'An instant product is booked at once and its price is taken from your credit: the answer is 201 with the booking, status booked. An on-request product answers requested, and Tirth accepts or declines it within 24 hours for a puja, 48 for a package.
5. Follow it
Every change of status is a webhook to your endpoint and an entry in the change feed. See Bookings and their lifecycle and Webhooks. In the sandbox you move a booking along yourself with POST /v2/sandbox/bookings/{id}/advance: see The sandbox.
The same in Node
Node 20 and later have fetch and crypto.randomUUID() built in. Save this as an ES module (quote.mjs) and run it with node quote.mjs.
const API = 'https://sandbox.api.tirth.com/v2';
const headers = {
Authorization: `Bearer ${process.env.TIRTH_API_KEY}`,
'Content-Type': 'application/json',
};
async function call(method, path, body, idempotencyKey) {
const response = await fetch(`${API}${path}`, {
method,
headers: idempotencyKey ? { ...headers, 'Idempotency-Key': idempotencyKey } : headers,
body: body ? JSON.stringify(body) : undefined,
});
const answer = await response.json();
if (!response.ok) {
const { code, message, request_id } = answer.error;
throw new Error(`${code}: ${message} (request ${request_id})`);
}
return answer;
}
const quote = await call('POST', '/quotes', {
variant_id: 'var_01JE5K7R2M8Q4T6V9X3B0C1D3G',
service_date: '2026-12-12',
travellers: { people: 2 },
});
const booking = await call(
'POST',
'/bookings',
{
quote_id: quote.quote_id,
partner_reference: 'ORD-2026-000123',
sankalp: { names: [{ name: 'Asha Verma', gotra: null }] },
},
crypto.randomUUID(),
);
console.log(booking.id, booking.status);Next
- Authentication: keys, scopes and IP allowlists.
- Errors: what a failed call answers.
- The API reference: every operation.
