# Quickstart

> Make your first call with the public demo key, read the response, then switch to your own test key.

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/kundali` (credits: 1)

**curl**


```bash
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**


```ts
// 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**


```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
<?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;
```


> **Tip: 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](https://navapatra.com/docs/guides/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:

```json
{
  "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](https://navapatra.com/docs/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](https://app.navapatra.com/signup) 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**


```bash
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**


```ts
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**


```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
<?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](https://navapatra.com/docs/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](https://navapatra.com/docs/credits/).

> **Caution: 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](https://navapatra.com/docs/guides/backend-proxy/).

## Next steps

- [Authentication and keys](https://navapatra.com/docs/authentication/): every key type and where it is allowed.
- [Kundali](https://navapatra.com/docs/guides/kundali/): `include`, options, vargas and sensitivity flags.
- [Panchang and calendar](https://navapatra.com/docs/guides/panchang/): daily panchang, choghadiya and BS month grids.
- [Errors](https://navapatra.com/docs/errors/): what each `code` means and how to fix it.