96Astro API

Documentation

Observance reminders

Get a signed webhook before Ekadashi, Purnima, Amavasya, Pradosh, Sankashti, a festival, a Sankranti, an eclipse or each day's Rahu Kaal, at your place and lead time.

An observance subscription asks the API to remind you of one kind of observance at one place. The API works out when each one falls, and sends an observance.upcoming webhook to the endpoint you choose, the lead time you ask for before it. You do not poll and you do not keep a calendar: you receive an event when a reminder is due.

Subscriptions need a secret key. Creating, changing and deleting them costs no credits, and each event delivered is free too (see Cost and limits). You can also manage them in the dashboard under Webhooks, Observance reminders.

Before you start

  1. Create a webhook endpoint in the dashboard (or POST it to the portal) and tick the Observance reminder event, observance.upcoming. A subscription names one endpoint, and the endpoint must be in the same environment as your key: a test key uses sandbox endpoints, a live key uses live ones.
  2. Know the place: latitude, longitude and an IANA time zone (or a fixed utc_offset). Latitude must be within 66° of the equator, because observances are judged from sunrise.

Subscribe

POST /v1/subscriptions/observances
Authorization: Bearer sk_live_...

{
  "kind": "ekadashi",
  "endpoint_id": "6d4a1f9e-3b0c-4c8e-9d55-2f6a8b7e1c40",
  "lead_minutes": 1440,
  "latitude": 28.6139,
  "longitude": 77.209,
  "timezone": "Asia/Kolkata",
  "label": "Delhi temple"
}
FieldMeaning
kindWhat to be reminded of. See the table below.
endpoint_idOne of your webhook endpoints, in the key's environment, subscribed to observance.upcoming.
latitude, longitudeThe place, within 66° of the equator.
timezone or utc_offsetSend exactly one. Times in the event are in this zone.
lead_minutesSend the event this many minutes before the observance: 0 to 43,200 (30 days). One hour is 60, one day 1,440. Default 0.
festivalsFor kind: "festival" only: keep festivals whose name contains one of these words (case-insensitive, up to 20). Empty means every festival.
labelYour own note, up to 120 characters.
kindWhen it falls (occurs_at)Calculated with
ekadashiThe start of the Smarta observance day (local midnight). The event names it (Utpanna Ekadashi...) and carries the tithi start and end and the parana window.ekadashi-calendar
purnima, amavasya, pradosh, sankashtiThe moment the day is judged: sunrise, or the evening window for Pradosh.vrat-calendar
festivalSunrise of the festival's day, or local midnight when the day has no sunrise value. One event per festival, so a day with two festivals sends two.festival-calendar
sankrantiThe exact moment the Sun enters a sign, with the Punya Kaal and the Maha Punya Kaal.sankranti-detail
eclipseThe moment of greatest eclipse. The event says whether it is visible at your place.eclipses
rahu_kaal_dailyThe start of each day's Rahu Kaal. Lead time up to 720 minutes.daily-panchang

The reminders agree with what those capabilities return for the same place, because they are calculated with them.

The response is the subscription with its id and its next occurrences. GET /v1/subscriptions/observances lists your subscriptions (kind filters, limit up to 200), GET /v1/subscriptions/observances/{id} shows one with its next ten, and DELETE /v1/subscriptions/observances/{id} removes it with the occurrences not yet sent.

PATCH /v1/subscriptions/observances/{id}

{ "lead_minutes": 60, "active": true }

PATCH changes label, lead_minutes, endpoint_id, festivals and active (false pauses it). The kind and the place cannot change: create a new subscription instead. When you change the lead time, occurrences not yet sent move with it, and one whose new send time has already passed is skipped rather than sent late.

The event

The endpoint receives the same signed envelope as every webhook (Astro-Signature, retries, the delivery log: see jobs and webhooks), with type set to observance.upcoming:

{
  "id": "evt_5e1c0d...",
  "type": "observance.upcoming",
  "created": 1796000000,
  "environment": "live",
  "project_id": null,
  "data": {
    "subscription_id": "0a8b2c6e-...",
    "label": "Delhi temple",
    "kind": "ekadashi",
    "title": "Utpanna Ekadashi",
    "occurs_at": "2026-12-04T00:00:00+05:30",
    "lead_minutes": 1440,
    "place": { "latitude": 28.6139, "longitude": 77.209, "timezone": "Asia/Kolkata" },
    "observance": {
      "date": "2026-12-04",
      "paksha": "Krishna",
      "lunar_month": "Margashirsha",
      "tithi_start": "2026-12-03T10:00:00+05:30",
      "tithi_end": "2026-12-04T09:00:00+05:30",
      "parana": { "date": "2026-12-05", "start": "2026-12-05T07:00:00+05:30", "end": "2026-12-05T09:00:00+05:30" },
      "at_means": "start of the observance day (local midnight)"
    }
  }
}

data.observance holds the details of that kind (a Sankranti has the sign and the Punya Kaal, an eclipse its type and visibility, Rahu Kaal its start and end). at_means says what occurs_at stands for. Use the event id (the Astro-Webhook-Id header) to ignore a repeat: a delivery that your server answered late may arrive twice.

When events are sent

The worker sends each occurrence once, at its occurs_at minus lead_minutes, to within about a minute. It keeps about 13 months of occurrences ahead (3 days for rahu_kaal_daily) and tops the list up, so a subscription keeps working without any action. Each occurrence is sent at most once even if two workers run at the same moment.

Some occurrences are never sent, and GET /v1/subscriptions/observances/{id} counts them as skipped:

  • An occurrence whose send time had already passed when it was found, for example when you subscribe a day before an Ekadashi with a two-day lead. A reminder is not sent late for something already close.
  • An occurrence the worker could not reach for more than 30 minutes after it happened (for example during an outage).
  • An occurrence whose endpoint was deleted, disabled or no longer subscribed to observance.upcoming, or whose live endpoint's plan no longer includes live webhooks.

Pausing a subscription (active: false) sends nothing until you resume it.

Cost and limits

Delivered events are free. Like the astrology events of a saved chart, a reminder costs no credits: the calculation behind it is bounded instead by these limits, per organization and environment:

  • up to 50 subscriptions;
  • up to 3 rahu_kaal_daily subscriptions, because each one asks the engine every day;
  • lead_minutes up to 30 days (12 hours for rahu_kaal_daily).

Live subscriptions need a plan that includes live webhooks (sandbox works on every plan). Delivery follows the webhook endpoint's rules: a live endpoint that fails for three days is disabled, and its pending deliveries close. If you need the same data on demand instead, the today-feed capability (POST /v1/panchang/today-feed) returns a day's panchang, festivals, events and the next observances in one call for 5 credits.

Errors

StatusCodeWhen
404not_foundThe endpoint_id is not an endpoint of this environment, or the subscription does not exist.
422invalid_requestAn unknown kind, a place outside 66°, both or neither of timezone and utc_offset, a lead_minutes out of range, or an endpoint that is not subscribed to observance.upcoming. The error names the field.
403plan_requiredA live subscription on a plan without live webhooks.
403publishable_key_not_allowedA publishable key. Use a secret key from your server.
409limit_reachedYou are at a limit above.

Was this page helpful?

On this page

Send us feedback

What is it about?