Field Formats

• URL — base https://api.occultapi.com, then the route exactly as listed, ending in a slash.
  Good: /api/astro/tithi/, /api/astro/dasha/vimshottari/, /api/festivals/.
  Bad: /api/astro/tithi, /astro/tithi/, /api/astro/Tithi/.
• Authentication — your key in the X-API-Key header, and Content-Type: application/json on every POST.
• Method — POST with a JSON body. The few GET lookups (place search, ayanamsa value, the shalaka boards and the natural-hazard data) take their inputs, if any, as query parameters.
  Good: POST /api/astro/panchanga/ with a JSON body; GET /api/astro/geocode/?address=Jaipur.

• date_time — ISO 8601 with a UTC offset or a trailing Z, for the moment being calculated (for a birth chart, the birth moment).
  Good: "1990-08-15T10:30:00+05:30", "2026-09-01T00:30:00Z".
  Bad: "1990-08-15 10:30:00" (no offset: most endpoints read it as UTC+05:30, a few as UTC), "15/08/1990 10:30 AM".
• datetime — the same value under a different name. /api/astro/chart/, the divisional-chart routes and /api/astro/planet-positions/ require this spelling; the dasha routes accept either.
• date and time — only on /api/astro/date_time/, which takes the local clock time and the coordinates and returns an offset-aware timestamp for that date.
  Good: "1990-08-15" and "10:30:00".
• year, month, day — plain integers, where an endpoint asks for them (numerology, the calendars, the year scans).
  Good: 1990, 8, 15.

• latitude / longitude — decimal degrees. North and east are positive, south and west negative.
  Good: 26.9124, 75.7873 (Jaipur); 40.7128, -74.006 (New York).
  Bad: "26°54′N", strings, or 74.006 for New York (a missing minus moves it to China).
• timezone_as_float — the UTC offset in hours, as a number from -12 to 14, in force at that place on that date (summer time included).
  Good: 5.5 (India), -4 (New York in summer), 5.75 (Nepal).
  Bad: "+05:30", "Asia/Kolkata", "IST".
• The same offset goes by other names on some endpoints: timezone (for example /api/astro/dosha/ and /api/astro/strength/), tz (/api/astro/transit/) and time_zone (/api/astro/celestial/). Send the name the endpoint lists.

• ayanamsa (sidereal endpoints) — an ayanamsa name, case-insensitive; LAHIRI by default. /api/astro/chart/ requires it.
  Good: LAHIRI, KRISHNAMURTI, RAMAN, TRUE_CITRA.
  Bad: "kp-newcomb", "Lahiri ayanamsa". On /api/astro/chart/ an unknown name returns 400.
• On the /api/astro/western/ and /api/astro/return/ routes, ayanamsa defaults to TROPICAL; pass an ayanamsa name to get sidereal positions instead.
• An endpoint with no ayanamsa field calculates with Lahiri. /api/astro/prashna/jamakkol/ has its own lowercase list: lahiri, true_citra, krishnamurti, raman.

• keys — a JSON array of exact names from the endpoint's key table.
  Good: ["tithi", "vaara", "rahu_kaalam"] on /api/astro/panchanga/.
  Bad: "tithi,vaara" (a string), "Tithi", "rahu_kaal".
• Some keys need an extra field, listed in the key table: the phone_number key on /api/astro/numerology/ needs a phone_number value.
• An endpoint whose reference has no key table, such as /api/astro/tithi/ or /api/astro/rahu-kaal/, always runs the same calculation; you do not need to send keys.

• chart_name on /api/astro/chart/ — case-sensitive PascalCase. Send an array to get several charts in one call.
  Good: "RashiChart", ["RashiChart", "NavamsaChart", "DasamsaChart"].
  Bad: "rashi", "D9", "Navamsa".
• notation — lowercase degree (decimal degrees) or astrological (sign, degrees, minutes, seconds).
• Lunar node — rahu on the chart routes (true by default, or mean or both), node on the dasha and Jaimini routes (true by default, or mean), node_type on Human Design and Prashna (mean by default, except on /api/astro/prashna/, where it is required).
• house_system on /api/astro/western/house-cusps/ — lowercase, underscore-separated.
  Good: placidus (default), whole_sign, equal, koch, porphyry, regiomontanus, campanus, topocentric.
  Bad: "whole-sign", "W".
• rashi on the rashifal routes — English sign names.
  Good: aries, taurus, … pisces.
• system on /api/astro/numerology/ — chaldean (default), pythagorean, chinese or vedic. Each has its own set of keys.
• spread on /api/astro/tarot/spread/ — three_card (default), one_card, celtic_cross, horseshoe, relationship or situation.
• sequence on /api/astro/numerology/angel/ — the number seen, as a string.
  Good: "1111", "444".
  Bad: 1111 (a number).
• levels on the dasha timelines — 1 to 4, default 3: 1 is mahadashas only, 2 adds antardashas, 3 pratyantardashas.

Every route ends in a slash. Without it the server answers 301 with a redirect to the slash URL, and most HTTP clients follow that redirect as a GET without your body, so the call fails. Copy the route's spelling exactly: some use hyphens (/api/astro/rahu-kaal/), some underscores (/api/astro/monthly_panchang/), and a few live outside /api/astro/ (/api/festivals/, /api/vrat-upavas/).

• /docs/agent-gotchas — Domain Gotchas
• /docs/agent-tasks — Agent Task Cheatsheet