# Navapatra API reference > OpenAPI 3.1.0, API version 2026-11-01. Base URL: https://api.navapatra.com/v1. Spec: https://navapatra.com/docs/openapi.json Kundali, panchang, matching and Nepali (Bikram Sambat) calendar API for apps in Nepal and India. **Auth.** `Authorization: Bearer `. Secret keys (`sk_live_`, `sk_test_`) are server-only; browsers use a publishable key (`pk_`, origin allowlist) or a short-lived client token from `POST /v1/tokens`. The public key `demo` accepts the five sample subjects listed in `GET /v1/meta` (10 requests per minute per IP). **Versioning.** `Navapatra-Version: YYYY-MM-DD`, pinned per key. Data updates (tzdb, BS table, overrides) are not pinned; `meta` echoes each data version. **Requests.** POST bodies carry `birth`, `options`, `include`, `lang` (`en`, `ne`, `hi`) and `numerals` (`latin`, `devanagari`). Every catalog value comes back as `{ index, name }` with `name` in the requested language. No credit surcharge for any language. **Credits.** Only 2xx responses consume credits. Every response carries `x-request-id`, `x-credits-charged` and `x-credits-remaining`; rate limits use `RateLimit-*` headers and `429` comes with `Retry-After`. **Errors.** RFC 9457 `application/problem+json` with a stable `code`. **Privacy.** Stateless: request and response bodies are never logged or stored. ## Kundali Charts, positions and dasha timelines. ### POST /v1/kundali **Full kundali** (`createKundali`) D1 and D9 for the lagna and nine grahas, Moon nakshatra, pada and naming syllable, the Vimshottari timeline (2 levels by default) and `meta`. `include` adds `vargas` (all 16), `dashas.yogini`, `dashas.tribhagi`, `panchang` and `svg` (North; `svg.south` adds South). `options.sensitivityMinutes` adds `sensitivity`. Deterministic: the same request and `meta` versions give byte-identical JSON. 1 credit. Auth: `Authorization: Bearer `. Request body (`KundaliRequest`): - `birth`, BirthInput, required: Birth date, local time and place. Supported range AD 1900-01-01 to 2100-12-31. - `options`, KundaliOptions, optional - `include`, "vargas" | "dashas.yogini" | "dashas.tribhagi" | "panchang" | "svg" | "svg.south"[], optional - `lang`, "en" | "ne" | "hi", optional: Language of every `name` label. No credit surcharge for any language. - `numerals`, "latin" | "devanagari", optional: Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`. ```json { "birth": { "calendar": "BS", "date": "2050-05-12", "time": "14:35:00", "place": { "lat": 28.2096, "lng": 83.9856 } }, "options": { "ayanamsha": "lahiri", "nodeType": "mean", "sensitivityMinutes": 10 }, "include": [ "panchang" ], "lang": "ne", "numerals": "devanagari" } ``` Responses: - `200` `Kundali`: The kundali. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `402` `Problem`: No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `413` `Problem`: The response would exceed 512 KB (`response_too_large`); narrow `include` or the range. - `422` `Problem`: `out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`. - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. - `503` `Problem`: Credit checks, rate limiting or key validation are briefly unavailable and the request cannot be served in degraded mode (`service_unavailable`); see `Retry-After`. Nothing is charged. ### POST /v1/kundali/planets **Graha positions** (`getPlanets`) Lagna and the nine grahas (sign, longitude, speed, house, retrograde, nakshatra, pada). 1 credit. Auth: `Authorization: Bearer `. Request body (`PlanetsRequest`): - `birth`, BirthInput, required: Birth date, local time and place. Supported range AD 1900-01-01 to 2100-12-31. - `options`, ChartOptions, optional - `lang`, "en" | "ne" | "hi", optional: Language of every `name` label. No credit surcharge for any language. - `numerals`, "latin" | "devanagari", optional: Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`. ```json { "birth": { "calendar": "BS", "date": "2050-05-12", "time": "14:35:00", "place": { "lat": 28.2096, "lng": 83.9856 } }, "lang": "en" } ``` Responses: - `200` `Planets`: Positions. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `402` `Problem`: No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `422` `Problem`: `out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`. - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. - `503` `Problem`: Credit checks, rate limiting or key validation are briefly unavailable and the request cannot be served in degraded mode (`service_unavailable`); see `Retry-After`. Nothing is charged. ### POST /v1/dasha **Dasha timeline** (`getDasha`) Vimshottari, Yogini or Tribhagi timeline to `levels` 1-3. `current` is returned only when `asOf` is given; the server clock is never used. 1 credit. Auth: `Authorization: Bearer `. Request body (`DashaRequest`): - `birth`, BirthInput, required: Birth date, local time and place. Supported range AD 1900-01-01 to 2100-12-31. - `options`, object, optional - `lang`, "en" | "ne" | "hi", optional: Language of every `name` label. No credit surcharge for any language. - `numerals`, "latin" | "devanagari", optional: Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`. ```json { "birth": { "calendar": "BS", "date": "2050-05-12", "time": "14:35:00", "place": { "lat": 28.2096, "lng": 83.9856 } }, "options": { "system": "vimshottari", "levels": 2, "asOf": "2026-11-01T00:00:00Z" } } ``` Responses: - `200` `Dasha`: The timeline. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `402` `Problem`: No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `413` `Problem`: The response would exceed 512 KB (`response_too_large`); narrow `include` or the range. - `422` `Problem`: `out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`. - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. - `503` `Problem`: Credit checks, rate limiting or key validation are briefly unavailable and the request cannot be served in degraded mode (`service_unavailable`); see `Retry-After`. Nothing is charged. ## Matching Ashtakoota guna milan and rashi compatibility. ### POST /v1/matching/ashtakoota **Ashtakoota guna milan** (`matchAshtakoota`) Eight kootas with obtained and maximum points, the total out of 36 and Nadi, Bhakuta and Gana dosha flags. Each subject is birth input or a kundali payload returned earlier. 1 credit. Auth: `Authorization: Bearer `. Request body (`AshtakootaRequest`): - `male`, MatchSubject, required: Birth input, or a kundali payload the API returned earlier. No server-side ids. - `female`, MatchSubject, required: Birth input, or a kundali payload the API returned earlier. No server-side ids. - `lang`, "en" | "ne" | "hi", optional: Language of every `name` label. No credit surcharge for any language. - `numerals`, "latin" | "devanagari", optional: Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`. ```json { "male": { "type": "birth", "birth": { "calendar": "AD", "date": "1990-05-15", "time": "10:30", "place": { "query": "Kathmandu" } } }, "female": { "type": "birth", "birth": { "calendar": "BS", "date": "2050-05-12", "time": "14:35", "place": { "lat": 28.2096, "lng": 83.9856 } } }, "lang": "en" } ``` Responses: - `200` `AshtakootaResponse`: Guna milan. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `402` `Problem`: No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `422` `Problem`: `out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`. - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. - `503` `Problem`: Credit checks, rate limiting or key validation are briefly unavailable and the request cannot be served in degraded mode (`service_unavailable`); see `Retry-After`. Nothing is charged. ### POST /v1/matching/ashtakoota/batch **Ashtakoota for 1-100 pairs** (`matchAshtakootaBatch`) Scores every pair; results keep the request order. 1 credit per pair. Auth: `Authorization: Bearer `. Request body (`AshtakootaBatchRequest`): - `pairs`, object[], required - `lang`, "en" | "ne" | "hi", optional: Language of every `name` label. No credit surcharge for any language. - `numerals`, "latin" | "devanagari", optional: Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`. ```json { "pairs": [ { "id": "p1", "male": { "type": "birth", "birth": { "calendar": "AD", "date": "1990-05-15", "time": "10:30", "place": { "query": "Kathmandu" } } }, "female": { "type": "birth", "birth": { "calendar": "BS", "date": "2050-05-12", "time": "14:35", "place": { "lat": 28.2096, "lng": 83.9856 } } } } ] } ``` Responses: - `200` `AshtakootaBatch`: One result per pair. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `402` `Problem`: No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `422` `Problem`: `out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`. - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. - `503` `Problem`: Credit checks, rate limiting or key validation are briefly unavailable and the request cannot be served in degraded mode (`service_unavailable`); see `Retry-After`. Nothing is charged. ### POST /v1/matching/rashi **Rashi compatibility** (`matchRashi`) Sign-to-sign compatibility from Graha Maitri and Bhakuta (symmetric, out of 12). 1 credit. Auth: `Authorization: Bearer `. Request body (`RashiRequest`): - `a`, integer, required - `b`, integer, required - `lang`, "en" | "ne" | "hi", optional: Language of every `name` label. No credit surcharge for any language. - `numerals`, "latin" | "devanagari", optional: Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`. ```json { "a": 3, "b": 9, "lang": "en" } ``` Responses: - `200` `RashiCompatibility`: Compatibility. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `402` `Problem`: No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. - `503` `Problem`: Credit checks, rate limiting or key validation are briefly unavailable and the request cannot be served in degraded mode (`service_unavailable`); see `Retry-After`. Nothing is charged. ## Panchang Daily panchang and choghadiya for any place. ### GET /v1/panchang/day **Daily panchang** (`getPanchangDay`) Tithi, nakshatra, yoga and karana at local sunrise with start and end instants; paksha; lunar month (adhik flag); sunrise, sunset, moonrise and moonset (local and UTC); 8 day and 8 night choghadiya; the BS and Nepal Sambat dates. Any location. 1 credit. Auth: `Authorization: Bearer `. Query parameters: - `date`, string, required - `calendar`, "AD" | "BS", optional: Calendar of `date` (default AD). - `lat`, number, required - `lng`, number, required - `tzid`, string, optional: Overrides the coordinate lookup. - `ayanamsha`, "lahiri" | "lahiri_icrc" | "true_chitra" | "raman" | "kp", optional - `tradition`, "nepal" | "amanta", optional - `sunriseConvention`, "center_geometric" | "upper_limb_refracted", optional - `lang`, "en" | "ne" | "hi", optional: Language of every `name` label. No credit surcharge for any language. - `numerals`, "latin" | "devanagari", optional: Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`. Responses: - `200` `PanchangDay`: The day. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `402` `Problem`: No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `422` `Problem`: `out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`. - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. - `503` `Problem`: Credit checks, rate limiting or key validation are briefly unavailable and the request cannot be served in degraded mode (`service_unavailable`); see `Retry-After`. Nothing is charged. ### GET /v1/panchang/range **Panchang for a date range** (`getPanchangRange`) Up to 366 days. Choghadiya only with `include=choghadiya`. 1 credit per started 31 days. Auth: `Authorization: Bearer `. Query parameters: - `from`, string, required - `to`, string, required - `calendar`, "AD" | "BS", optional: Calendar of `from` and `to` (default AD). - `lat`, number, required - `lng`, number, required - `tzid`, string, optional: Overrides the coordinate lookup. - `ayanamsha`, "lahiri" | "lahiri_icrc" | "true_chitra" | "raman" | "kp", optional - `tradition`, "nepal" | "amanta", optional - `sunriseConvention`, "center_geometric" | "upper_limb_refracted", optional - `lang`, "en" | "ne" | "hi", optional: Language of every `name` label. No credit surcharge for any language. - `numerals`, "latin" | "devanagari", optional: Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`. - `include`, "choghadiya", optional: `choghadiya` adds the periods to every day. Responses: - `200` `PanchangRange`: One entry per day. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `402` `Problem`: No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `413` `Problem`: The response would exceed 512 KB (`response_too_large`); narrow `include` or the range. - `422` `Problem`: `out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`. - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. - `503` `Problem`: Credit checks, rate limiting or key validation are briefly unavailable and the request cannot be served in degraded mode (`service_unavailable`); see `Retry-After`. Nothing is charged. ## Calendar Bikram Sambat, AD and Nepal Sambat. ### GET /v1/calendar/convert **Convert between AD and BS** (`convertDate`) Converts a date between AD (Gregorian) and Bikram Sambat, with the weekday and the BS `status` (`published` by the Samiti or `projected`). `include=nepalSambat` adds Nepal Sambat. 1 credit. Auth: `Authorization: Bearer `. Query parameters: - `date`, string, required - `calendar`, "AD" | "BS", required: Calendar of `date`. - `include`, "nepalSambat", optional: `nepalSambat` adds the Nepal Sambat date (from the lunar month and tithi at sunrise). - `lat`, number, optional: Place for the Nepal Sambat sunrise (default Kathmandu). - `lng`, number, optional - `lang`, "en" | "ne" | "hi", optional: Language of every `name` label. No credit surcharge for any language. - `numerals`, "latin" | "devanagari", optional: Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`. Responses: - `200` `DateConversion`: The date in both calendars. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `402` `Problem`: No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `422` `Problem`: `out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`. - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. - `503` `Problem`: Credit checks, rate limiting or key validation are briefly unavailable and the request cannot be served in degraded mode (`service_unavailable`); see `Retry-After`. Nothing is charged. ### GET /v1/calendar/month **BS month grid** (`getCalendarMonth`) Every day of a BS month with its AD date, weekday and tithi at sunrise, plus the month `bsStatus`. Give `lat` and `lng` together for another place (default Kathmandu). 1 credit. Auth: `Authorization: Bearer `. Query parameters: - `year`, integer, required - `month`, integer, required - `calendar`, "BS", optional: Month grids are Bikram Sambat months. - `lat`, number, optional: Place for tithi at sunrise (default Kathmandu). - `lng`, number, optional - `tradition`, "nepal" | "amanta", optional - `lang`, "en" | "ne" | "hi", optional: Language of every `name` label. No credit surcharge for any language. - `numerals`, "latin" | "devanagari", optional: Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`. Responses: - `200` `CalendarMonth`: The month. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `402` `Problem`: No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `422` `Problem`: `out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`. - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. - `503` `Problem`: Credit checks, rate limiting or key validation are briefly unavailable and the request cannot be served in degraded mode (`service_unavailable`); see `Retry-After`. Nothing is charged. ## Charts Server-rendered SVG charts. ### POST /v1/charts/svg **Chart SVG** (`renderChartSvg`) North or South Indian chart (D1 or D9) from birth input or a kundali payload returned earlier. Returns `image/svg+xml`, or JSON `{ svg }` when the request sends `Accept: application/json`. Theme it with the CSS custom properties `--kc-line`, `--kc-text` and `--kc-bg`; houses and grahas carry class names. Charts on the Free plan and the Starter pack carry a small "Powered by" mark. 1 credit. Auth: `Authorization: Bearer `. Request body (`ChartSvgRequest`): - `birth`, BirthInput, optional: Birth date, local time and place. Supported range AD 1900-01-01 to 2100-12-31. - `kundali`, ChartPayload, optional: A kundali payload returned by this API (lagna and graha longitudes are read). - `style`, "north" | "south", optional, default `"north"` - `chart`, "D1" | "D9", optional, default `"D1"` - `options`, object, optional - `lang`, "en" | "ne" | "hi", optional: Language of every `name` label. No credit surcharge for any language. - `numerals`, "latin" | "devanagari", optional: Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`. ```json { "birth": { "calendar": "BS", "date": "2050-05-12", "time": "14:35:00", "place": { "lat": 28.2096, "lng": 83.9856 } }, "style": "north", "chart": "D1", "lang": "ne" } ``` Responses: - `200` `ChartSvg`: The chart. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `402` `Problem`: No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `422` `Problem`: `out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`. - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. - `503` `Problem`: Credit checks, rate limiting or key validation are briefly unavailable and the request cannot be served in degraded mode (`service_unavailable`); see `Retry-After`. Nothing is charged. ## Places Geocoding and time zones. ### GET /v1/places/search **Search places** (`searchPlaces`) Ranked places from the bundled GeoNames gazetteer (cities over 15,000 people worldwide plus Nepal districts, local levels and towns): exact and prefix matches first, with a Nepal boost (stronger when `lang=ne`), then population. Names in en, ne and hi where GeoNames has them. Add a country, province or district after a comma to narrow. Free (0 credits), 30 requests per minute per key. Auth: `Authorization: Bearer `. Query parameters: - `q`, string, required - `lang`, "en" | "ne" | "hi", optional: Language of every `name` label. No credit surcharge for any language. - `limit`, integer, optional: Default 10. - `country`, string, optional Responses: - `200` `PlaceSearch`: Matches, best first. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. ### GET /v1/timezone **Time zone for a coordinate** (`getTimezone`) IANA zone for `lat`/`lng` and its UTC offset at `instant` (default now). Zone lookup uses present-day boundaries; pass an explicit `tzid` to kundali requests when a historical zone split matters. 1 credit. Auth: `Authorization: Bearer `. Query parameters: - `lat`, number, required - `lng`, number, required - `instant`, string, optional: Instant for the offset (default: now). Responses: - `200` `Timezone`: Zone and offset. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `402` `Problem`: No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. - `503` `Problem`: Credit checks, rate limiting or key validation are briefly unavailable and the request cannot be served in degraded mode (`service_unavailable`); see `Retry-After`. Nothing is charged. ## Account Client tokens, usage and metadata. ### POST /v1/tokens **Create a client token** (`createClientToken`) For mobile and browser apps: your backend calls this with an `sk_live_` key and hands the token to the app, which sends it as `Authorization: Bearer ct_...`. TTL at most 15 minutes, scoped to the listed endpoints, with an optional credit cap (never above the issuing key's own cap). Each use is re-checked against the issuing key: revoking the key stops its tokens within a minute, and token calls also count against the key's rate limit and monthly cap. Credits come from your organization. Free (0 credits). Auth: `Authorization: Bearer `. Request body (`TokenRequest`): - `scopes`, "kundali" | "kundali.planets" | "dasha" | "matching.ashtakoota" | "matching.ashtakoota.batch" | "matching.rashi" | "panchang.day" | "panchang.range" | "calendar.convert" | "calendar.month" | "charts.svg" | "places.search" | "timezone"[], required: Endpoint ids the token may call. - `ttlSeconds`, integer, optional: Default and maximum 900 (15 minutes). - `creditCap`, integer, optional: Maximum credits the token may consume. ```json { "scopes": [ "kundali", "charts.svg" ], "ttlSeconds": 600, "creditCap": 20 } ``` Responses: - `200` `ClientToken`: The token. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`). - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. ### GET /v1/usage **Credit balance** (`getUsage`) Organization balance by lot (the monthly free grant first, then paid lots by earliest expiry), the free grant remaining this UTC month, and this key's usage. Free (0 credits). Auth: `Authorization: Bearer `. Responses: - `200` `Usage`: Balance and lots. - `401` `Problem`: Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`). - `403` `Problem`: `secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type). - `429` `Problem`: Rate limited (`rate_limited`); see `Retry-After`. - `503` `Problem`: Credit checks, rate limiting or key validation are briefly unavailable and the request cannot be served in degraded mode (`service_unavailable`); see `Retry-After`. Nothing is charged. ### GET /v1/meta **Versions, ranges and attributions** (`getMeta`) Engine, API, tzdb, BS-table and override versions, supported options and ranges, data attributions and the demo key's sample subjects. No key needed. Free (0 credits). Auth: none required. Responses: - `200` `ApiMeta`: Metadata. - `400` `Problem`: Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).