Quickstart

Every call is an HTTPS request to https://api.navapatra.com/v1 with a key in the Authorization header. You can make a real one right now, before you sign up, with the public key demo.

1. Make a call with the demo key

The demo key accepts five bundled sample births (listed below) and allows 10 requests per minute per IP address. It is not tied to any account and never uses credits. This request computes the kundali of the Pokhara sample, born on Bhadra 12, BS 2050 at 14:35 local time.

POST/v1/kundali1 creditReference

curl

curl https://api.navapatra.com/v1/kundali \
  -H "Authorization: Bearer demo" \
  -H "Content-Type: application/json" \
  -d '{
    "birth": {
      "calendar": "BS",
      "date": "2050-05-12",
      "time": "14:35",
      "place": { "lat": 28.2096, "lng": 83.9856 }
    }
  }'

TypeScript

// quickstart.ts (Node 18+, Deno or Bun; fetch is built in)
const res = await fetch('https://api.navapatra.com/v1/kundali', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer demo',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    birth: {
      calendar: 'BS',
      date: '2050-05-12',
      time: '14:35',
      place: { lat: 28.2096, lng: 83.9856 },
    },
  }),
});

if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).detail}`);
const kundali = await res.json();
console.log(kundali.lagna.sign.name, kundali.moon.nakshatra.name);

Python

# quickstart.py (pip install requests)
import requests

res = requests.post(
    "https://api.navapatra.com/v1/kundali",
    headers={"Authorization": "Bearer demo"},
    json={
        "birth": {
            "calendar": "BS",
            "date": "2050-05-12",
            "time": "14:35",
            "place": {"lat": 28.2096, "lng": 83.9856},
        }
    },
)
res.raise_for_status()
kundali = res.json()
print(kundali["lagna"]["sign"]["name"], kundali["moon"]["nakshatra"]["name"])

PHP

<?php
// quickstart.php (composer require guzzlehttp/guzzle)
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->post('https://api.navapatra.com/v1/kundali', [
    'headers' => ['Authorization' => 'Bearer demo'],
    'json' => [
        'birth' => [
            'calendar' => 'BS',
            'date' => '2050-05-12',
            'time' => '14:35',
            'place' => ['lat' => 28.2096, 'lng' => 83.9856],
        ],
    ],
]);

$kundali = json_decode((string) $res->getBody(), true);
echo $kundali['lagna']['sign']['name'], ' ', $kundali['moon']['nakshatra']['name'], PHP_EOL;

Prefer a typed client?

@navapatra/sdk wraps every endpoint with generated types, retries and metering headers, installed with npm install @navapatra/sdk once it is published to npm. See the TypeScript SDK guide. In Python and PHP, the plain HTTP examples above are all you need.

2. Read the response

The call prints Dhanu Uttara Ashadha: the lagna (ascendant) is in Dhanu and the Moon is in the Uttara Ashadha nakshatra. Here is the shape of the full response, shortened:

{
  "subject": {
    "instantUtc": "1993-08-28T08:50:00Z",
    "place": { "lat": 28.2096, "lng": 83.9856 },
    "tzid": "Asia/Kathmandu",
    "utcOffset": "+05:45",
    "offsetSource": "tzdb",
    "birth": { "ad": "1993-08-28", "bs": "2050-05-12" }
  },
  "lagna": {
    "sign": { "index": 9, "name": "Dhanu" },
    "longitude": 245.8854,
    "nakshatra": { "index": 19, "name": "Mula" },
    "pada": 2
  },
  "grahas": [
    {
      "id": "sun",
      "name": "Sun",
      "sign": { "index": 5, "name": "Simha" },
      "longitude": 131.2923,
      "speed": 0.9658,
      "house": 9,
      "retrograde": false,
      "nakshatra": { "index": 10, "name": "Magha" },
      "pada": 4
    }
  ],
  "vargas": { "D1": { "...": "..." }, "D9": { "...": "..." } },
  "moon": {
    "rashi": { "index": 9, "name": "Dhanu" },
    "nakshatra": { "index": 21, "name": "Uttara Ashadha" },
    "pada": 1,
    "syllable": { "index": 81, "en": "Bhe", "ne": "भे", "hi": "भे" }
  },
  "dashas": { "vimshottari": { "...": "..." } },
  "meta": {
    "engineVersion": "0.1.0",
    "apiVersion": "2026-11-01",
    "ayanamsha": { "id": "lahiri", "degrees": 23.773159 },
    "nodeType": "mean",
    "tradition": "nepal",
    "sunriseConvention": "upper_limb_refracted",
    "tzdbVersion": "unknown",
    "deltaTModelVersion": "iers-c01-2026.5+quad2100-v1",
    "bsTableVersion": "2026.10.1",
    "overridesVersion": null
  }
}

A few things hold for every endpoint:

• subject shows how the birth was read: the UTC instant, the time zone and offset applied, where the offset came from (tzdb or override) and the date in both AD and BS. Check it first when a chart looks wrong.
• Catalog values come back as { index, name }. The index is stable and 1-based (weekday 0 is Sunday); the name follows lang (en, ne or hi). Store the index, show the name.
• meta names everything needed to reproduce the result: engine version, API version, ayanamsha and its value, node type and the data versions. See Conventions.
• Headers: every response carries x-request-id, x-credits-charged and, for keys tied to an account, x-credits-remaining.

To get Nepali labels with Devanagari digits, add "lang": "ne" to the body. Numerals follow the language unless you set "numerals": "latin" or "numerals": "devanagari".

3. The sample subjects

The demo key only accepts these births, given exactly as below (the place may be coordinates or a place name that resolves within about 5 km). GET /v1/meta returns the same list. Daily panchang, month grids and time zone lookups with the demo key accept the same five places.

Sample	Calendar	Date	Time	Latitude, longitude
Pokhara	BS	2050-05-12	14:35	28.2096, 83.9856
Kathmandu	AD	1990-05-15	10:30	27.7172, 85.324
Biratnagar	AD	2001-01-26	21:05	26.4525, 87.2718
New Delhi	AD	1985-11-02	06:15	28.6139, 77.209
Varanasi	AD	1975-03-08	04:40	25.3176, 82.9739

Any other birth returns 403 with code: "demo_restricted". Batch matching, panchang ranges, /v1/tokens and /v1/usage need a real key.

4. Switch to your own key

Sign up and the dashboard shows a test key that starts with sk_test_. Test keys return exactly what live keys return, never use credits, and are limited to a daily quota of 100 (counted in credits) and 10 requests per minute for your organization. Keep the key in an environment variable and send it the same way:

curl

export NAVAPATRA_API_KEY="sk_test_..."

curl "https://api.navapatra.com/v1/calendar/convert?date=2083-01-01&calendar=BS" \
  -H "Authorization: Bearer $NAVAPATRA_API_KEY" \
  -H "Navapatra-Version: 2026-11-01"

TypeScript

const res = await fetch('https://api.navapatra.com/v1/calendar/convert?date=2083-01-01&calendar=BS', {
  headers: {
    Authorization: `Bearer ${process.env.NAVAPATRA_API_KEY}`,
    'Navapatra-Version': '2026-11-01',
  },
});
const { ad, bs } = await res.json();
console.log(bs.text, '=', ad.date); // 1 Baishakh 2083 = 2026-04-14

Python

import os
import requests

res = requests.get(
    "https://api.navapatra.com/v1/calendar/convert",
    params={"date": "2083-01-01", "calendar": "BS"},
    headers={
        "Authorization": f"Bearer {os.environ['NAVAPATRA_API_KEY']}",
        "Navapatra-Version": "2026-11-01",
    },
)
data = res.json()
print(data["bs"]["text"], "=", data["ad"]["date"])  # 1 Baishakh 2083 = 2026-04-14

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();
$res = $client->get('https://api.navapatra.com/v1/calendar/convert', [
    'query' => ['date' => '2083-01-01', 'calendar' => 'BS'],
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('NAVAPATRA_API_KEY'),
        'Navapatra-Version' => '2026-11-01',
    ],
]);

$data = json_decode((string) $res->getBody(), true);
echo $data['bs']['text'], ' = ', $data['ad']['date'], PHP_EOL; // 1 Baishakh 2083 = 2026-04-14

The Navapatra-Version header is optional: without it you get the version your key is pinned to. Sending it makes the version explicit in your code. See Versioning.

When you go live, swap in an sk_live_ key. Live calls use credits from your organization’s balance, which includes 2,000 free credits every month. See Credits and metering.

Secret keys stay on servers

sk_ keys must never ship in a browser, mobile app or public repository. Calls from a browser with an sk_ key are refused with secret_key_in_browser. For apps, read Mobile apps.

Next steps

• Authentication and keys: every key type and where it is allowed.
• Kundali: include, options, vargas and sensitivity flags.
• Panchang and calendar: daily panchang, choghadiya and BS month grids.
• Errors: what each code means and how to fix it.