Developers

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

1

Create a key

Sign up and generate an API key from the dashboard. The Free plan needs no card.

Create a free API key
2

Make a call

Every request authenticates with an X-API-Key header. Nothing else is required.

step 2
$ 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"
3

Ask why

Swap in the explain endpoint to get the derivation behind any festival date.

step 3
$ 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"
4

Go deeper

Add observatory mode to see the raw astronomical facts behind the decision.

step 4
$ 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

X-API-Key on every request. Keys are per-environment; rotate from the dashboard.

Transport

HTTPS only. Plain HTTP requests are redirected, never served.

Scope

A key carries its plan. Endpoints outside your plan return 402, not 403 — the request was understood, the plan does not include it.

Rotation

Multiple active keys are supported so you can rotate without downtime.
Authentication
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

PlanQuotaKeysBurstEndpoint access
Free500 requests / day1BasicPanchang and festivals only
Starter100,000 requests / month5StandardAll documented endpoints
Pro1,000,000 requests / month20ElevatedAll, plus bulk endpoints
EnterpriseNegotiatedUnlimitedDedicatedAll, plus custom rules and locations

Exceeding a limit returns 429, not a degraded answer

We never silently reduce the quality of a response to stay inside a quota. You either get the full answer or an explicit error you can handle.

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-08
Response
Press “Send it” to issue this request for real.
CodeMeaning
200OKResponse body contains the result.
400Malformed requestA parameter failed validation. The body names the field.
401Missing or invalid keyCheck the X-API-Key header.
402Endpoint not in your planThe request was valid; your plan does not include this endpoint. Upgrade or use a documented alternative.
404No data for this inputUsually a location or date outside the supported range.
429Rate limit exceededBack off and retry. Limits reset on your plan period.
500Engine errorReport it. Traces are retained, so we can reconstruct the request.

Why 402 and not 403

A gated endpoint returns 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

REST APIAvailable81 endpoints in production, every response carrying a confidence score and engine version.OpenAPI 3.1AvailableThe machine-readable contract every client is generated from — with named operation ids, a declared security scheme and documented error responses.Postman / InsomniaAvailableImport the OpenAPI URL directly — no separate collection to fall out of date.Live playgroundAvailableReal requests against production, no account required.WebhooksAvailableHMAC-signed delivery with backoff and explicit idempotency semantics.Python SDKAvailablev0.1.0 — 79 methods across 19 namespaces, generated from the spec. Retries, distinct error types, rate-limit surface. 30 tests. Wheel builds. Not on PyPI yet, so there is no install command.TypeScript SDKAvailablev0.1.0 — the same 79 methods and namespaces as Python, enforced by a parity check in CI. ESM and CommonJS, full type declarations. 29 tests. Not on npm yet.MCP serverAvailablev0.1.0 — six tools over stdio JSON-RPC, including explain_festival so an agent can cite a rule and version rather than assert a date. 20 tests. Built on the TypeScript SDK.CLIAvailableTerminal access to panchang, festivals, muhurat and explain. Wraps the TypeScript SDK — no second HTTP implementation.React widgetsAvailableDrop-in components for panchang, festivals and muhurat, consuming the TypeScript SDK.AI tool definitionsAvailableOne shared adapter exposing six tools to OpenAI, Anthropic, Gemini and LangChain — a single registry rather than four hand-maintained copies.VS Code extensionAvailablePanchang and festival lookups without leaving the editor. Built and tested; not yet on the Marketplace.

On the roadmap

GitHub ActionBuilt · not publishedCalendar checks in CI, reporting rather than blocking on pull requests.
Go, Java and C# SDKsDeferred to v0.2Deferred to v0.2. Generating them is straightforward from the same spec; we will not ship a client we cannot compile and test, and those toolchains are not yet in our build.

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

SDK availability by language
ClientStatusInstallNotes
PythonAvailablepip install tathaastuGenerated from the OpenAPI document. 79 methods across 19 namespaces, 31 tests. Published on PyPI as tathaastu 0.1.0.
TypeScriptAvailablenpm install @tathaastu/sdkSame surface as Python, enforced in CI. ESM and CommonJS, 30 tests. Published on npm as @tathaastu/sdk 0.1.0.
CLIAvailablenpm install -g @tathaastu/cliastro / tathaastu. Wraps the TypeScript SDK — no second HTTP implementation.
MCP serverAvailablenpm install -g @tathaastu/mcpSix tools over stdio for Claude Desktop and other MCP clients.
React widgetsAvailablenpm install @tathaastu/widgetsSSR-safe drop-in components for panchang, festivals and muhurat.
VS Code extensionAvailablecode --install-extension tebibyte.tathaastu-vscodeEndpoint explorer, hover docs and snippets. Published on the VS Code Marketplace as tebibyte.tathaastu-vscode 0.1.0.
GitHub ActionBuiltCalendar checks in CI. Listing needs a public repository, which does not exist yet.
GoComing SoonGenerated from the same spec once the toolchain is in our build.
JavaComing SoonGenerated from the same spec once the toolchain is in our build.
.NETComing SoonGenerated from the same spec once the toolchain is in our build.
PHP / LaravelComing SoonScheduled after the compiled-language clients.
FlutterComing SoonScheduled after the compiled-language clients.

Why most of these say Built rather than Available

Built means the code is complete, tested and building — but the package is not yet on PyPI, npm or a marketplace, so there is no install command we could honestly print. Available appears only once a package actually resolves on its registry. We printed a 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

Importing into Postman

Postman can import an OpenAPI document straight from a URL. Point it at 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

HMAC-SHA256 over the raw request body, prefixed with sha256=. Compare in constant time, and verify before parsing.

Delivery

at-least-once

A single event may arrive more than once. Deduplicate on X-TathaAstu-Event-Id — this is a requirement, not a suggestion.

Retries

5 attempts

Failed deliveries retry with exponential backoff, then stop. The delivery is marked dead and remains visible in the event history.

Auto-disable

20 consecutive failures

A persistently failing endpoint is disabled and needs manual re-enabling, so a dead receiver does not consume delivery capacity indefinitely.

One-way only

There are no inbound webhooks. The platform sends events; it does not accept them.
Verify and deduplicate — Python
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 200

Versioning

What can change, and what cannot

URL version

The path carries the major version: /v1/. A breaking change would ship as /v2/, never as a silent change to /v1/.

Engine envelope

Responses include _engine with the festival engine version, the resolved rule pack, and the rules snapshot version.

Rule versions

Rules are versioned independently of the API. A rule correction can change a date without changing the API contract — which is exactly why the envelope reports the snapshot version.

Additive by default

New fields may appear in responses. Parse defensively; do not assume an exhaustive key set.

A date changing is not an API change

If a rule correction moves a festival, the API contract has not changed — the answer has. That is why every response carries _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.