Your first call takes about a minute
One header, one endpoint, no SDK required. Everything below assumes nothing beyond curl and an API key.
Quickstart
Four steps to an explained response
Create a key
Sign up and generate an API key from the dashboard. The Free plan needs no card.
Make a call
Every request authenticates with an X-API-Key header. Nothing else is required.
$ curl https://api.tathaastuapi.com/v1/panchang \
-H "X-API-Key: $TATHAASTU_API_KEY" \
-G --data-urlencode "date=2026-11-08" \
--data-urlencode "location_id=1"Ask why
Swap in the explain endpoint to get the derivation behind any festival date.
$ curl https://api.tathaastuapi.com/v1/festivals/explain \
-H "X-API-Key: $TATHAASTU_API_KEY" \
-G --data-urlencode "date=2026-11-08" \
--data-urlencode "location_id=1"Go deeper
Add observatory mode to see the raw astronomical facts behind the decision.
$ curl "https://api.tathaastuapi.com/v1/festivals?date=2026-11-08&location_id=1&observatory=true" \
-H "X-API-Key: $TATHAASTU_API_KEY"Authentication
One header, everywhere
Header
Transport
Scope
Rotation
curl https://api.tathaastuapi.com/v1/panchang \
-H "X-API-Key: $TATHAASTU_API_KEY" \
-G --data-urlencode "date=2026-11-08" \
--data-urlencode "location_id=1"
# Never put the key in a query string — it will end up
# in server logs, browser history and referrer headers.Examples
The same call, in four forms
curl https://api.tathaastuapi.com/v1/festivals/explain \
-H "X-API-Key: $TATHAASTU_API_KEY" \
-G --data-urlencode "date=2026-11-08" \
--data-urlencode "location_id=1"Rate limits
What each plan allows
| Plan | Quota | Keys | Burst | Endpoint access |
|---|---|---|---|---|
| Free | 500 requests / day | 1 | Basic | Panchang and festivals only |
| Starter | 100,000 requests / month | 5 | Standard | All documented endpoints |
| Pro | 1,000,000 requests / month | 20 | Elevated | All, plus bulk endpoints |
| Enterprise | Negotiated | Unlimited | Dedicated | All, plus custom rules and locations |
Exceeding a limit returns 429, not a degraded answer
Errors
Send a real failing request
Each case below issues an actual request from your browser and shows the actual response. Nothing here is a mocked payload — if our error shape changes, this page changes with it.
A well-formed request to a public demo endpoint.
GET /demo/panchang?date=2026-11-08Press “Send it” to issue this request for real.| Code | Meaning |
|---|---|
| 200 | OKResponse body contains the result. |
| 400 | Malformed requestA parameter failed validation. The body names the field. |
| 401 | Missing or invalid keyCheck the X-API-Key header. |
| 402 | Endpoint not in your planThe request was valid; your plan does not include this endpoint. Upgrade or use a documented alternative. |
| 404 | No data for this inputUsually a location or date outside the supported range. |
| 429 | Rate limit exceededBack off and retry. Limits reset on your plan period. |
| 500 | Engine errorReport it. Traces are retained, so we can reconstruct the request. |
Why 402 and not 403
402 because the request was valid and understood — your plan simply does not include it. 403 would imply you were forbidden, a different problem with a different fix.Developer platform
What you can use today, and what is coming
TathaAstu is becoming a full developer platform, not just a REST surface. Everything below will be generated from the same OpenAPI document. Nothing is listed as available until it actually resolves on its registry.
Available now
On the roadmap
Nothing here carries an install command, including the items marked built — those are code-complete and tested but not yet on npm or PyPI. Each will be announced in the changelog the day it resolves on its registry, and not before.
Clients, by language
| Client | Status | Install | Notes |
|---|---|---|---|
| Python | Available | pip install tathaastu | Generated from the OpenAPI document. 79 methods across 19 namespaces, 31 tests. Published on PyPI as tathaastu 0.1.0. |
| TypeScript | Available | npm install @tathaastu/sdk | Same surface as Python, enforced in CI. ESM and CommonJS, 30 tests. Published on npm as @tathaastu/sdk 0.1.0. |
| CLI | Available | npm install -g @tathaastu/cli | astro / tathaastu. Wraps the TypeScript SDK — no second HTTP implementation. |
| MCP server | Available | npm install -g @tathaastu/mcp | Six tools over stdio for Claude Desktop and other MCP clients. |
| React widgets | Available | npm install @tathaastu/widgets | SSR-safe drop-in components for panchang, festivals and muhurat. |
| VS Code extension | Available | code --install-extension tebibyte.tathaastu-vscode | Endpoint explorer, hover docs and snippets. Published on the VS Code Marketplace as tebibyte.tathaastu-vscode 0.1.0. |
| GitHub Action | Built | — | Calendar checks in CI. Listing needs a public repository, which does not exist yet. |
| Go | Coming Soon | — | Generated from the same spec once the toolchain is in our build. |
| Java | Coming Soon | — | Generated from the same spec once the toolchain is in our build. |
| .NET | Coming Soon | — | Generated from the same spec once the toolchain is in our build. |
| PHP / Laravel | Coming Soon | — | Scheduled after the compiled-language clients. |
| Flutter | Coming Soon | — | Scheduled after the compiled-language clients. |
Why most of these say Built rather than Available
pip install for a package that did not exist once; this table is the structure that stops it happening again.Tooling
Spec, reference, Postman and playground
OpenAPI 3.1
The complete machine-readable spec for all 81 endpoints.
API reference
Endpoint-by-endpoint documentation with parameters and response shapes.
Postman
Import the OpenAPI URL directly into Postman to get a working collection.
Playground
Build a request in the browser and read the response, the explanation and the code.
Importing into Postman
https://api.tathaastuapi.com/openapi.json and you get a collection covering all 81 endpoints, with parameters pre-filled from the spec.Webhooks
Events, signatures and idempotency
Signature
X-TathaAstu-Signature
sha256=. Compare in constant time, and verify before parsing.Delivery
at-least-once
X-TathaAstu-Event-Id — this is a requirement, not a suggestion.Retries
5 attempts
Auto-disable
20 consecutive failures
One-way only
import hmac, hashlib
def verify(raw_body: bytes, signature: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(
secret.encode(), raw_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
# Delivery is at-least-once — always dedupe on the event id.
seen: set[str] = set()
def handle(request):
if not verify(request.body, request.headers["X-TathaAstu-Signature"], SECRET):
return 401
event_id = request.headers["X-TathaAstu-Event-Id"]
if event_id in seen:
return 200 # already processed
seen.add(event_id)
process(request.json())
return 200Versioning
What can change, and what cannot
URL version
Engine envelope
Rule versions
Additive by default
A date changing is not an API change
_engine.rules_snapshot_version. Pin it in your logs and you can always explain why yesterday's answer differed from today's.Start with the Free plan
500 requests a day, no card required. Confidence scores and the engine envelope are included on every plan.