{ "openapi": "3.1.0", "info": { "title": "Navapatra API", "version": "2026-11-01", "description": "Kundali, panchang, matching and Nepali (Bikram Sambat) calendar API for apps in Nepal and India.\n\n**Auth.** `Authorization: Bearer `. Secret keys (`sk_live_`, `sk_test_`) are server-only; browsers use a\npublishable key (`pk_`, origin allowlist) or a short-lived client token from `POST /v1/tokens`. The public key\n`demo` accepts the five sample subjects listed in `GET /v1/meta` (10 requests per minute per IP).\n\n**Versioning.** `Navapatra-Version: YYYY-MM-DD`, pinned per key. Data updates (tzdb, BS table, overrides) are not\npinned; `meta` echoes each data version.\n\n**Requests.** POST bodies carry `birth`, `options`, `include`, `lang` (`en`, `ne`, `hi`) and `numerals`\n(`latin`, `devanagari`). Every catalog value comes back as `{ index, name }` with `name` in the requested\nlanguage. No credit surcharge for any language.\n\n**Credits.** Only 2xx responses consume credits. Every response carries `x-request-id`, `x-credits-charged` and\n`x-credits-remaining`; rate limits use `RateLimit-*` headers and `429` comes with `Retry-After`.\n\n**Errors.** RFC 9457 `application/problem+json` with a stable `code`.\n\n**Privacy.** Stateless: request and response bodies are never logged or stored." }, "servers": [ { "url": "https://api.navapatra.com", "description": "Production" } ], "tags": [ { "name": "Kundali", "description": "Charts, positions and dasha timelines." }, { "name": "Matching", "description": "Ashtakoota guna milan and rashi compatibility." }, { "name": "Panchang", "description": "Daily panchang and choghadiya for any place." }, { "name": "Calendar", "description": "Bikram Sambat, AD and Nepal Sambat." }, { "name": "Charts", "description": "Server-rendered SVG charts." }, { "name": "Places", "description": "Geocoding and time zones." }, { "name": "Account", "description": "Client tokens, usage and metadata." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key (`sk_live_`, `sk_test_`, `pk_`), a client token (`ct_`) or the public key `demo`." } }, "schemas": { "Kundali": { "type": "object", "properties": { "subject": { "$ref": "#/components/schemas/Subject" }, "lagna": { "$ref": "#/components/schemas/Lagna" }, "grahas": { "type": "array", "items": { "$ref": "#/components/schemas/Graha" } }, "vargas": { "$ref": "#/components/schemas/Vargas" }, "moon": { "type": "object", "properties": { "rashi": { "$ref": "#/components/schemas/Label" }, "nakshatra": { "$ref": "#/components/schemas/Label" }, "pada": { "type": "integer" }, "syllable": { "type": "object", "properties": { "index": { "type": "integer" }, "en": { "type": "string" }, "ne": { "type": "string" }, "hi": { "type": "string" } }, "required": [ "index", "en", "ne", "hi" ] } }, "required": [ "rashi", "nakshatra", "pada", "syllable" ] }, "dashas": { "type": "object", "properties": { "vimshottari": { "$ref": "#/components/schemas/DashaTimeline" }, "yogini": { "$ref": "#/components/schemas/DashaTimeline" }, "tribhagi": { "$ref": "#/components/schemas/DashaTimeline" } }, "required": [ "vimshottari" ] }, "panchang": { "$ref": "#/components/schemas/PanchangElements" }, "sensitivity": { "type": "array", "items": { "$ref": "#/components/schemas/SensitivityChange" } }, "svg": { "type": "object", "properties": { "north": { "type": "string" }, "south": { "type": "string" } }, "required": [ "north" ] }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "subject", "lagna", "grahas", "vargas", "moon", "dashas", "meta" ] }, "Subject": { "type": "object", "properties": { "instantUtc": { "type": "string", "example": "1993-08-28T08:50:00Z" }, "place": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "name": { "type": "string" }, "country": { "type": "string" }, "admin1": { "type": [ "string", "null" ] }, "geonameId": { "type": "integer" } }, "required": [ "lat", "lng" ] }, "tzid": { "type": "string", "example": "Asia/Kathmandu" }, "utcOffset": { "type": "string", "example": "+05:45" }, "offsetSource": { "type": "string", "enum": [ "tzdb", "override", "historic_0540" ], "description": "Where `utcOffset` came from. `tzdb`: the IANA rules for `tzid` at that instant. `override`: the `birth.utcOffset` you sent. `historic_0540`: the pre-1986 Nepal +05:40 convention, applied because `options.nepalHistoricOffset` is `historic_0540`." }, "birth": { "type": "object", "properties": { "ad": { "type": "string" }, "bs": { "type": [ "string", "null" ] } }, "required": [ "ad", "bs" ] } }, "required": [ "instantUtc", "place", "tzid", "utcOffset", "offsetSource", "birth" ] }, "Lagna": { "type": "object", "properties": { "sign": { "$ref": "#/components/schemas/Label" }, "longitude": { "type": "number" }, "nakshatra": { "$ref": "#/components/schemas/Label" }, "pada": { "type": "integer" } }, "required": [ "sign", "longitude", "nakshatra", "pada" ] }, "Label": { "type": "object", "properties": { "index": { "type": "integer", "description": "Stable catalog index (1-based; weekday 0 = Sunday)." }, "name": { "type": "string", "description": "Name in the requested `lang` and `numerals`." } }, "required": [ "index", "name" ] }, "Graha": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "sun", "moon", "mars", "mercury", "jupiter", "venus", "saturn", "rahu", "ketu" ] }, "name": { "type": "string" }, "sign": { "$ref": "#/components/schemas/Label" }, "longitude": { "type": "number", "description": "Sidereal longitude, degrees [0, 360)." }, "speed": { "type": "number", "description": "Degrees per day." }, "house": { "type": "integer" }, "retrograde": { "type": "boolean" }, "nakshatra": { "$ref": "#/components/schemas/Label" }, "pada": { "type": "integer" } }, "required": [ "id", "name", "sign", "longitude", "speed", "house", "retrograde", "nakshatra", "pada" ] }, "Vargas": { "type": "object", "properties": { "D1": { "$ref": "#/components/schemas/VargaChart" }, "D2": { "$ref": "#/components/schemas/VargaChart" }, "D3": { "$ref": "#/components/schemas/VargaChart" }, "D4": { "$ref": "#/components/schemas/VargaChart" }, "D7": { "$ref": "#/components/schemas/VargaChart" }, "D9": { "$ref": "#/components/schemas/VargaChart" }, "D10": { "$ref": "#/components/schemas/VargaChart" }, "D12": { "$ref": "#/components/schemas/VargaChart" }, "D16": { "$ref": "#/components/schemas/VargaChart" }, "D20": { "$ref": "#/components/schemas/VargaChart" }, "D24": { "$ref": "#/components/schemas/VargaChart" }, "D27": { "$ref": "#/components/schemas/VargaChart" }, "D30": { "$ref": "#/components/schemas/VargaChart" }, "D40": { "$ref": "#/components/schemas/VargaChart" }, "D45": { "$ref": "#/components/schemas/VargaChart" }, "D60": { "$ref": "#/components/schemas/VargaChart" } }, "description": "D1 and D9 by default; all 16 with `include: [\"vargas\"]`." }, "VargaChart": { "type": "object", "properties": { "lagna": { "$ref": "#/components/schemas/Label" }, "sun": { "$ref": "#/components/schemas/Label" }, "moon": { "$ref": "#/components/schemas/Label" }, "mars": { "$ref": "#/components/schemas/Label" }, "mercury": { "$ref": "#/components/schemas/Label" }, "jupiter": { "$ref": "#/components/schemas/Label" }, "venus": { "$ref": "#/components/schemas/Label" }, "saturn": { "$ref": "#/components/schemas/Label" }, "rahu": { "$ref": "#/components/schemas/Label" }, "ketu": { "$ref": "#/components/schemas/Label" } }, "required": [ "lagna", "sun", "moon", "mars", "mercury", "jupiter", "venus", "saturn", "rahu", "ketu" ], "description": "Sign of the lagna and each graha in one divisional chart." }, "DashaTimeline": { "type": "object", "properties": { "system": { "$ref": "#/components/schemas/IdLabel" }, "levels": { "type": "integer" }, "yearDays": { "type": "number" }, "balanceAtBirth": { "type": "object", "properties": { "lord": { "$ref": "#/components/schemas/IdLabel" }, "years": { "type": "number" } }, "required": [ "lord", "years" ] }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/DashaPeriod" } }, "current": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "integer" }, "lord": { "$ref": "#/components/schemas/IdLabel" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "level", "lord", "start", "end" ] } } }, "required": [ "system", "levels", "yearDays", "balanceAtBirth", "periods" ] }, "IdLabel": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "index", "name" ], "description": "A catalog value with its stable string id." }, "DashaPeriod": { "allOf": [ { "$ref": "#/components/schemas/DashaPeriodL3" }, { "type": "object", "properties": { "periods": { "type": "array", "items": { "$ref": "#/components/schemas/DashaPeriodL2" } } } } ] }, "DashaPeriodL2": { "allOf": [ { "$ref": "#/components/schemas/DashaPeriodL3" }, { "type": "object", "properties": { "periods": { "type": "array", "items": { "$ref": "#/components/schemas/DashaPeriodL3" } } } } ] }, "DashaPeriodL3": { "type": "object", "properties": { "lord": { "$ref": "#/components/schemas/IdLabel" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "lord", "start", "end" ] }, "PanchangElements": { "type": "object", "properties": { "vara": { "$ref": "#/components/schemas/Label" }, "tithi": { "allOf": [ { "$ref": "#/components/schemas/TimedLabel" }, { "type": "object", "properties": { "paksha": { "$ref": "#/components/schemas/IdLabel" } }, "required": [ "paksha" ] } ], "description": "Element with its start and end instants (UTC, whole seconds)." }, "nakshatra": { "$ref": "#/components/schemas/TimedLabel" }, "yoga": { "$ref": "#/components/schemas/TimedLabel" }, "karana": { "$ref": "#/components/schemas/TimedLabel" }, "lunarMonth": { "allOf": [ { "$ref": "#/components/schemas/TimedLabel" }, { "type": "object", "properties": { "adhik": { "type": "boolean" }, "scheme": { "type": "string", "enum": [ "purnimanta", "amanta" ] } }, "required": [ "adhik", "scheme" ] } ], "description": "Element with its start and end instants (UTC, whole seconds)." } }, "required": [ "vara", "tithi", "nakshatra", "yoga", "karana", "lunarMonth" ], "description": "Lunar month index: 1 = Vaishakha ... 12 = Chaitra." }, "TimedLabel": { "type": "object", "properties": { "index": { "type": "integer" }, "name": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "index", "name", "start", "end" ], "description": "Element with its start and end instants (UTC, whole seconds)." }, "SensitivityChange": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "lagnaD1", "lagnaD9", "moonNakshatra", "moonPada" ] }, "from": { "$ref": "#/components/schemas/Label" }, "to": { "$ref": "#/components/schemas/Label" }, "changesAt": { "type": "string" } }, "required": [ "field", "from", "to", "changesAt" ] }, "Meta": { "type": "object", "properties": { "engineVersion": { "type": "string" }, "apiVersion": { "type": "string" }, "ayanamsha": { "type": "object", "properties": { "id": { "type": "string" }, "degrees": { "type": "number" } }, "required": [ "id", "degrees" ] }, "nodeType": { "type": "string", "enum": [ "mean", "true" ] }, "tradition": { "type": "string", "enum": [ "nepal", "amanta" ] }, "sunriseConvention": { "type": "string" }, "tzdbVersion": { "type": "string" }, "deltaTModelVersion": { "type": "string" }, "bsTableVersion": { "type": "string" }, "bsProjectionVersion": { "type": "string", "description": "Version of the BS projection model; present only when a BS date in the response is `projected`." }, "overridesVersion": { "type": [ "string", "null" ] } }, "required": [ "engineVersion", "apiVersion", "ayanamsha", "tzdbVersion", "deltaTModelVersion", "bsTableVersion", "overridesVersion" ], "description": "Everything needed to reproduce the result (FR-ENG-17)." }, "Problem": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable code.", "example": "invalid_input" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/Place" }, "description": "For `ambiguous_place`: up to 10 places." }, "details": { "type": "object", "additionalProperties": {} }, "topUpUrl": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code" ], "description": "RFC 9457 problem details (`application/problem+json`)." }, "Place": { "type": "object", "properties": { "id": { "type": "integer", "description": "GeoNames id." }, "name": { "type": "string" }, "names": { "type": "object", "properties": { "en": { "type": "string" }, "ne": { "type": [ "string", "null" ] }, "hi": { "type": [ "string", "null" ] } }, "required": [ "en", "ne", "hi" ] }, "country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code", "name" ] }, "admin1": { "type": [ "string", "null" ] }, "admin2": { "type": [ "string", "null" ] }, "lat": { "type": "number" }, "lng": { "type": "number" }, "population": { "type": "integer" }, "tzid": { "type": "string" }, "kind": { "type": "string", "enum": [ "populated_place", "admin_area" ] } }, "required": [ "id", "name", "names", "country", "admin1", "admin2", "lat", "lng", "population", "tzid", "kind" ] }, "KundaliRequest": { "type": "object", "properties": { "birth": { "$ref": "#/components/schemas/BirthInput" }, "options": { "$ref": "#/components/schemas/KundaliOptions" }, "include": { "type": "array", "items": { "type": "string", "enum": [ "vargas", "dashas.yogini", "dashas.tribhagi", "panchang", "svg", "svg.south" ], "description": "`svg` adds the North chart, `svg.south` also the South chart." }, "maxItems": 6 }, "lang": { "type": "string", "enum": [ "en", "ne", "hi" ], "description": "Language of every `name` label. No credit surcharge for any language.", "example": "en" }, "numerals": { "type": "string", "enum": [ "latin", "devanagari" ], "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "example": "latin" } }, "required": [ "birth" ], "example": { "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" } }, "BirthInput": { "type": "object", "properties": { "calendar": { "type": "string", "enum": [ "AD", "BS" ], "default": "AD", "description": "Calendar of `date`." }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2050-05-12" }, "time": { "type": "string", "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$", "description": "Local civil time at the birthplace.", "example": "14:35:00" }, "place": { "$ref": "#/components/schemas/PlaceInput" }, "utcOffset": { "type": "string", "pattern": "^[+-]\\d{2}:\\d{2}$", "description": "Explicit offset; overrides tzdb (`offsetSource: override`).", "example": "+05:45" }, "tzid": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Explicit IANA zone; overrides the coordinate lookup.", "example": "Asia/Kathmandu" } }, "required": [ "date", "time", "place" ], "description": "Birth date, local time and place. Supported range AD 1900-01-01 to 2100-12-31." }, "PlaceInput": { "type": "object", "properties": { "lat": { "type": "number", "minimum": -90, "maximum": 90, "example": 28.2096 }, "lng": { "type": "number", "minimum": -180, "maximum": 180, "example": 83.9856 }, "query": { "type": "string", "minLength": 2, "maxLength": 120, "description": "Place name resolved against the bundled GeoNames gazetteer, e.g. `Pokhara` or `Pokhara, Nepal`.", "example": "Pokhara" }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO 3166-1 alpha-2 filter for `query`.", "example": "NP" } }, "description": "Either coordinates `{ lat, lng }` or a `{ query }`. An ambiguous query fails with `422 ambiguous_place`." }, "KundaliOptions": { "type": "object", "properties": { "ayanamsha": { "type": "string", "enum": [ "lahiri", "lahiri_icrc", "true_chitra", "raman", "kp" ], "default": "lahiri", "description": "Sidereal zodiac. Echoed in `meta.ayanamsha`." }, "nodeType": { "type": "string", "enum": [ "mean", "true" ], "default": "mean", "description": "Lunar node used for Rahu and Ketu." }, "disambiguation": { "type": "string", "enum": [ "earlier", "later" ], "description": "Resolves a local time skipped or repeated by a clock change (else `422 ambiguous_local_time`)." }, "nepalHistoricOffset": { "type": "string", "enum": [ "tzdb", "historic_0540" ], "default": "tzdb", "description": "Nepal before 1986: tzdb (+05:30) or the historic +05:40 convention." }, "sensitivityMinutes": { "type": "integer", "minimum": 1, "maximum": 60, "description": "Adds `sensitivity`: lagna (D1, D9) and Moon nakshatra or pada changes within ±N minutes." }, "dasha": { "type": "object", "properties": { "levels": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] } ], "default": 2, "description": "1 maha, 2 antar, 3 pratyantar." }, "yearDays": { "type": "number", "exclusiveMinimum": 0, "maximum": 400, "default": 365.25, "description": "Days per dasha year." }, "asOf": { "type": "string", "format": "date-time", "description": "When given, `current` lists the running periods at this instant. The server clock is never used.", "example": "2026-11-01T00:00:00Z" } } }, "tradition": { "type": "string", "enum": [ "nepal", "amanta" ], "default": "nepal", "description": "`nepal`: purnimanta month names (Samiti practice). `amanta`: new-moon months." }, "sunriseConvention": { "type": "string", "enum": [ "upper_limb_refracted", "center_geometric" ], "default": "upper_limb_refracted", "description": "Sunrise and sunset convention, used for the vara, the daily elements and choghadiya. Moonrise and moonset always use the disc centre." } } }, "Planets": { "type": "object", "properties": { "subject": { "$ref": "#/components/schemas/Subject" }, "lagna": { "$ref": "#/components/schemas/Lagna" }, "grahas": { "type": "array", "items": { "$ref": "#/components/schemas/Graha" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "subject", "lagna", "grahas", "meta" ] }, "PlanetsRequest": { "type": "object", "properties": { "birth": { "$ref": "#/components/schemas/BirthInput" }, "options": { "$ref": "#/components/schemas/ChartOptions" }, "lang": { "type": "string", "enum": [ "en", "ne", "hi" ], "description": "Language of every `name` label. No credit surcharge for any language.", "example": "en" }, "numerals": { "type": "string", "enum": [ "latin", "devanagari" ], "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "example": "latin" } }, "required": [ "birth" ], "example": { "birth": { "calendar": "BS", "date": "2050-05-12", "time": "14:35:00", "place": { "lat": 28.2096, "lng": 83.9856 } }, "lang": "en" } }, "ChartOptions": { "type": "object", "properties": { "ayanamsha": { "type": "string", "enum": [ "lahiri", "lahiri_icrc", "true_chitra", "raman", "kp" ], "default": "lahiri", "description": "Sidereal zodiac. Echoed in `meta.ayanamsha`." }, "nodeType": { "type": "string", "enum": [ "mean", "true" ], "default": "mean", "description": "Lunar node used for Rahu and Ketu." }, "disambiguation": { "type": "string", "enum": [ "earlier", "later" ], "description": "Resolves a local time skipped or repeated by a clock change (else `422 ambiguous_local_time`)." }, "nepalHistoricOffset": { "type": "string", "enum": [ "tzdb", "historic_0540" ], "default": "tzdb", "description": "Nepal before 1986: tzdb (+05:30) or the historic +05:40 convention." } } }, "Dasha": { "type": "object", "properties": { "subject": { "$ref": "#/components/schemas/Subject" }, "dasha": { "$ref": "#/components/schemas/DashaTimeline" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "subject", "dasha", "meta" ] }, "DashaRequest": { "type": "object", "properties": { "birth": { "$ref": "#/components/schemas/BirthInput" }, "options": { "type": "object", "properties": { "ayanamsha": { "type": "string", "enum": [ "lahiri", "lahiri_icrc", "true_chitra", "raman", "kp" ], "default": "lahiri", "description": "Sidereal zodiac. Echoed in `meta.ayanamsha`." }, "nodeType": { "type": "string", "enum": [ "mean", "true" ], "default": "mean", "description": "Lunar node used for Rahu and Ketu." }, "disambiguation": { "type": "string", "enum": [ "earlier", "later" ], "description": "Resolves a local time skipped or repeated by a clock change (else `422 ambiguous_local_time`)." }, "nepalHistoricOffset": { "type": "string", "enum": [ "tzdb", "historic_0540" ], "default": "tzdb", "description": "Nepal before 1986: tzdb (+05:30) or the historic +05:40 convention." }, "system": { "type": "string", "enum": [ "vimshottari", "yogini", "tribhagi" ], "default": "vimshottari" }, "levels": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] } ], "default": 2, "description": "1 maha, 2 antar, 3 pratyantar." }, "yearDays": { "type": "number", "exclusiveMinimum": 0, "maximum": 400, "default": 365.25, "description": "Days per dasha year." }, "asOf": { "type": "string", "format": "date-time", "description": "When given, `current` lists the running periods at this instant. The server clock is never used.", "example": "2026-11-01T00:00:00Z" } } }, "lang": { "type": "string", "enum": [ "en", "ne", "hi" ], "description": "Language of every `name` label. No credit surcharge for any language.", "example": "en" }, "numerals": { "type": "string", "enum": [ "latin", "devanagari" ], "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "example": "latin" } }, "required": [ "birth" ], "example": { "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" } } }, "AshtakootaResponse": { "allOf": [ { "$ref": "#/components/schemas/Ashtakoota" }, { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/MatchMeta" } }, "required": [ "meta" ] } ] }, "MatchMeta": { "type": "object", "properties": { "engineVersion": { "type": "string" }, "apiVersion": { "type": "string" }, "ayanamsha": { "type": "object", "properties": { "id": { "type": "string" }, "degrees": { "type": "number" } }, "required": [ "id", "degrees" ] }, "nodeType": { "type": "string", "enum": [ "mean", "true" ] }, "tzdbVersion": { "type": "string" }, "deltaTModelVersion": { "type": "string" }, "bsTableVersion": { "type": "string" }, "bsProjectionVersion": { "type": "string", "description": "Version of the BS projection model; present only when a BS date in the response is `projected`." }, "overridesVersion": { "type": [ "string", "null" ] } }, "required": [ "engineVersion", "apiVersion", "tzdbVersion", "deltaTModelVersion", "bsTableVersion", "overridesVersion" ], "description": "Versions behind a matching result. `ayanamsha` and `nodeType` are those of the first subject computed from birth input (male first); both are omitted when no subject was (kundali payloads carry their own `meta`)." }, "Ashtakoota": { "type": "object", "properties": { "male": { "type": "object", "properties": { "rashi": { "$ref": "#/components/schemas/Label" }, "nakshatra": { "$ref": "#/components/schemas/Label" }, "moonLongitude": { "type": "number" } }, "required": [ "rashi", "nakshatra", "moonLongitude" ] }, "female": { "type": "object", "properties": { "rashi": { "$ref": "#/components/schemas/Label" }, "nakshatra": { "$ref": "#/components/schemas/Label" }, "moonLongitude": { "type": "number" } }, "required": [ "rashi", "nakshatra", "moonLongitude" ] }, "kootas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "obtained": { "type": "number" }, "max": { "type": "number" }, "detail": { "type": "object", "properties": { "male": { "$ref": "#/components/schemas/IdLabel" }, "female": { "$ref": "#/components/schemas/IdLabel" } }, "required": [ "male", "female" ] } }, "required": [ "id", "index", "name", "obtained", "max", "detail" ] } }, "total": { "type": "number" }, "max": { "type": "number" }, "percent": { "type": "number" }, "dosha": { "type": "object", "properties": { "nadi": { "type": "boolean" }, "bhakuta": { "type": "boolean" }, "gana": { "type": "boolean" } }, "required": [ "nadi", "bhakuta", "gana" ] } }, "required": [ "male", "female", "kootas", "total", "max", "percent", "dosha" ] }, "AshtakootaRequest": { "type": "object", "properties": { "male": { "$ref": "#/components/schemas/MatchSubject" }, "female": { "$ref": "#/components/schemas/MatchSubject" }, "lang": { "type": "string", "enum": [ "en", "ne", "hi" ], "description": "Language of every `name` label. No credit surcharge for any language.", "example": "en" }, "numerals": { "type": "string", "enum": [ "latin", "devanagari" ], "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "example": "latin" } }, "required": [ "male", "female" ], "example": { "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" } }, "MatchSubject": { "oneOf": [ { "$ref": "#/components/schemas/MatchSubjectBirth" }, { "$ref": "#/components/schemas/MatchSubjectKundali" } ], "discriminator": { "propertyName": "type", "mapping": { "birth": "#/components/schemas/MatchSubjectBirth", "kundali": "#/components/schemas/MatchSubjectKundali" } }, "description": "Birth input, or a kundali payload the API returned earlier. No server-side ids." }, "MatchSubjectBirth": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "birth" ] }, "birth": { "$ref": "#/components/schemas/BirthInput" }, "options": { "$ref": "#/components/schemas/ChartOptions" } }, "required": [ "type", "birth" ] }, "MatchSubjectKundali": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "kundali" ] }, "kundali": { "$ref": "#/components/schemas/KundaliPayload" } }, "required": [ "type", "kundali" ] }, "KundaliPayload": { "type": "object", "properties": { "grahas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "longitude": { "type": "number", "minimum": 0, "exclusiveMaximum": 360 } }, "required": [ "id", "longitude" ], "additionalProperties": {} }, "minItems": 1, "maxItems": 9 } }, "required": [ "grahas" ], "additionalProperties": {}, "description": "A kundali previously returned by this API; only `grahas[].longitude` of the Moon is read." }, "AshtakootaBatch": { "type": "object", "properties": { "results": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Ashtakoota" }, { "type": "object", "properties": { "id": { "type": "string" } } } ] } }, "meta": { "$ref": "#/components/schemas/MatchMeta" } }, "required": [ "results", "meta" ] }, "AshtakootaBatchRequest": { "type": "object", "properties": { "pairs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64 }, "male": { "$ref": "#/components/schemas/MatchSubject" }, "female": { "$ref": "#/components/schemas/MatchSubject" } }, "required": [ "male", "female" ] }, "minItems": 1, "maxItems": 100 }, "lang": { "type": "string", "enum": [ "en", "ne", "hi" ], "description": "Language of every `name` label. No credit surcharge for any language.", "example": "en" }, "numerals": { "type": "string", "enum": [ "latin", "devanagari" ], "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "example": "latin" } }, "required": [ "pairs" ], "example": { "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 } } } } ] } }, "RashiCompatibility": { "type": "object", "properties": { "a": { "$ref": "#/components/schemas/Label" }, "b": { "$ref": "#/components/schemas/Label" }, "grahaMaitri": { "type": "object", "properties": { "obtained": { "type": "number" }, "max": { "type": "number" } }, "required": [ "obtained", "max" ] }, "bhakuta": { "type": "object", "properties": { "obtained": { "type": "number" }, "max": { "type": "number" } }, "required": [ "obtained", "max" ] }, "total": { "type": "number" }, "max": { "type": "number" }, "percent": { "type": "number" }, "meta": { "$ref": "#/components/schemas/MatchMeta" } }, "required": [ "a", "b", "grahaMaitri", "bhakuta", "total", "max", "percent", "meta" ], "description": "Symmetric: (a, b) and (b, a) score the same." }, "RashiRequest": { "type": "object", "properties": { "a": { "type": "integer", "minimum": 1, "maximum": 12 }, "b": { "type": "integer", "minimum": 1, "maximum": 12 }, "lang": { "type": "string", "enum": [ "en", "ne", "hi" ], "description": "Language of every `name` label. No credit surcharge for any language.", "example": "en" }, "numerals": { "type": "string", "enum": [ "latin", "devanagari" ], "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "example": "latin" } }, "required": [ "a", "b" ], "example": { "a": 3, "b": 9, "lang": "en" } }, "PanchangDay": { "type": "object", "properties": { "date": { "type": "string" }, "bs": { "$ref": "#/components/schemas/BsDate" }, "tzid": { "type": "string" }, "sunrise": { "$ref": "#/components/schemas/LocalInstant" }, "sunset": { "$ref": "#/components/schemas/LocalInstant" }, "moonrise": { "$ref": "#/components/schemas/LocalInstant" }, "moonset": { "$ref": "#/components/schemas/LocalInstant" }, "vara": { "$ref": "#/components/schemas/Label" }, "tithi": { "allOf": [ { "$ref": "#/components/schemas/TimedLabel" }, { "type": "object", "properties": { "paksha": { "$ref": "#/components/schemas/IdLabel" } }, "required": [ "paksha" ] } ], "description": "Element with its start and end instants (UTC, whole seconds)." }, "nakshatra": { "$ref": "#/components/schemas/TimedLabel" }, "yoga": { "$ref": "#/components/schemas/TimedLabel" }, "karana": { "$ref": "#/components/schemas/TimedLabel" }, "lunarMonth": { "allOf": [ { "$ref": "#/components/schemas/TimedLabel" }, { "type": "object", "properties": { "adhik": { "type": "boolean" }, "scheme": { "type": "string", "enum": [ "purnimanta", "amanta" ] } }, "required": [ "adhik", "scheme" ] } ], "description": "Element with its start and end instants (UTC, whole seconds)." }, "nepalSambat": { "$ref": "#/components/schemas/NepalSambatDate" }, "choghadiya": { "type": "object", "properties": { "day": { "type": "array", "items": { "$ref": "#/components/schemas/Choghadiya" } }, "night": { "type": "array", "items": { "$ref": "#/components/schemas/Choghadiya" } } }, "required": [ "day", "night" ] }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "date", "bs", "tzid", "sunrise", "sunset", "moonrise", "moonset", "vara", "tithi", "nakshatra", "yoga", "karana", "lunarMonth", "nepalSambat", "choghadiya", "meta" ] }, "BsDate": { "type": [ "object", "null" ], "properties": { "date": { "type": "string" }, "year": { "type": "integer" }, "month": { "$ref": "#/components/schemas/Label" }, "day": { "type": "integer" }, "status": { "type": "string", "enum": [ "published", "projected" ] }, "text": { "type": "string", "description": "Display string in the requested language and numerals." } }, "required": [ "date", "year", "month", "day", "status", "text" ] }, "LocalInstant": { "type": [ "object", "null" ], "properties": { "utc": { "type": "string" }, "local": { "type": "string" } }, "required": [ "utc", "local" ] }, "NepalSambatDate": { "type": [ "object", "null" ], "properties": { "year": { "type": "integer" }, "month": { "$ref": "#/components/schemas/Label" }, "paksha": { "$ref": "#/components/schemas/Label" }, "day": { "type": "integer" }, "adhik": { "type": "boolean" }, "text": { "type": "string" } }, "required": [ "year", "month", "paksha", "day", "adhik", "text" ], "description": "Month index 1 = Kachhala ... 12 = Kaula, 13 = Anala (adhik)." }, "Choghadiya": { "type": "object", "properties": { "period": { "type": "integer", "description": "1-8 within the day or night." }, "id": { "type": "string" }, "index": { "type": "integer" }, "name": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "period", "id", "index", "name", "start", "end" ] }, "PanchangRange": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/PanchangRangeDay" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "from", "to", "days", "meta" ] }, "PanchangRangeDay": { "type": "object", "properties": { "date": { "type": "string" }, "bs": { "$ref": "#/components/schemas/BsDate" }, "tzid": { "type": "string" }, "sunrise": { "$ref": "#/components/schemas/LocalInstant" }, "sunset": { "$ref": "#/components/schemas/LocalInstant" }, "moonrise": { "$ref": "#/components/schemas/LocalInstant" }, "moonset": { "$ref": "#/components/schemas/LocalInstant" }, "vara": { "$ref": "#/components/schemas/Label" }, "tithi": { "allOf": [ { "$ref": "#/components/schemas/TimedLabel" }, { "type": "object", "properties": { "paksha": { "$ref": "#/components/schemas/IdLabel" } }, "required": [ "paksha" ] } ], "description": "Element with its start and end instants (UTC, whole seconds)." }, "nakshatra": { "$ref": "#/components/schemas/TimedLabel" }, "yoga": { "$ref": "#/components/schemas/TimedLabel" }, "karana": { "$ref": "#/components/schemas/TimedLabel" }, "lunarMonth": { "allOf": [ { "$ref": "#/components/schemas/TimedLabel" }, { "type": "object", "properties": { "adhik": { "type": "boolean" }, "scheme": { "type": "string", "enum": [ "purnimanta", "amanta" ] } }, "required": [ "adhik", "scheme" ] } ], "description": "Element with its start and end instants (UTC, whole seconds)." }, "nepalSambat": { "$ref": "#/components/schemas/NepalSambatDate" }, "choghadiya": { "type": "object", "properties": { "day": { "type": "array", "items": { "$ref": "#/components/schemas/Choghadiya" } }, "night": { "type": "array", "items": { "$ref": "#/components/schemas/Choghadiya" } } }, "required": [ "day", "night" ] } }, "required": [ "date", "bs", "tzid", "sunrise", "sunset", "moonrise", "moonset", "vara", "tithi", "nakshatra", "yoga", "karana", "lunarMonth", "nepalSambat" ] }, "DateConversion": { "type": "object", "properties": { "ad": { "$ref": "#/components/schemas/AdDate" }, "bs": { "$ref": "#/components/schemas/BsDate" }, "nepalSambat": { "$ref": "#/components/schemas/NepalSambatDate" }, "meta": { "type": "object", "properties": { "bsTableVersion": { "type": "string" }, "bsProjectionVersion": { "type": "string", "description": "Version of the BS projection model; present only when a BS date in the response is `projected`." }, "apiVersion": { "type": "string" } }, "required": [ "bsTableVersion", "apiVersion" ] } }, "required": [ "ad", "bs", "meta" ] }, "AdDate": { "type": "object", "properties": { "date": { "type": "string" }, "year": { "type": "integer" }, "month": { "type": "integer" }, "day": { "type": "integer" }, "weekday": { "$ref": "#/components/schemas/Label" } }, "required": [ "date", "year", "month", "day", "weekday" ] }, "CalendarMonth": { "type": "object", "properties": { "calendar": { "type": "string", "enum": [ "BS" ] }, "year": { "type": "integer" }, "month": { "$ref": "#/components/schemas/Label" }, "bsStatus": { "type": "string", "enum": [ "published", "projected" ] }, "days": { "type": "array", "items": { "type": "object", "properties": { "ad": { "type": "string" }, "bs": { "type": "object", "properties": { "date": { "type": "string" }, "day": { "type": "integer" }, "text": { "type": "string" } }, "required": [ "date", "day", "text" ] }, "weekday": { "$ref": "#/components/schemas/Label" }, "tithi": { "allOf": [ { "$ref": "#/components/schemas/Label" }, { "type": "object", "properties": { "paksha": { "$ref": "#/components/schemas/IdLabel" } }, "required": [ "paksha" ] } ] } }, "required": [ "ad", "bs", "weekday", "tithi" ] } }, "meta": { "type": "object", "properties": { "engineVersion": { "type": "string" }, "apiVersion": { "type": "string" }, "tzdbVersion": { "type": "string" }, "deltaTModelVersion": { "type": "string" }, "bsTableVersion": { "type": "string" }, "bsProjectionVersion": { "type": "string", "description": "Version of the BS projection model; present only when a BS date in the response is `projected`." }, "overridesVersion": { "type": [ "string", "null" ] }, "tzid": { "type": "string" } }, "required": [ "engineVersion", "apiVersion", "tzdbVersion", "deltaTModelVersion", "bsTableVersion", "overridesVersion", "tzid" ] } }, "required": [ "calendar", "year", "month", "bsStatus", "days", "meta" ], "description": "Holidays and festivals are added once their data source is settled (PRD D7)." }, "ChartSvg": { "type": "object", "properties": { "svg": { "type": "string" }, "style": { "type": "string", "enum": [ "north", "south" ] }, "chart": { "type": "string", "enum": [ "D1", "D9" ] } }, "required": [ "svg", "style", "chart" ] }, "ChartSvgRequest": { "type": "object", "properties": { "birth": { "$ref": "#/components/schemas/BirthInput" }, "kundali": { "$ref": "#/components/schemas/ChartPayload" }, "style": { "type": "string", "enum": [ "north", "south" ], "default": "north" }, "chart": { "type": "string", "enum": [ "D1", "D9" ], "default": "D1" }, "options": { "allOf": [ { "$ref": "#/components/schemas/ChartOptions" }, { "type": "object", "properties": { "showDegrees": { "type": "boolean" }, "size": { "type": "integer", "minimum": 100, "maximum": 2000 } } } ] }, "lang": { "type": "string", "enum": [ "en", "ne", "hi" ], "description": "Language of every `name` label. No credit surcharge for any language.", "example": "en" }, "numerals": { "type": "string", "enum": [ "latin", "devanagari" ], "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "example": "latin" } }, "example": { "birth": { "calendar": "BS", "date": "2050-05-12", "time": "14:35:00", "place": { "lat": 28.2096, "lng": 83.9856 } }, "style": "north", "chart": "D1", "lang": "ne" } }, "ChartPayload": { "type": "object", "properties": { "lagna": { "type": "object", "properties": { "longitude": { "type": "number", "minimum": 0, "exclusiveMaximum": 360 } }, "required": [ "longitude" ], "additionalProperties": {} }, "grahas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "sun", "moon", "mars", "mercury", "jupiter", "venus", "saturn", "rahu", "ketu" ] }, "longitude": { "type": "number", "minimum": 0, "exclusiveMaximum": 360 }, "retrograde": { "type": "boolean" } }, "required": [ "id", "longitude" ], "additionalProperties": {} }, "minItems": 1, "maxItems": 9 } }, "required": [ "lagna", "grahas" ], "additionalProperties": {}, "description": "A kundali payload returned by this API (lagna and graha longitudes are read)." }, "PlaceSearch": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Place" } }, "ambiguous": { "type": "boolean", "description": "True when the top two results are equally plausible places of that name (both exact, far apart, comparable population). Ask the user to pick instead of taking the first; birth input with this query fails with `ambiguous_place`." }, "attribution": { "type": "string" } }, "required": [ "results", "ambiguous", "attribution" ] }, "Timezone": { "type": "object", "properties": { "tzid": { "type": "string" }, "utcOffset": { "type": "string" }, "instant": { "type": "string" }, "source": { "type": "string", "enum": [ "tz-lookup" ] } }, "required": [ "tzid", "utcOffset", "instant", "source" ] }, "ClientToken": { "type": "object", "properties": { "token": { "type": "string" }, "expiresAt": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "creditCap": { "type": [ "integer", "null" ] } }, "required": [ "token", "expiresAt", "scopes", "creditCap" ] }, "TokenRequest": { "type": "object", "properties": { "scopes": { "type": "array", "items": { "type": "string", "enum": [ "kundali", "kundali.planets", "dasha", "matching.ashtakoota", "matching.ashtakoota.batch", "matching.rashi", "panchang.day", "panchang.range", "calendar.convert", "calendar.month", "charts.svg", "places.search", "timezone" ] }, "minItems": 1, "description": "Endpoint ids the token may call." }, "ttlSeconds": { "type": "integer", "minimum": 60, "maximum": 900, "description": "Default and maximum 900 (15 minutes)." }, "creditCap": { "type": "integer", "minimum": 1, "description": "Maximum credits the token may consume." } }, "required": [ "scopes" ], "example": { "scopes": [ "kundali", "charts.svg" ], "ttlSeconds": 600, "creditCap": 20 } }, "Usage": { "type": "object", "properties": { "orgId": { "type": "string" }, "balance": { "type": "integer" }, "month": { "type": "string" }, "freeGrant": { "type": "object", "properties": { "granted": { "type": "integer" }, "remaining": { "type": "integer" }, "expiresAt": { "type": "string" } }, "required": [ "granted", "remaining", "expiresAt" ] }, "lots": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string", "enum": [ "grant", "pack", "annual", "adjust" ] }, "remaining": { "type": "integer" }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "id", "source", "remaining", "expiresAt" ] } }, "key": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "creditCap": { "type": [ "integer", "null" ] }, "usedThisMonth": { "type": "integer" } }, "required": [ "id", "type", "creditCap", "usedThisMonth" ] }, "testQuota": { "type": "object", "properties": { "day": { "type": "string" }, "used": { "type": "integer" }, "limit": { "type": "integer" } }, "required": [ "day", "used", "limit" ] } }, "required": [ "orgId", "balance", "month", "freeGrant", "lots", "key", "testQuota" ] }, "ApiMeta": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "apiVersions": { "type": "array", "items": { "type": "string" } }, "engineVersion": { "type": "string" }, "tzdbVersion": { "type": "string" }, "deltaTModelVersion": { "type": "string" }, "bsTableVersion": { "type": "string" }, "bsPublishedThrough": { "type": "integer" }, "overridesVersion": { "type": [ "string", "null" ] }, "ayanamshas": { "type": "array", "items": { "type": "string" } }, "nodeTypes": { "type": "array", "items": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "string" } }, "numerals": { "type": "array", "items": { "type": "string" } }, "supportedRange": { "type": "object", "properties": { "ad": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "bs": { "type": "object", "properties": { "from": { "type": "integer" }, "to": { "type": "integer" }, "fromDate": { "type": "string", "description": "First supported BS date (= AD 1900-01-01); BS years at the ends are partial." }, "toDate": { "type": "string", "description": "Last supported BS date (= AD 2100-12-31)." } }, "required": [ "from", "to", "fromDate", "toDate" ] } }, "required": [ "ad", "bs" ] }, "attributions": { "type": "array", "items": { "type": "string" } }, "demo": { "type": "object", "properties": { "key": { "type": "string" }, "rateLimitPerMinute": { "type": "integer" }, "samples": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "birth": { "$ref": "#/components/schemas/BirthInput" } }, "required": [ "id", "label", "birth" ] } } }, "required": [ "key", "rateLimitPerMinute", "samples" ] } }, "required": [ "apiVersion", "apiVersions", "engineVersion", "tzdbVersion", "deltaTModelVersion", "bsTableVersion", "bsPublishedThrough", "overridesVersion", "ayanamshas", "nodeTypes", "languages", "numerals", "supportedRange", "attributions", "demo" ] } }, "parameters": {} }, "paths": { "/v1/kundali": { "post": { "operationId": "createKundali", "tags": [ "Kundali" ], "summary": "Full kundali", "description": "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.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KundaliRequest" } } } }, "responses": { "200": { "description": "The kundali.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Kundali" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The response would exceed 512 KB (`response_too_large`); narrow `include` or the range.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "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.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/kundali/planets": { "post": { "operationId": "getPlanets", "tags": [ "Kundali" ], "summary": "Graha positions", "description": "Lagna and the nine grahas (sign, longitude, speed, house, retrograde, nakshatra, pada). 1 credit.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanetsRequest" } } } }, "responses": { "200": { "description": "Positions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Planets" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "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.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/dasha": { "post": { "operationId": "getDasha", "tags": [ "Kundali" ], "summary": "Dasha timeline", "description": "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.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashaRequest" } } } }, "responses": { "200": { "description": "The timeline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dasha" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The response would exceed 512 KB (`response_too_large`); narrow `include` or the range.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "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.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/matching/ashtakoota": { "post": { "operationId": "matchAshtakoota", "tags": [ "Matching" ], "summary": "Ashtakoota guna milan", "description": "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.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AshtakootaRequest" } } } }, "responses": { "200": { "description": "Guna milan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AshtakootaResponse" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "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.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/matching/ashtakoota/batch": { "post": { "operationId": "matchAshtakootaBatch", "tags": [ "Matching" ], "summary": "Ashtakoota for 1-100 pairs", "description": "Scores every pair; results keep the request order. 1 credit per pair.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AshtakootaBatchRequest" } } } }, "responses": { "200": { "description": "One result per pair.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AshtakootaBatch" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "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.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/matching/rashi": { "post": { "operationId": "matchRashi", "tags": [ "Matching" ], "summary": "Rashi compatibility", "description": "Sign-to-sign compatibility from Graha Maitri and Bhakuta (symmetric, out of 12). 1 credit.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RashiRequest" } } } }, "responses": { "200": { "description": "Compatibility.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RashiCompatibility" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "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.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/panchang/day": { "get": { "operationId": "getPanchangDay", "tags": [ "Panchang" ], "summary": "Daily panchang", "description": "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.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2083-01-01" }, "required": true, "name": "date", "in": "query" }, { "schema": { "type": "string", "enum": [ "AD", "BS" ], "description": "Calendar of `date` (default AD).", "example": "BS" }, "required": false, "description": "Calendar of `date` (default AD).", "name": "calendar", "in": "query" }, { "schema": { "type": "number", "minimum": -90, "maximum": 90, "example": 27.7172 }, "required": true, "name": "lat", "in": "query" }, { "schema": { "type": "number", "minimum": -180, "maximum": 180, "example": 85.324 }, "required": true, "name": "lng", "in": "query" }, { "schema": { "type": "string", "maxLength": 64, "description": "Overrides the coordinate lookup." }, "required": false, "description": "Overrides the coordinate lookup.", "name": "tzid", "in": "query" }, { "schema": { "type": "string", "enum": [ "lahiri", "lahiri_icrc", "true_chitra", "raman", "kp" ] }, "required": false, "name": "ayanamsha", "in": "query" }, { "schema": { "type": "string", "enum": [ "nepal", "amanta" ] }, "required": false, "name": "tradition", "in": "query" }, { "schema": { "type": "string", "enum": [ "center_geometric", "upper_limb_refracted" ] }, "required": false, "name": "sunriseConvention", "in": "query" }, { "schema": { "type": "string", "enum": [ "en", "ne", "hi" ], "description": "Language of every `name` label. No credit surcharge for any language.", "example": "en" }, "required": false, "description": "Language of every `name` label. No credit surcharge for any language.", "name": "lang", "in": "query" }, { "schema": { "type": "string", "enum": [ "latin", "devanagari" ], "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "example": "latin" }, "required": false, "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "name": "numerals", "in": "query" } ], "responses": { "200": { "description": "The day.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PanchangDay" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "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.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/panchang/range": { "get": { "operationId": "getPanchangRange", "tags": [ "Panchang" ], "summary": "Panchang for a date range", "description": "Up to 366 days. Choghadiya only with `include=choghadiya`. 1 credit per started 31 days.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2083-01-01" }, "required": true, "name": "from", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2083-01-31" }, "required": true, "name": "to", "in": "query" }, { "schema": { "type": "string", "enum": [ "AD", "BS" ], "description": "Calendar of `from` and `to` (default AD)." }, "required": false, "description": "Calendar of `from` and `to` (default AD).", "name": "calendar", "in": "query" }, { "schema": { "type": "number", "minimum": -90, "maximum": 90, "example": 27.7172 }, "required": true, "name": "lat", "in": "query" }, { "schema": { "type": "number", "minimum": -180, "maximum": 180, "example": 85.324 }, "required": true, "name": "lng", "in": "query" }, { "schema": { "type": "string", "maxLength": 64, "description": "Overrides the coordinate lookup." }, "required": false, "description": "Overrides the coordinate lookup.", "name": "tzid", "in": "query" }, { "schema": { "type": "string", "enum": [ "lahiri", "lahiri_icrc", "true_chitra", "raman", "kp" ] }, "required": false, "name": "ayanamsha", "in": "query" }, { "schema": { "type": "string", "enum": [ "nepal", "amanta" ] }, "required": false, "name": "tradition", "in": "query" }, { "schema": { "type": "string", "enum": [ "center_geometric", "upper_limb_refracted" ] }, "required": false, "name": "sunriseConvention", "in": "query" }, { "schema": { "type": "string", "enum": [ "en", "ne", "hi" ], "description": "Language of every `name` label. No credit surcharge for any language.", "example": "en" }, "required": false, "description": "Language of every `name` label. No credit surcharge for any language.", "name": "lang", "in": "query" }, { "schema": { "type": "string", "enum": [ "latin", "devanagari" ], "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "example": "latin" }, "required": false, "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "name": "numerals", "in": "query" }, { "schema": { "type": "string", "enum": [ "choghadiya" ], "description": "`choghadiya` adds the periods to every day." }, "required": false, "description": "`choghadiya` adds the periods to every day.", "name": "include", "in": "query" } ], "responses": { "200": { "description": "One entry per day.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PanchangRange" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "The response would exceed 512 KB (`response_too_large`); narrow `include` or the range.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "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.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/calendar/convert": { "get": { "operationId": "convertDate", "tags": [ "Calendar" ], "summary": "Convert between AD and BS", "description": "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.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2050-05-12" }, "required": true, "name": "date", "in": "query" }, { "schema": { "type": "string", "enum": [ "AD", "BS" ], "description": "Calendar of `date`.", "example": "BS" }, "required": true, "description": "Calendar of `date`.", "name": "calendar", "in": "query" }, { "schema": { "type": "string", "enum": [ "nepalSambat" ], "description": "`nepalSambat` adds the Nepal Sambat date (from the lunar month and tithi at sunrise)." }, "required": false, "description": "`nepalSambat` adds the Nepal Sambat date (from the lunar month and tithi at sunrise).", "name": "include", "in": "query" }, { "schema": { "type": "number", "minimum": -90, "maximum": 90, "description": "Place for the Nepal Sambat sunrise (default Kathmandu)." }, "required": false, "description": "Place for the Nepal Sambat sunrise (default Kathmandu).", "name": "lat", "in": "query" }, { "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "required": false, "name": "lng", "in": "query" }, { "schema": { "type": "string", "enum": [ "en", "ne", "hi" ], "description": "Language of every `name` label. No credit surcharge for any language.", "example": "en" }, "required": false, "description": "Language of every `name` label. No credit surcharge for any language.", "name": "lang", "in": "query" }, { "schema": { "type": "string", "enum": [ "latin", "devanagari" ], "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "example": "latin" }, "required": false, "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "name": "numerals", "in": "query" } ], "responses": { "200": { "description": "The date in both calendars.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DateConversion" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "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.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/calendar/month": { "get": { "operationId": "getCalendarMonth", "tags": [ "Calendar" ], "summary": "BS month grid", "description": "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.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } }, { "schema": { "type": "integer", "minimum": 1900, "maximum": 2200, "example": 2083 }, "required": true, "name": "year", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 12, "example": 1 }, "required": true, "name": "month", "in": "query" }, { "schema": { "type": "string", "enum": [ "BS" ], "description": "Month grids are Bikram Sambat months." }, "required": false, "description": "Month grids are Bikram Sambat months.", "name": "calendar", "in": "query" }, { "schema": { "type": "number", "minimum": -90, "maximum": 90, "description": "Place for tithi at sunrise (default Kathmandu)." }, "required": false, "description": "Place for tithi at sunrise (default Kathmandu).", "name": "lat", "in": "query" }, { "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "required": false, "name": "lng", "in": "query" }, { "schema": { "type": "string", "enum": [ "nepal", "amanta" ] }, "required": false, "name": "tradition", "in": "query" }, { "schema": { "type": "string", "enum": [ "en", "ne", "hi" ], "description": "Language of every `name` label. No credit surcharge for any language.", "example": "en" }, "required": false, "description": "Language of every `name` label. No credit surcharge for any language.", "name": "lang", "in": "query" }, { "schema": { "type": "string", "enum": [ "latin", "devanagari" ], "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "example": "latin" }, "required": false, "description": "Digits inside labels and display strings. Default: `latin` for `en`, `devanagari` for `ne` and `hi`.", "name": "numerals", "in": "query" } ], "responses": { "200": { "description": "The month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarMonth" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "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.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/charts/svg": { "post": { "operationId": "renderChartSvg", "tags": [ "Charts" ], "summary": "Chart SVG", "description": "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.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChartSvgRequest" } } } }, "responses": { "200": { "description": "The chart.", "content": { "image/svg+xml": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ChartSvg" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`out_of_range`, `ambiguous_local_time` (resolve with `options.disambiguation`), `ambiguous_place` (with `candidates`) or `place_not_found`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "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.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/places/search": { "get": { "operationId": "searchPlaces", "tags": [ "Places" ], "summary": "Search places", "description": "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.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } }, { "schema": { "type": "string", "minLength": 1, "maxLength": 120, "example": "pokhara" }, "required": true, "name": "q", "in": "query" }, { "schema": { "type": "string", "enum": [ "en", "ne", "hi" ], "description": "Language of every `name` label. No credit surcharge for any language.", "example": "en" }, "required": false, "description": "Language of every `name` label. No credit surcharge for any language.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Default 10." }, "required": false, "description": "Default 10.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "required": false, "name": "country", "in": "query" } ], "responses": { "200": { "description": "Matches, best first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceSearch" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/timezone": { "get": { "operationId": "getTimezone", "tags": [ "Places" ], "summary": "Time zone for a coordinate", "description": "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.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } }, { "schema": { "type": "number", "minimum": -90, "maximum": 90, "example": 27.7172 }, "required": true, "name": "lat", "in": "query" }, { "schema": { "type": "number", "minimum": -180, "maximum": 180, "example": 85.324 }, "required": true, "name": "lng", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Instant for the offset (default: now)." }, "required": false, "description": "Instant for the offset (default: now).", "name": "instant", "in": "query" } ], "responses": { "200": { "description": "Zone and offset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timezone" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "No credits left (`insufficient_credits`, with `topUpUrl`) or a key or token cap reached (`credit_cap_reached`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "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.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tokens": { "post": { "operationId": "createClientToken", "tags": [ "Account" ], "summary": "Create a client token", "description": "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).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } }, "responses": { "200": { "description": "The token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientToken" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/usage": { "get": { "operationId": "getUsage", "tags": [ "Account" ], "summary": "Credit balance", "description": "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).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } } ], "responses": { "200": { "description": "Balance and lots.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "description": "Missing, invalid or revoked key (`unauthorized`), or expired client token (`token_expired`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`secret_key_in_browser`, `origin_not_allowed`, `demo_restricted` or `forbidden` (scope or key type).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited (`rate_limited`); see `Retry-After`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "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.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/meta": { "get": { "operationId": "getMeta", "tags": [ "Account" ], "summary": "Versions, ranges and attributions", "description": "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).", "parameters": [ { "name": "navapatra-version", "in": "header", "required": false, "description": "API version (`Navapatra-Version: YYYY-MM-DD`). Defaults to the key's pinned version; unknown versions fail with 400.", "schema": { "type": "string", "example": "2026-11-01" } } ], "responses": { "200": { "description": "Metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMeta" } } } }, "400": { "description": "Invalid input (`invalid_input`, with field paths in `errors`) or unknown version (`unsupported_version`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "webhooks": {} }