Formatos dos campos

• URL — a base https://api.occultapi.com e depois a rota exatamente como está listada, terminando em barra.
  Certo: /api/astro/tithi/, /api/astro/dasha/vimshottari/, /api/festivals/.
  Errado: /api/astro/tithi, /astro/tithi/, /api/astro/Tithi/.
• Autenticação — sua chave no cabeçalho X-API-Key e Content-Type: application/json em todo POST.
• Método — POST com corpo JSON. As poucas consultas GET (busca de locais, valor do ayanamsa, os tabuleiros shalaka e os dados de desastres naturais) recebem as entradas, quando têm, como parâmetros de query.
  Certo: POST /api/astro/panchanga/ com corpo JSON; GET /api/astro/geocode/?address=Jaipur.

• date_time — ISO 8601 com offset UTC ou Z no final, para o momento a ser calculado (num mapa natal, o momento do nascimento).
  Certo: "1990-08-15T10:30:00+05:30", "2026-09-01T00:30:00Z".
  Errado: "1990-08-15 10:30:00" (sem offset: a maioria dos endpoints lê como UTC+05:30, e alguns como UTC), "15/08/1990 10:30 AM".
• datetime — o mesmo valor com outro nome. /api/astro/chart/, as rotas de mapas divisionais e /api/astro/planet-positions/ exigem essa grafia; as rotas de dasha aceitam as duas.
• date e time — só em /api/astro/date_time/, que recebe a hora local do relógio e as coordenadas e devolve um timestamp com o offset correto daquela data.
  Certo: "1990-08-15" e "10:30:00".
• year, month, day — inteiros simples, nos endpoints que pedem esses campos (numerologia, calendários, varreduras anuais).
  Certo: 1990, 8, 15.

• latitude / longitude — graus decimais. Norte e leste são positivos; sul e oeste, negativos.
  Certo: 26.9124, 75.7873 (Jaipur); 40.7128, -74.006 (Nova York).
  Errado: "26°54′N", strings, ou 74.006 para Nova York (sem o sinal de menos, a cidade vai parar na China).
• timezone_as_float — o offset UTC em horas, como número de -12 a 14, vigente naquele local naquela data (horário de verão incluído).
  Certo: 5.5 (Índia), -4 (Nova York no verão), 5.75 (Nepal).
  Errado: "+05:30", "Asia/Kolkata", "IST".
• Em alguns endpoints, o mesmo offset tem outro nome: timezone (por exemplo, /api/astro/dosha/ e /api/astro/strength/), tz (/api/astro/transit/) e time_zone (/api/astro/celestial/). Envie o nome que o endpoint lista.

• ayanamsa (endpoints siderais) — o nome de um ayanamsa, sem diferenciar maiúsculas de minúsculas; o padrão é LAHIRI. Em /api/astro/chart/, é obrigatório.
  Certo: LAHIRI, KRISHNAMURTI, RAMAN, TRUE_CITRA.
  Errado: "kp-newcomb", "Lahiri ayanamsa". Em /api/astro/chart/, um nome desconhecido retorna 400.
• Nas rotas /api/astro/western/ e /api/astro/return/, o padrão de ayanamsa é TROPICAL; para receber posições siderais, passe o nome de um ayanamsa.
• Um endpoint sem o campo ayanamsa calcula com Lahiri. /api/astro/prashna/jamakkol/ tem a própria lista, em minúsculas: lahiri, true_citra, krishnamurti, raman.

• keys — um array JSON com os nomes exatos da tabela de chaves do endpoint.
  Certo: ["tithi", "vaara", "rahu_kaalam"] em /api/astro/panchanga/.
  Errado: "tithi,vaara" (uma string), "Tithi", "rahu_kaal".
• Algumas chaves precisam de um campo extra, indicado na tabela de chaves: a chave phone_number de /api/astro/numerology/ precisa de um valor em phone_number.
• Um endpoint sem tabela de chaves na referência, como /api/astro/tithi/ ou /api/astro/rahu-kaal/, sempre faz o mesmo cálculo; não é preciso enviar keys.

• chart_name em /api/astro/chart/ — PascalCase, diferenciando maiúsculas de minúsculas. Envie um array para receber vários mapas numa só chamada.
  Certo: "RashiChart", ["RashiChart", "NavamsaChart", "DasamsaChart"].
  Errado: "rashi", "D9", "Navamsa".
• notation — em minúsculas: degree (graus decimais) ou astrological (signo, graus, minutos, segundos).
• Nodo lunar — rahu nas rotas de mapas (padrão true; também mean ou both), node nas rotas de dasha e Jaimini (padrão true; também mean), node_type em Human Design e Prashna (padrão mean, exceto em /api/astro/prashna/, onde é obrigatório).
• house_system em /api/astro/western/house-cusps/ — em minúsculas, separado por sublinhado.
  Certo: placidus (padrão), whole_sign, equal, koch, porphyry, regiomontanus, campanus, topocentric.
  Errado: "whole-sign", "W".
• rashi nas rotas de rashifal — o nome do signo em inglês.
  Certo: aries, taurus, … pisces.
• system em /api/astro/numerology/ — chaldean (padrão), pythagorean, chinese ou vedic. Cada sistema tem o próprio conjunto de chaves.
• spread em /api/astro/tarot/spread/ — three_card (padrão), one_card, celtic_cross, horseshoe, relationship ou situation.
• sequence em /api/astro/numerology/angel/ — o número que a pessoa viu, como string.
  Certo: "1111", "444".
  Errado: 1111 (um número).
• levels nas linhas do tempo de dasha — de 1 a 4, padrão 3: 1 traz só os mahadashas, 2 acrescenta os antardashas e 3, os pratyantardashas.

Toda rota termina em barra. Sem ela, o servidor responde 301 e redireciona para a URL com barra — e a maioria dos clientes HTTP segue o redirecionamento como GET, sem o seu corpo, então a chamada falha. Copie a rota exatamente como está escrita: algumas usam hífen (/api/astro/rahu-kaal/), outras sublinhado (/api/astro/monthly_panchang/), e algumas ficam fora de /api/astro/ (/api/festivals/, /api/vrat-upavas/).

• /docs/agent-gotchas — Pegadinhas do domínio
• /docs/agent-tasks — Colinha de tarefas para agentes