vedicAPI

Find a muhurta

Ranked windows for 23 purposes, each with its reasons. The birth fields are the person's. The event happens at the birth place unless you send place.

POST/muhurta/find
Counts as 5 API calls

Heavy call: it does more work, so it counts as 5 API calls on your plan. 10 API calls for a range over 90 days. How API calls are counted

Authentication

Send your API key as a Bearer token. Keys start with sk_live_. Keep keys on your server. More on keys

Authorization: Bearer $VEDICAPI_KEY

Headers

  • Authorization
    Requiredrequired
    DescriptionBearer followed by your API key.
  • X-End-User
    Requiredoptional
    DescriptionYour own id for the person the call is for, up to 64 characters. Shows in Request logs. End-user tags
  • Content-Type
    Requiredrequired
    Descriptionapplication/json

Body parameters

  • datetimestringrequired

    Local birth time, ISO 8601 with no offset: 1990-10-21T00:45. Seconds are optional.

    Example 1990-10-21T00:45
  • latnumberrequired

    Latitude of the birth place, -90 to 90.

    Example 28.6139
  • lonnumberrequired

    Longitude of the birth place, -180 to 180.

    Example 77.209
  • tzstringrequired

    IANA zone (Asia/Kolkata) or an offset (+05:30). Past rule changes and daylight saving are handled.

    Example Asia/Kolkata
  • langstring

    Language of names and labels: en, hi, mr, bn, te, gu, ta, pa, kn, ml, en_IN (Hinglish) or de. Default en.

    Example en
  • ayanamsastring

    Ayanamsa. Lahiri (chitrapaksha) is the only one today and the default. Any other value gets 400 unsupported_ayanamsa.

    One of lahiri
  • purposestringrequired

    A key from GET /muhurta/purposes.

    Example griha_pravesh
  • fromstringrequired

    Start date, YYYY-MM-DD.

    Example 2026-12-01
  • tostringrequired

    End date, up to 180 days from the start.

    Example 2026-12-31
  • topinteger

    How many windows, 1 to 20. Default 5.

    Example 5
  • placeobject

    Where the event happens, if not at the birth place: lat, lon and tz.

    • latnumberrequired

      Latitude.

    • lonnumberrequired

      Longitude.

    • tzstringrequired

      IANA zone (Asia/Kolkata) or an offset (+05:30). Past rule changes and daylight saving are handled.

Birth fields are the same on every chart endpoint. Times are local to the place; pass the zone in tz and we handle past rule changes and daylight saving.

Response

JSON with 200 OK. Every answer carries units (how many API calls this request counts as) and request_id, and the same values in the X-Units and X-Request-Id headers. The example below is the real answer to the request shown.

  • birthobjectThe birth you sent, with the UTC offset used at that moment.
  • days_scannednumberDays checked.
  • days_usablenumberDays with at least one good time.
  • fromstringStart of the range.
  • langstringLanguage of names and labels.
  • purposestringThe purpose you asked for.
  • text_langstringLanguage of the longer text. English for now.
  • tostringEnd of the range.
  • windowsarrayRanked time windows, best first.
  • unitsnumberHow many API calls this request counts as: 1, or 5 for a heavy call; 0 for errors and free endpoints.
  • request_idstringId of this call. Search it in Request logs. Also sent as the X-Request-Id header.

Errors

  • 400
    Codesinvalid_jsoninvalid_datetimeinvalid_latinvalid_loninvalid_tzunsupported_ayanamsainvalid_frominvalid_toinvalid_rangerange_too_longinvalid_purposeunsupported_langinvalid_end_user
    WhenA field is missing or invalid. The message names the field.
  • 401
    Codesmissing_keyunknown_key
    WhenNo key, or the key is wrong, revoked or past its rotation window.
  • 403
    Codesnot_allowed
    WhenThe key has an allow list and this call came from another IP or domain.
  • 404
    Codesno_such_endpoint
    WhenWrong path or method.
  • 429
    Codesrate_limitedmonthly_limitspend_cap
    WhenOver a limit. Wait the Retry-After seconds before trying again.
  • 503
    Codesbusy
    WhenLong searches are busy. Wait the Retry-After seconds and retry. Nothing is counted.
  • 502
    Codesengine_unavailableengine_error
    WhenOur engine could not answer. Retry with backoff.

Errors are never charged. Every error has one shape: { "error": "<message>", "code": "<code>", "request_id": "req_..." }. Errors and limits