Формати полів

• URL — база https://api.occultapi.com, далі маршрут точно як у переліку, зі слешем у кінці.
  Правильно: /api/astro/tithi/, /api/astro/dasha/vimshottari/, /api/festivals/.
  Неправильно: /api/astro/tithi, /astro/tithi/, /api/astro/Tithi/.
• Автентифікація — ключ у заголовку X-API-Key, а в кожному POST — ще й Content-Type: application/json.
• Метод — POST із JSON-тілом. Кілька GET-ендпоінтів (пошук місця, значення аянамші, дошки шалака й дані про природні катастрофи) приймають вхідні дані, якщо вони взагалі є, як параметри запиту.
  Правильно: POST /api/astro/panchanga/ із JSON-тілом; GET /api/astro/geocode/?address=Jaipur.

• date_time — ISO 8601 зі зміщенням від UTC або із Z у кінці; це момент, для якого робиться розрахунок (для натальної карти — момент народження).
  Правильно: "1990-08-15T10:30:00+05:30", "2026-09-01T00:30:00Z".
  Неправильно: "1990-08-15 10:30:00" (без зміщення більшість ендпоінтів читає час як UTC+05:30, деякі — як UTC), "15/08/1990 10:30 AM".
• datetime — те саме значення, лише під іншою назвою. Саме так його треба писати для /api/astro/chart/, маршрутів дробових карт і /api/astro/planet-positions/; маршрути даш приймають обидва варіанти.
• date і time — лише в /api/astro/date_time/. Він приймає місцевий час і координати й повертає часову позначку зі зміщенням, яке діяло на ту дату.
  Правильно: "1990-08-15" і "10:30:00".
• year, month, day — звичайні цілі числа, там, де ендпоінт їх просить (нумерологія, календарі, річні сканування).
  Правильно: 1990, 8, 15.

• latitude / longitude — десяткові градуси. Північ і схід — додатні, південь і захід — від’ємні.
  Правильно: 26.9124, 75.7873 (Джайпур); 40.7128, -74.006 (Нью-Йорк).
  Неправильно: "26°54′N", рядки або 74.006 для Нью-Йорка (без мінуса місто опиняється в Китаї).
• timezone_as_float — зміщення від UTC у годинах, число від -12 до 14, яке діяло в цьому місці на цю дату (з урахуванням літнього часу).
  Правильно: 5.5 (Індія), -4 (Нью-Йорк улітку), 5.75 (Непал).
  Неправильно: "+05:30", "Asia/Kolkata", "IST".
• На деяких ендпоінтах те саме зміщення називається інакше: timezone (наприклад, /api/astro/dosha/ і /api/astro/strength/), tz (/api/astro/transit/) і time_zone (/api/astro/celestial/). Надсилайте ту назву, яку вказано для ендпоінта.

• ayanamsa (сидеричні ендпоінти) — назва аянамші, регістр не важливий; за замовчуванням LAHIRI. Для /api/astro/chart/ поле обов’язкове.
  Правильно: LAHIRI, KRISHNAMURTI, RAMAN, TRUE_CITRA.
  Неправильно: "kp-newcomb", "Lahiri ayanamsa". На /api/astro/chart/ невідома назва повертає 400.
• На маршрутах /api/astro/western/ і /api/astro/return/ поле ayanamsa за замовчуванням дорівнює TROPICAL; щоб отримати сидеричні положення, передайте назву аянамші.
• Якщо в ендпоінта немає поля ayanamsa, він рахує за Лахірі. У /api/astro/prashna/jamakkol/ власний перелік, малими літерами: lahiri, true_citra, krishnamurti, raman.

• keys — JSON-масив точних назв із таблиці ключів ендпоінта.
  Правильно: ["tithi", "vaara", "rahu_kaalam"] для /api/astro/panchanga/.
  Неправильно: "tithi,vaara" (рядок), "Tithi", "rahu_kaal".
• Деяким ключам потрібне додаткове поле — воно вказане в таблиці ключів. Наприклад, ключ phone_number на /api/astro/numerology/ потребує значення phone_number.
• Якщо на сторінці ендпоінта немає таблиці ключів, як-от у /api/astro/tithi/ чи /api/astro/rahu-kaal/, він завжди виконує той самий розрахунок, і keys надсилати не треба.

• chart_name на /api/astro/chart/ — PascalCase, регістр має значення. Передайте масив, щоб отримати кілька карт за один виклик.
  Правильно: "RashiChart", ["RashiChart", "NavamsaChart", "DasamsaChart"].
  Неправильно: "rashi", "D9", "Navamsa".
• notation — малими літерами: degree (десяткові градуси) або astrological (знак, градуси, хвилини, секунди).
• Місячний вузол — rahu на маршрутах карт (за замовчуванням true, або mean чи both), node на маршрутах даш і Джайміні (за замовчуванням true, або mean), node_type у Human Design і Прашні (за замовчуванням mean, крім /api/astro/prashna/, де поле обов’язкове).
• house_system на /api/astro/western/house-cusps/ — малими літерами, слова через підкреслення.
  Правильно: placidus (за замовчуванням), whole_sign, equal, koch, porphyry, regiomontanus, campanus, topocentric.
  Неправильно: "whole-sign", "W".
• rashi на маршрутах рашифалу — англійські назви знаків.
  Правильно: aries, taurus, … pisces.
• system на /api/astro/numerology/ — chaldean (за замовчуванням), pythagorean, chinese або vedic. У кожної системи свій набір ключів.
• spread на /api/astro/tarot/spread/ — three_card (за замовчуванням), one_card, celtic_cross, horseshoe, relationship або situation.
• sequence на /api/astro/numerology/angel/ — число, яке людина бачить, у вигляді рядка.
  Правильно: "1111", "444".
  Неправильно: 1111 (число).
• levels для часових шкал даш — від 1 до 4, за замовчуванням 3: 1 — лише махадаші, 2 — ще й антардаші, 3 — ще й пратьянтардаші.

Кожен маршрут закінчується слешем. Без нього сервер відповідає 301 і перенаправляє на адресу зі слешем, а більшість HTTP-клієнтів виконує цей редирект як GET без тіла запиту — і виклик не вдається. Копіюйте маршрут точно: в одних дефіси (/api/astro/rahu-kaal/), в інших підкреслення (/api/astro/monthly_panchang/), а кілька лежать поза /api/astro/ (/api/festivals/, /api/vrat-upavas/).

• /docs/agent-gotchas — Підводні камені
• /docs/agent-tasks — Шпаргалка для агентів