Formato de los campos

• URL: la base https://api.occultapi.com y después la ruta tal como aparece en la referencia, con barra al final.
  Bien: /api/astro/tithi/, /api/astro/dasha/vimshottari/, /api/festivals/.
  Mal: /api/astro/tithi, /astro/tithi/, /api/astro/Tithi/.
• Autenticación: tu clave en la cabecera X-API-Key, y Content-Type: application/json en todos los POST.
• Método: POST con cuerpo JSON. Las pocas consultas GET (búsqueda de lugares, valor del ayanamsa, los tableros shalaka y los datos de riesgos naturales) reciben sus datos, si los necesitan, como parámetros de consulta.
  Bien: POST /api/astro/panchanga/ con cuerpo JSON; GET /api/astro/geocode/?address=Jaipur.

• date_time: ISO 8601 con diferencia UTC o con Z al final, para el momento que se calcula (en una carta natal, el del nacimiento).
  Bien: "1990-08-15T10:30:00+05:30", "2026-09-01T00:30:00Z".
  Mal: "1990-08-15 10:30:00" (sin diferencia horaria, casi todos los endpoints lo toman como UTC+05:30 y unos pocos como UTC), "15/08/1990 10:30 AM".
• datetime: el mismo valor con otro nombre. /api/astro/chart/, las rutas de cartas divisionales y /api/astro/planet-positions/ exigen esta forma; las rutas de dasha aceptan las dos.
• date y time: solo en /api/astro/date_time/, que recibe la hora local y las coordenadas y devuelve una marca de tiempo con la diferencia horaria de esa fecha.
  Bien: "1990-08-15" y "10:30:00".
• year, month, day: números enteros, en los endpoints que los piden (numerología, calendarios, búsquedas por año).
  Bien: 1990, 8, 15.

• latitude / longitude: grados decimales. Norte y este son positivos; sur y oeste, negativos.
  Bien: 26.9124, 75.7873 (Jaipur); 40.7128, -74.006 (Nueva York).
  Mal: "26°54′N", cadenas de texto, o 74.006 para Nueva York (sin el menos, acaba en China).
• timezone_as_float: la diferencia con UTC en horas, como número de -12 a 14, la que regía en ese lugar en esa fecha (horario de verano incluido).
  Bien: 5.5 (India), -4 (Nueva York en verano), 5.75 (Nepal).
  Mal: "+05:30", "Asia/Kolkata", "IST".
• En algunos endpoints, esa misma diferencia horaria tiene otro nombre: timezone (por ejemplo, en /api/astro/dosha/ y /api/astro/strength/), tz (/api/astro/transit/) y time_zone (/api/astro/celestial/). Usa el nombre que indique el endpoint.

• ayanamsa (endpoints siderales): el nombre de un ayanamsa, sin importar mayúsculas o minúsculas; por defecto, LAHIRI. En /api/astro/chart/ es obligatorio.
  Bien: LAHIRI, KRISHNAMURTI, RAMAN, TRUE_CITRA.
  Mal: "kp-newcomb", "Lahiri ayanamsa". En /api/astro/chart/, un nombre desconocido devuelve 400.
• En las rutas /api/astro/western/ y /api/astro/return/, ayanamsa vale TROPICAL por defecto; indica el nombre de un ayanamsa si quieres posiciones siderales.
• Un endpoint sin campo ayanamsa calcula con Lahiri. /api/astro/prashna/jamakkol/ tiene su propia lista, en minúsculas: lahiri, true_citra, krishnamurti, raman.

• keys: un array JSON con los nombres exactos que aparecen en la tabla de claves del endpoint.
  Bien: ["tithi", "vaara", "rahu_kaalam"] en /api/astro/panchanga/.
  Mal: "tithi,vaara" (una cadena), "Tithi", "rahu_kaal".
• Algunas claves necesitan un campo más, indicado en la tabla de claves: la clave phone_number de /api/astro/numerology/ necesita un valor phone_number.
• Si la referencia de un endpoint no tiene tabla de claves, como /api/astro/tithi/ o /api/astro/rahu-kaal/, el endpoint hace siempre el mismo cálculo y no hace falta enviar keys.

• chart_name en /api/astro/chart/: en PascalCase, distinguiendo mayúsculas. Envía un array para obtener varias cartas en una sola llamada.
  Bien: "RashiChart", ["RashiChart", "NavamsaChart", "DasamsaChart"].
  Mal: "rashi", "D9", "Navamsa".
• notation: en minúsculas, degree (grados decimales) o astrological (signo, grados, minutos y segundos).
• Nodo lunar: rahu en las rutas de cartas (true por defecto, o mean o both), node en las rutas de dasha y Jaimini (true por defecto, o mean) y node_type en Human Design y Prashna (mean por defecto, salvo en /api/astro/prashna/, donde es obligatorio).
• house_system en /api/astro/western/house-cusps/: en minúsculas y con guion bajo entre palabras.
  Bien: placidus (por defecto), whole_sign, equal, koch, porphyry, regiomontanus, campanus, topocentric.
  Mal: "whole-sign", "W".
• rashi en las rutas de rashifal: el nombre del signo en inglés.
  Bien: aries, taurus, … pisces.
• system en /api/astro/numerology/: chaldean (por defecto), pythagorean, chinese o vedic. Cada uno tiene sus propias claves.
• spread en /api/astro/tarot/spread/: three_card (por defecto), one_card, celtic_cross, horseshoe, relationship o situation.
• sequence en /api/astro/numerology/angel/: el número que se ha visto, como cadena.
  Bien: "1111", "444".
  Mal: 1111 (un número).
• levels en las líneas de tiempo de dasha: de 1 a 4, por defecto 3. Con 1 salen solo los mahadashas; con 2, también los antardashas; con 3, además, los pratyantardashas.

Todas las rutas terminan en barra. Sin ella, el servidor responde con un 301 que redirige a la URL con barra, y la mayoría de los clientes HTTP siguen esa redirección como un GET sin tu cuerpo, así que la llamada falla. Copia la ruta tal cual: unas llevan guiones (/api/astro/rahu-kaal/), otras guiones bajos (/api/astro/monthly_panchang/) y unas pocas no cuelgan de /api/astro/ (/api/festivals/, /api/vrat-upavas/).

• /docs/agent-gotchas — Trampas habituales
• /docs/agent-tasks — Guía rápida de tareas para agentes