Versioning

The API uses dated versions such as 2026-11-01. A version fixes the request and response schema and the computation conventions. Once you are on a version, a newer release cannot change what your integration receives.

Which version a request uses

1. The Navapatra-Version request header, if you send one.
2. Otherwise the version your key is pinned to. You set and change pins in the dashboard.
3. A key without a pin gets the newest version.

A client token is fixed to the version that served the POST /v1/tokens call that created it (that call’s header, or the issuing key’s pin).

Every response says which version served it, in the Navapatra-Version response header and in meta.apiVersion:

Navapatra-Version: 2026-11-01

An unknown version returns 400 unsupported_version. GET /v1/meta lists the versions that exist:

{ "apiVersion": "2026-11-01", "apiVersions": ["2026-11-01"], "...": "..." }

Sending the header on every request is good practice: your code states the version it was written against, and a change of pin in the dashboard cannot surprise it.

Upgrading

1. Read the changelog entry for the new version.
2. Send Navapatra-Version: <new version> from a test environment and compare responses.
3. Deploy with the new header, or change the key’s pin in the dashboard.

You can move one key at a time, so a gradual rollout needs nothing more than two keys.

Data updates are not pinned

Some data changes because the world does, not because the API does:

• tz database releases, when a country changes its clocks or historians correct an old offset;
• Bikram Sambat table updates, when the Samiti publishes a new year’s calendar;
• Samiti tithi overrides, the official corrections to computed tithis;
• holiday data, once available.

These are corrections, so they apply to every API version as soon as they ship. Each one is announced in the changelog, and each has its own version in meta (tzdbVersion, bsTableVersion, overridesVersion), so you can tell exactly which data produced a stored response.

The same holds for engine fixes that bring results within the published accuracy tolerances; they are announced with the new engineVersion.

What counts as a breaking change

A new dated version is released for any change that could break a correct integration:

• removing or renaming a field, parameter or endpoint;
• changing a field’s type, format or meaning;
• changing a default convention (for example the default ayanamsha or sunrise convention);
• adding a required parameter;
• changing an error code or status for the same situation.

These are not breaking and can ship to existing versions:

• new endpoints, new optional parameters and new response fields;
• new values in include or in other option lists;
• new error codes for situations that previously succeeded incorrectly;
• data updates as described above;
• changes to title and detail text.

Write your client to ignore unknown fields. Breaking versions get at least 12 months of notice; see the deprecation policy.

SDKs

SDKs follow semantic versioning, separately from API versions. The two latest major versions are supported.