# API do Placidus — cálculo astrológico tradicional

Motor de astrologia tradicional servido por HTTP. Você manda um instante e um lugar; recebe o mapa inteiro: posições planetárias, casas, aspectos, dignidades essenciais e acidentais, estrelas fixas calculadas na data do mapa, partes árabes, temperamento e mentalidade.

- **Base:** `https://placidus.app/api/public/v1`
- **Autenticação:** cabeçalho `X-API-Key: plc_<43 caracteres>`
- **Limite:** 120 requisições por minuto, por chave
- **Formato:** JSON na entrada e na saída. Textos de leitura vêm em português.
- **Documentação em página:** https://placidus.app/docs
- **Versão desta documentação:** `2026-09-04.2` — publicada em 2026-09-04

⚠️ **Está lendo uma cópia local?** Compare a versão acima com a de https://placidus.app/docs/llms.txt. Se a sua for mais antiga, atualize ANTES de tratar qualquer diferença como defeito do motor: o histórico no fim deste arquivo diz o que mudou entre as duas, e quase toda "divergência" relatada até hoje era documentação velha, não cálculo errado.

## Antes de começar

### Um mapa é instante + lugar + config

Não existe 'tipo' de mapa no Placidus. Natal, horária e revolução são rótulos de leitura, não estruturas diferentes: os três são o mesmo cálculo sobre um instante, um lugar e uma configuração. Por isso a API tem um endpoint de mapa, e não um por técnica. O campo `technique` só escolhe uma configuração de partida.

### Nada é guardado

A API pública calcula e esquece. Nenhuma requisição grava linha no banco — nem o input. O que chega numa chamada são data, hora e lugar de nascimento de alguém, e esse dado não pode ficar. Se você precisa persistir, persista do seu lado.

### O fuso é o nome IANA, nunca um offset

Mande 'America/Sao_Paulo', não '-03:00'. O offset depende da data: o horário de verão brasileiro anterior a 2019 muda de ano para ano, e o Placidus aplica a regra vigente na data do mapa. Um offset fixo erra por uma hora todo mapa de verão antigo — o bastante para trocar o Ascendente de signo. Se você não souber o fuso, omita o campo: ele é resolvido pela coordenada ou pela cidade.

### O cálculo é o mesmo do aplicativo

Esta API não é uma reimplementação nem uma versão reduzida. É o mesmo motor, chamado do mesmo jeito, com as mesmas tabelas de dignidade e o mesmo catálogo de estrelas que a tela do Placidus usa. Não existe divergência possível entre o que a API devolve e o que o app mostra. Vale para o DESENHO também: `/chart.png` e `/chart.svg` renderizam o mesmo componente da roda que está na tela, e não uma segunda versão dela.

### Recalcular sempre, nunca cachear

A resposta não vem de cache e não deve ser cacheada como se fosse verdade permanente: o motor evolui e correções de doutrina entram nele. Guarde o INPUT (instante, lugar, config) e recalcule quando precisar do resultado.

## Autenticação

Toda rota de cálculo exige uma chave de projeto no cabeçalho `X-API-Key`. Um `Authorization: Bearer plc_...` também é aceito, para clientes HTTP que só sabem mandar Bearer. A chave é emitida pelo administrador do Placidus, é revogável individualmente e aparece em claro uma única vez — na resposta que a criou.

- A chave identifica um PROJETO, não uma pessoa. Ela não abre mapas salvos, não lê conta de usuário e não alcança nada persistido.
- Trate-a como senha: ela vive no servidor do integrador, em variável de ambiente. Uma chave num repositório público é uma chave a revogar.
- Limite: 120 requisições por minuto, por chave. Ao estourar, a resposta é 429 com o cabeçalho `Retry-After` em segundos.
- Chave revogada responde 403 a partir da requisição seguinte, sem período de tolerância.

## Endpoints

Caminhos relativos a `https://placidus.app/api/public/v1`.

### POST /chart — Calcula um mapa completo

Requer chave de API.

O endpoint principal. Recebe um instante e um lugar; devolve o mapa inteiro — posições, casas, aspectos, dignidades, estrelas fixas, partes árabes, temperamento, mentalidade e motivação primária. Nada é gravado. A profecção NÃO sai daqui: ela precisa de um quarto dado que não é do mapa (o instante a situar), e por isso tem endpoint próprio.

**Corpo**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `datetime_local` | `string` | sim | Data e hora LOCAIS do lugar, ISO 8601: '1990-03-15T14:32:00'. Não converta para UTC — o Placidus faz isso com a regra de fuso da data. Alternativa: `jd_ut`. |
| `timezone` | `string` | não | Fuso IANA ('America/Sao_Paulo'). Opcional: sem ele, é resolvido pela cidade (`place`) ou pela coordenada. |
| `jd_ut` | `number` | não | Julian Day UT — o instante já resolvido, sem ambiguidade de fuso. Use quando estiver encadeando chamadas: ele vem em `meta.jd_ut` de toda resposta. |
| `lat` | `number` | não | Latitude decimal, −90 a 90. Obrigatória junto com `lon`, salvo se mandar `place`. |
| `lon` | `number` | não | Longitude decimal, −180 a 180. Negativa a oeste de Greenwich. |
| `place` | `string` | não | Cidade por extenso: 'Goiânia, GO', 'Kesswil, CH'. Resolve lat, lon e fuso de uma vez. Havendo homônimos, vence a de maior população — a cidade escolhida volta em `meta.place`, então dá para conferir. Para escolher você mesmo, use `GET /places`. |
| `technique` | `string` | não | Configuração de partida: 'natal' (padrão), 'horaria' (Regiomontanus, orbe apertado, Parte da Demissão) ou 'eleicao'. Acentos e apelidos em inglês são aceitos. Consulte `GET /techniques`. Técnica é rótulo: isto muda defaults, não comportamento. |
| `config` | `object` | não | Configuração explícita do cálculo — sistema de casas, orbes, tabelas de dignidade, o que ligar e desligar. Vence a `technique`. Ver a seção Configuração. |
| `sections` | `string[]` | não | Só estas seções voltam. Omitido, vem tudo. `meta` volta sempre. Recorta a RESPOSTA, não o cálculo. |
| `exclude` | `string[]` | não | Seções a remover da resposta. Útil para cortar as pesadas (`fixed_stars`). |

**Exemplo de requisição**

```bash
curl -X POST https://placidus.app/api/public/v1/chart \
  -H "X-API-Key: $PLACIDUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime_local": "1875-07-26T19:32:00",
    "place": "Kesswil, CH"
  }'
```

**Exemplo de resposta**

```json
{
  "meta": {
    "jd_ut": 2406096.2932175924,
    "datetime_utc": "1875-07-26T19:02:14Z",
    "timezone": "Europe/Zurich",
    "tz_offset_hours": 0.4961111111111111,
    "location": { "lat": 47.5983, "lon": 9.3216 },
    "house_system": "placidus",
    "sect": "nocturnal",
    "engine_version": "0.1.0"
  },
  "bodies": [
    {
      "id": "sun",
      "name": "Sol",
      "longitude": 123.31565476363885,
      "sign": "Leão",
      "sign_index": 4,
      "deg": 3, "min": 18, "sec": 56,
      "latitude": 0.00006471318014565755,
      "speed": 0.9558238152095152,
      "speed_lat": 0.00001954998409620958,
      "retrograde": false,
      "motion": {
        "direction": "direct", "direction_pt": "direto",
        "pace": "slow", "pace_pt": "lento",
        "reading_pt": "direto e lento",
        "speed": 0.9564, "mean_speed": 0.9856
      },
      "house": 7,
      "solar_orientation": "occidental",
      "dignities": {
        "domicile": true, "exaltation": false, "triplicity": false,
        "term": false, "face": false, "detriment": false, "fall": false,
        "peregrine": false,
        "triplicity_ruler": "jupiter", "term_ruler": "saturn", "face_ruler": "saturn",
        "sign_ruler": "saturn", "exaltation_ruler": null,
        "detriment_of": "sun", "fall_of": null,
        "score": 5
      },
      "accidental": {
        "score": 7,
        "factors": [
          { "name": "casa 7", "points": 4 },
          { "name": "lento", "points": -2 },
          { "name": "latitude norte aumentando", "points": 2 },
          { "name": "hayz", "points": 3 }
        ],
        "combust": false
      }
    }
    // … os outros 9 corpos
  ],
  "moon_phase": { "quadrant": 3, "humor": "phlegmatic", "humor_pt": "Fleumático" },
  "angles": [
    { "id": "asc", "name": "Ascendente", "longitude": 304.14859735082854,
      "sign": "Aquário", "sign_index": 10, "deg": 4, "min": 8, "sec": 55 }
    // … mc, ic, dsc
  ],
  "points": [
    { "id": "north_node", "name": "Nodo Norte", "longitude": 10.925703810632907,
      "sign": "Áries", "sign_index": 0, "deg": 10, "min": 55, "sec": 33, "house": 2 }
    // … south_node
  ],
  "houses": {
    "system": "placidus",
    "cusps": [304.14859735082854, 358.3127605423338 /* … 12 cúspides, em graus */]
  },
  "aspects": [
    { "from": "sun", "to": "neptune", "type": "square",
      "orb": 0.27333089374567976, "orb_deg": 0, "orb_min": 16,
      "applying": false, "sign_gated": true },
    { "from": "saturn", "to": "ic", "type": "conjunction",
      "orb": 4.73, "orb_deg": 4, "orb_min": 44,
      "applying": true, "sign_gated": true }
  ],
  "fixed_stars": {
    "mode": "closest",
    "magnitude_floor": { "value": 3, "inclusive": true, "chart_kind": "natal" },
    "magnitude_source": "swiss",
    "include_nebulae": false,
    "bypassed_floor_count": 0,
    "fundamental_list": ["ALDEBARAN", "ALGOL", "ANTARES", "ARCTURUS", "/* … 12 */"],
    "revolution_wide_orb_list": [],
    "orb_table": { "kind": "natal_by_magnitude", "nebula_deg": 1 },
    "conjunctions_found": 14,
    "discarded_by_magnitude": 9,
    "formula_version": "estrelas-yuri-4",
    "active": [
      { "name_swiss": "Regulus", "name": "Regulus", "longitude": 149.08,
        "sign": "Leão", "deg": 29, "min": 5, "sec": 12,
        "magnitude": 1.35, "magnitude_source": "swiss",
        "object_type": "star", "fundamental": true, "bypassed_floor": false,
        "planetary_nature": "Mars-Jupiter", "constellation": "Alpha Leonis",
        "conjunct_to": "asc", "conjunct_to_name": "Ascendente",
        "orb_deg": 0, "orb_min": 53, "orb_limit_deg": 2.0,
        "reading_source": "verbete_pt",
        "interpretation": {
          "key": "REGULUS", "verbete": "Regulus é a estrela do coração do Leão…",
          "significado": "…", "mitologia": "…", "encaixe_interpretativo": "…",
          "catalog_sign": "Virgem"
        },
        "won_over": [
          { "name_swiss": "Phecda", "magnitude": 2.5,
            "orb_deg": 0, "orb_min": 15, "reason": "a outra é fundamental" }
        ] }
    ],
    "searched": [ /* … */ ]
  },
  "arabic_parts": [
    { "id": "fortuna", "name": "Parte da Fortuna",
      "longitude": 21.877916825632383, "sign": "Áries",
      "deg": 21, "min": 52, "sec": 41, "house": 2,
      "formula": "asc + sol - lua", "sect": "nocturnal",
      "conjunctions": [], "description": "Indica onde se manifestam a sorte material…" }
    // … as outras 7
  ],
  "strength_ranking": [
    { "body": "moon", "name": "Lua", "score": 8, "accidental_score": 10,
      "combust": false, "house_strength": 2, "rank": 1, "lord_of_nativity": true }
    // … os demais, em ordem
  ],
  "antiscia": [
    { "body": "sun", "name": "Sol",
      "antiscion": { "longitude": 56.68434523636115, "sign": "Touro", "deg": 26, "min": 41 },
      "contra_antiscion": { "longitude": 236.68434523636114, "sign": "Escorpião", "deg": 26, "min": 41 },
      "antiscion_hits": [
        { "point": "cusp_6", "point_name": "Cúspide 6",
          "orb_deg": 1, "orb_min": 12, "orb_limit_deg": 3 }
      ],
      "contra_antiscion_hits": [] }
  ],
  "temperament": {
    "result": "Fleumático",
    "humor": "phlegmatic",
    "signature_pt": "umidade forte, frio forte",
    "points": [
      { "point": "ascendant",  "detail": "Aquário (Ar)",     "humor": "sanguine",    "active": "hot",  "passive": "wet" },
      { "point": "asc_ruler",  "detail": "Saturno",          "humor": "melancholic", "active": "cold", "passive": "dry" },
      { "point": "moon_phase", "detail": "Minguante (Água)", "humor": "phlegmatic",  "active": "cold", "passive": "wet" },
      { "point": "sun_season", "detail": "Leão — verão",     "humor": "choleric",    "active": "hot",  "passive": "dry" }
    ],
    "tally": { "active": { "hot": 2, "cold": 2 }, "passive": { "dry": 2, "wet": 2 } },
    "modulation": [
      { "source": "lord",           "detail": "Lua",                    "active": "cold", "passive": "wet" },
      { "source": "lord_sign",      "detail": "Touro (Terra)",          "active": "cold", "passive": "dry" },
      { "source": "asc_ruler_sign", "detail": "Aquário (Ar)",           "active": "hot",  "passive": "wet" },
      { "source": "sun_sign",       "detail": "Leão (Fogo)",            "active": "hot",  "passive": "dry" },
      { "source": "aspect",         "detail": "Mercúrio à Lua, 1°49'",  "active": "cold", "passive": "wet" },
      { "source": "aspect",         "detail": "Vênus à Lua, 1°55'",     "active": "cold", "passive": "wet" },
      { "source": "aspect",         "detail": "Sol ao Ascendente, 0°50'", "active": "hot", "passive": "dry" }
    ],
    "modulation_tally": { "active": { "hot": 3, "cold": 4 }, "passive": { "dry": 3, "wet": 4 } },
    "reinforcement": {
      "active":  { "quality": "cold", "for": 4, "against": 3, "reinforced": true, "reading_pt": "frio forte" },
      "passive": { "quality": "wet",  "for": 4, "against": 3, "reinforced": true, "reading_pt": "umidade forte" }
    },
    "imbalance": { "quality": null, "tied": ["cold", "wet"], "testimonies": 4, "of": 7,
                   "reading_pt": "sem excesso definido — frio e umidade empatam" },
    "resolution": { "active": { "quality": "cold", "via": "modulation", "weak": true },
                    "passive": { "quality": "wet", "via": "modulation", "weak": true } },
    "notes": [],
    "formula_version": "temperamento-yuri-4"
  },
  "mentality": {
    "result": "Júpiter associado a Vênus",
    "combination": { "kind": "pair", "planets": ["jupiter", "venus"] },
    "moon_almuten": { "planet": "venus", "name": "Vênus", "score": 5 },
    "mercury_almuten": { "planet": "jupiter", "name": "Júpiter", "score": 4 },
    "pole": {
      "side": "light", "side_pt": "Luz",
      "decided_by": "definers", "definers_total": 9,
      "counterweight": {
        "favorable": ["Mercúrio em lugar próprio", "Sol bem posto (+3)"],
        "unfavorable": ["Saturno retrógrado"],
        "neutral": ["modalidade cardinal", "significadores orientais"],
        "balance": "attenuated",
        "reading_pt": "luz confirmada — os definidores caem para o melhor, e o conjunto do mapa sustenta"
      }
    },
    "modality": { "mode": "cardinal", "text_pt": "Mente extrovertida, polêmica, engenhosa…" },
    "orientality": { "state": "oriental", "decided_by": "maioria na orientalidade", "text_pt": "Tornam a mente constante…" },
    "modifiers": [
      { "factor": "lua_nodos", "aspect": "square", "orb_deg": 2, "orb_min": 14,
        "text_pt": "Mentalidade mais sensível, artística e volúvel." }
    ],
    "formula_version": "mentalidade-yuri-4"
  },
  "primary_motivation": {
    "result": "Libra, por Vênus em Touro (domiciliado)",
    "question_pt": "Que tipo de bem eu sou capaz de realizar e desfrutar?",
    "inspiration": { "point": "ascendant", "ruled_by": "sign", "sign": "Libra",
      "text_pt": "Diferenciar os lados da situação; estabelecer alianças; equilibrar; compensar." },
    "action": { "point": "asc_ruler", "ruled_by": "planet", "planet": "venus", "name": "Vênus",
      "verbs": ["fruir", "adornar", "embelezar", "enriquecer"],
      "sign": "Touro", "mode_pt": "Enriquecer; aumentar o valor das coisas; embelezar." },
    "final_disposition": { "point": "dispositor", "planet": "venus", "chain_stopped": true,
      "reason": "ruler_in_domicile", "text_pt": "Motivação exclusivamente venusina." },
    "special_cases": [ { "kind": "ruler_in_domicile", "text_pt": "…" } ],
    "livelihood_and_fulfilment": { "match": true, "text_pt": "…" },
    "base_exercise": { "emitted": false, "reason_pt": "…", "criterion_pt": "…" },
    "formula_version": "motivacao-yuri-2"
  }
}
```

### POST /advance — O mesmo mapa em outro instante

Requer chave de API.

Desloca o instante do mapa e recalcula, mantendo lugar e configuração. O deslocamento é ACUMULADO a partir do instante-base, não encadeado: cada chamada reconstrói o instante do zero, então avançar +1 mês e depois −1 mês devolve exatamente o ponto de partida, sem deriva de ponto flutuante nem perda do dia 31. Passando `jd_ut` (que vem em `meta.jd_ut`), o instante-base não precisa ser resolvido de novo.

**Corpo**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `datetime_local` | `string` | sim | Data e hora LOCAIS do lugar, ISO 8601: '1990-03-15T14:32:00'. Não converta para UTC — o Placidus faz isso com a regra de fuso da data. Alternativa: `jd_ut`. |
| `timezone` | `string` | não | Fuso IANA ('America/Sao_Paulo'). Opcional: sem ele, é resolvido pela cidade (`place`) ou pela coordenada. |
| `jd_ut` | `number` | não | Julian Day UT — o instante já resolvido, sem ambiguidade de fuso. Use quando estiver encadeando chamadas: ele vem em `meta.jd_ut` de toda resposta. |
| `lat` | `number` | não | Latitude decimal, −90 a 90. Obrigatória junto com `lon`, salvo se mandar `place`. |
| `lon` | `number` | não | Longitude decimal, −180 a 180. Negativa a oeste de Greenwich. |
| `place` | `string` | não | Cidade por extenso: 'Goiânia, GO', 'Kesswil, CH'. Resolve lat, lon e fuso de uma vez. Havendo homônimos, vence a de maior população — a cidade escolhida volta em `meta.place`, então dá para conferir. Para escolher você mesmo, use `GET /places`. |
| `technique` | `string` | não | Configuração de partida: 'natal' (padrão), 'horaria' (Regiomontanus, orbe apertado, Parte da Demissão) ou 'eleicao'. Acentos e apelidos em inglês são aceitos. Consulte `GET /techniques`. Técnica é rótulo: isto muda defaults, não comportamento. |
| `config` | `object` | não | Configuração explícita do cálculo — sistema de casas, orbes, tabelas de dignidade, o que ligar e desligar. Vence a `technique`. Ver a seção Configuração. |
| `sections` | `string[]` | não | Só estas seções voltam. Omitido, vem tudo. `meta` volta sempre. Recorta a RESPOSTA, não o cálculo. |
| `exclude` | `string[]` | não | Seções a remover da resposta. Útil para cortar as pesadas (`fixed_stars`). |
| `offsets` | `object` | não | Deslocamento acumulado por unidade: { "year": 1, "day": -3 }. Unidades: second, minute, hour, day, week, month, year. |
| `unit` | `string` | não | Passo único — unidade. Padrão 'day'. |
| `amount` | `number` | não | Passo único — quantidade; negativa retrocede. |

**Exemplo de requisição**

```bash
curl -X POST https://placidus.app/api/public/v1/advance \
  -H "X-API-Key: $PLACIDUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jd_ut": 2406096.2932175924,
    "lat": 47.5983,
    "lon": 9.3216,
    "offsets": { "year": 30 },
    "sections": ["bodies", "angles"]
  }'
```

**Exemplo de resposta**

```json
{
  "base": { "jd_ut": 2406096.2932175924 },
  "jd_ut": 2417056.2932175924,
  "datetime_utc": "1905-07-26T19:02:14Z",
  "offsets": { "year": 30 },
  "result": {
    "meta": { "jd_ut": 2417056.2932175924, "sect": "nocturnal", "…": "…" },
    "bodies": [ /* … */ ],
    "angles": [ /* … */ ]
  }
}
```

### POST /revolution — Revolução solar ou lunar

Requer chave de API.

Encontra o instante em que o Sol (ou a Lua) volta à longitude que tinha no mapa dado, e calcula o mapa desse instante. Escolha o alvo por `year` (a revolução daquele ano) ou por `from_jd` + `direction` (a próxima ou a anterior a um ponto). A resposta traz o mapa da revolução em `result`, os aspectos cruzados com o natal em `cross_aspects` e, em `arabic_parts_arc`, as **partes árabes do natal transportadas por arco** — `parte − Asc_natal + Asc_da_revolução`. ⚠️ Elas **não** são as partes de `result.arabic_parts`, que são recalculadas com o Ascendente e os planetas da revolução: são duas camadas diferentes, e **as duas se usam**. Cada parte diz qual é em `method`.

**Corpo**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `datetime_local` | `string` | sim | Data e hora LOCAIS do lugar, ISO 8601: '1990-03-15T14:32:00'. Não converta para UTC — o Placidus faz isso com a regra de fuso da data. Alternativa: `jd_ut`. |
| `timezone` | `string` | não | Fuso IANA ('America/Sao_Paulo'). Opcional: sem ele, é resolvido pela cidade (`place`) ou pela coordenada. |
| `jd_ut` | `number` | não | Julian Day UT — o instante já resolvido, sem ambiguidade de fuso. Use quando estiver encadeando chamadas: ele vem em `meta.jd_ut` de toda resposta. |
| `lat` | `number` | não | Latitude decimal, −90 a 90. Obrigatória junto com `lon`, salvo se mandar `place`. |
| `lon` | `number` | não | Longitude decimal, −180 a 180. Negativa a oeste de Greenwich. |
| `place` | `string` | não | Cidade por extenso: 'Goiânia, GO', 'Kesswil, CH'. Resolve lat, lon e fuso de uma vez. Havendo homônimos, vence a de maior população — a cidade escolhida volta em `meta.place`, então dá para conferir. Para escolher você mesmo, use `GET /places`. |
| `technique` | `string` | não | Configuração de partida: 'natal' (padrão), 'horaria' (Regiomontanus, orbe apertado, Parte da Demissão) ou 'eleicao'. Acentos e apelidos em inglês são aceitos. Consulte `GET /techniques`. Técnica é rótulo: isto muda defaults, não comportamento. |
| `config` | `object` | não | Configuração explícita do cálculo — sistema de casas, orbes, tabelas de dignidade, o que ligar e desligar. Vence a `technique`. Ver a seção Configuração. |
| `sections` | `string[]` | não | Só estas seções voltam. Omitido, vem tudo. `meta` volta sempre. Recorta a RESPOSTA, não o cálculo. |
| `exclude` | `string[]` | não | Seções a remover da resposta. Útil para cortar as pesadas (`fixed_stars`). |
| `body` | `'sun' | 'moon'` | não | Corpo que retorna. Padrão 'sun'. |
| `year` | `number` | não | Ano da revolução procurada. |
| `from_jd` | `number` | não | Procura a partir deste Julian Day. |
| `direction` | `'next' | 'prev'` | não | Sentido da busca com `from_jd`. Padrão 'next'. |

**Exemplo de requisição**

```bash
curl -X POST https://placidus.app/api/public/v1/revolution \
  -H "X-API-Key: $PLACIDUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime_local": "1875-07-26T19:32:00",
    "place": "Kesswil, CH",
    "body": "sun",
    "year": 1913
  }'
```

**Exemplo de resposta**

```json
{
  "jd_ut": 2419940.29,
  "datetime_utc": "1913-07-27T…Z",
  "body": "sun",
  "year": 1913,
  "target_longitude": 123.31565476363885,
  "result": { "meta": { "…": "…" }, "bodies": [ /* … */ ],
              "arabic_parts": [ { "id": "fortuna", "method": "recalculated", "…": "…" } ] },
  "cross_aspects": [ /* … */ ],
  "arabic_parts_arc": [
    { "id": "fortuna", "name": "Parte da Fortuna",
      "longitude": 188.55, "sign": "Libra", "house": 7,
      "natal_longitude": 103.57, "arc_deg": 84.97,
      "formula": "parte_natal − Asc_natal + Asc_do_mapa",
      "method": "arc_transported" }
  ]
}
```

### POST /profection — Profecção anual, mensal e diária

Requer chave de API.

Onde um instante cai na profecção de um mapa: a casa profeccionada, o senhor e a janela exata de cada nível. Três coisas divergem do padrão helenístico de mercado, e são deliberadas: as casas são as **do mapa** (Plácido por padrão), nunca signo inteiro; o senhor é o regente do signo **na cúspide** (a 29° de Leão, o senhor é o Sol, mesmo que o resto da casa seja Virgem); e a virada do ano é o **retorno solar exato**, com hora — não o aniversário civil, e a idade se conta do mesmo jeito. ⚠️ O nível ANUAL é régua fechada. O MENSAL e o DIÁRIO seguem o padrão helenístico, **validado pelo autor da régua em 19/08/2026** — não são técnica do professor dele: servem para afinar a data dentro de um período que a análise maior já apontou, e não decidem sozinhas. É o que diz o `weight` de cada nível (`primary` no ano, `refinement` nos outros dois). Não trate os três com o mesmo peso, e não hierarquize os senhores entre si.

**Corpo**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `datetime_local` | `string` | sim | Data e hora LOCAIS do lugar, ISO 8601: '1990-03-15T14:32:00'. Não converta para UTC — o Placidus faz isso com a regra de fuso da data. Alternativa: `jd_ut`. |
| `timezone` | `string` | não | Fuso IANA ('America/Sao_Paulo'). Opcional: sem ele, é resolvido pela cidade (`place`) ou pela coordenada. |
| `jd_ut` | `number` | não | Julian Day UT — o instante já resolvido, sem ambiguidade de fuso. Use quando estiver encadeando chamadas: ele vem em `meta.jd_ut` de toda resposta. |
| `lat` | `number` | não | Latitude decimal, −90 a 90. Obrigatória junto com `lon`, salvo se mandar `place`. |
| `lon` | `number` | não | Longitude decimal, −180 a 180. Negativa a oeste de Greenwich. |
| `place` | `string` | não | Cidade por extenso: 'Goiânia, GO', 'Kesswil, CH'. Resolve lat, lon e fuso de uma vez. Havendo homônimos, vence a de maior população — a cidade escolhida volta em `meta.place`, então dá para conferir. Para escolher você mesmo, use `GET /places`. |
| `technique` | `string` | não | Configuração de partida: 'natal' (padrão), 'horaria' (Regiomontanus, orbe apertado, Parte da Demissão) ou 'eleicao'. Acentos e apelidos em inglês são aceitos. Consulte `GET /techniques`. Técnica é rótulo: isto muda defaults, não comportamento. |
| `config` | `object` | não | Configuração explícita do cálculo — sistema de casas, orbes, tabelas de dignidade, o que ligar e desligar. Vence a `technique`. Ver a seção Configuração. |
| `sections` | `string[]` | não | Só estas seções voltam. Omitido, vem tudo. `meta` volta sempre. Recorta a RESPOSTA, não o cálculo. |
| `exclude` | `string[]` | não | Seções a remover da resposta. Útil para cortar as pesadas (`fixed_stars`). |
| `target_datetime` | `string` | não | Instante a situar, ISO local. Omitido, usa agora. |
| `target_timezone` | `string` | não | Fuso IANA do alvo. Omitido, herda o do mapa. |
| `target_jd` | `number` | não | Julian Day UT do alvo (alternativa ao datetime). |
| `levels` | `string[]` | não | Níveis a devolver: year, month, day. Padrão: os três. |
| `timeline` | `boolean` | não | Devolve também a volta de 12 anos. Padrão false. |

**Exemplo de requisição**

```bash
curl -X POST https://placidus.app/api/public/v1/profection \
  -H "X-API-Key: $PLACIDUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime_local": "1996-08-28T13:45:00",
    "place": "Salvador, BA",
    "target_datetime": "2026-08-06T12:00:00"
  }'
```

**Exemplo de resposta**

```json
{
  "age": 29,
  "month_index": 11,
  "day_index": 3,
  "house_system": "placidus",
  "year": {
    "house": 6, "cusp_sign": "Gêmeos", "cusp_deg": 11, "cusp_min": 12,
    "ruler": { "id": "mercury", "name": "Mercúrio" },
    "start": "2025-08-28T16:52:26Z", "end": "2026-08-28T22:42:33Z",
    "provisional": false, "weight": "primary"
  },
  "month": {
    "index": 11, "house": 5, "cusp_sign": "Touro",
    "ruler": { "id": "venus", "name": "Vênus" },
    "start": "2026-07-29T12:13:23Z", "end": "2026-08-28T22:42:33Z",
    "provisional": false, "weight": "refinement",
    "weight_note_pt": "Afina a data dentro do período que a análise maior apontou. Não abre período nem decide sozinha."
  },
  "day": { "index": 3, "house": 8, "cusp_sign": "Leão", "…": "…", "provisional": false, "weight": "refinement" },
  "formula_version": "profeccao-yuri-2"
}
```

### POST /progression — Progressão secundária (um dia por ano de vida)

Requer chave de API.

O mapa progredido de um instante, e o que ele toca. **Um dia de efeméride para cada ano de vida**, e o mapa avança INTEIRO — posições, ângulos, cúspides e **partes árabes**, que nascem do Ascendente e por isso mudam quando ele anda. O mapa sai completo em `result`. Os contatos vêm em **duas matrizes**: `progressed_to_progressed` e `progressed_to_natal`, e elas não se deduplicam — são perguntas diferentes. ⛔ **Só conjunção e oposição**, e o **antiscion conta** como caminho próprio (`via`: `direct` · `antiscion` · `contra_antiscion`). **Progridem** Sol, Lua, Ascendente, MC, Fortuna, Mercúrio, Vênus e Marte; ⛔ Júpiter, Saturno, os transaturninos e as estrelas fixas **recebem, mas não progridem**. Contato que envolva Lua ou Fortuna sai com `weight: "lesser"` — elas se movem rápido demais para cravar um ano sozinhas. 🔴 **Na leitura médica esta técnica pesa mais que a profecção**: é o filtro de quais anos podem ter problemas, e a cadeia é progressão → revolução solar → revolução lunar. ⚠️ **Dois orbes, e eles não se confundem:** os contatos **diretos** valem 4° e os **refletidos** (antiscion e contra-antiscion) valem 3°, que é orbe próprio do antiscion e não uma fração do outro. Cada contato declara o seu em `orb_limit_deg`. 📌 A chave da técnica sai na resposta (`day_for_a_year.key`: `one_day_per_year`) — a secundária é uma progressão entre várias, e quem integra não deveria ter de inferi-la do resultado. 📌 `houses_jd` na resposta declara de que instante saíram as CASAS, e ele **não** é o dos corpos: a fração do ano vira fração de dia, e o Ascendente dá uma volta completa a cada dia — o que se interpola ali é o tempo sideral, para que ele avance ~1° por ano.

**Corpo**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `datetime_local` | `string` | sim | Data e hora LOCAIS do lugar, ISO 8601: '1990-03-15T14:32:00'. Não converta para UTC — o Placidus faz isso com a regra de fuso da data. Alternativa: `jd_ut`. |
| `timezone` | `string` | não | Fuso IANA ('America/Sao_Paulo'). Opcional: sem ele, é resolvido pela cidade (`place`) ou pela coordenada. |
| `jd_ut` | `number` | não | Julian Day UT — o instante já resolvido, sem ambiguidade de fuso. Use quando estiver encadeando chamadas: ele vem em `meta.jd_ut` de toda resposta. |
| `lat` | `number` | não | Latitude decimal, −90 a 90. Obrigatória junto com `lon`, salvo se mandar `place`. |
| `lon` | `number` | não | Longitude decimal, −180 a 180. Negativa a oeste de Greenwich. |
| `place` | `string` | não | Cidade por extenso: 'Goiânia, GO', 'Kesswil, CH'. Resolve lat, lon e fuso de uma vez. Havendo homônimos, vence a de maior população — a cidade escolhida volta em `meta.place`, então dá para conferir. Para escolher você mesmo, use `GET /places`. |
| `technique` | `string` | não | Configuração de partida: 'natal' (padrão), 'horaria' (Regiomontanus, orbe apertado, Parte da Demissão) ou 'eleicao'. Acentos e apelidos em inglês são aceitos. Consulte `GET /techniques`. Técnica é rótulo: isto muda defaults, não comportamento. |
| `config` | `object` | não | Configuração explícita do cálculo — sistema de casas, orbes, tabelas de dignidade, o que ligar e desligar. Vence a `technique`. Ver a seção Configuração. |
| `sections` | `string[]` | não | Só estas seções voltam. Omitido, vem tudo. `meta` volta sempre. Recorta a RESPOSTA, não o cálculo. |
| `exclude` | `string[]` | não | Seções a remover da resposta. Útil para cortar as pesadas (`fixed_stars`). |
| `target_datetime` | `string` | não | Instante a situar, ISO local. Omitido, usa agora. |
| `target_timezone` | `string` | não | Fuso IANA do alvo. Omitido, herda o do mapa. |
| `target_jd` | `number` | não | Julian Day UT do alvo (alternativa ao datetime). |
| `orb_degrees` | `number` | não | Orbe dos contatos DIRETOS, de 0 a 10. Padrão 4°. |
| `antiscia` | `boolean` | não | Inclui os contatos por antiscion. Padrão true. |
| `antiscion_orb_degrees` | `number` | não | Orbe dos caminhos refletidos, de 0 a 10. Padrão 3° — orbe próprio do antiscion, não uma fração do de cima. |
| `fixed_stars` | `boolean` | não | Inclui as estrelas alcançadas pelos progressores. Padrão true. |
| `fixed_star_orb` | `number` | não | Força um orbe único para as estrelas. Ausente, vale o orbe próprio de cada uma pela magnitude — que, com os 4° acima, é o filtro mais apertado dos dois. |

**Exemplo de requisição**

```bash
curl -X POST https://placidus.app/api/public/v1/progression   -H "X-API-Key: $PLACIDUS_API_KEY"   -H "Content-Type: application/json"   -d '{
    "datetime_local": "1996-08-28T13:45:00",
    "place": "Salvador, BA",
    "target_datetime": "2026-08-06T12:00:00"
  }'
```

**Exemplo de resposta**

```json
{
  "age": 29,
  "age_exact": 29.938886,
  "progressed_datetime_utc": "1996-09-27T…Z",
  "houses_jd": 2450353.19,
  "day_for_a_year": { "key": "one_day_per_year", "days_elapsed": 29.938886, "year_basis": "solar_return" },
  "house_system": "placidus",
  "orb_degrees": 4,
  "antiscion_orb_degrees": 3,
  "progressors": ["sun", "moon", "asc", "mc", "fortuna", "mercury", "venus", "mars"],
  "natal_sect": "diurnal", "progressed_sect": "diurnal",
  "weight": "primary",
  "result": { "meta": { "…": "…" }, "bodies": [ /* … */ ], "arabic_parts": [ /* … */ ] },
  "contacts": {
    "progressed_to_progressed": [
      { "from": "sun", "from_name": "Sol", "to": "saturn", "to_name": "Saturno",
        "type": "opposition", "via": "direct", "orb_deg": 0, "orb_min": 53,
        "orb_limit_deg": 4, "applying": false, "rate_per_year": 0.981,
        "weight": "primary" }
    ],
    "progressed_to_natal": [ /* … */ ],
    "fixed_stars": { "active": [ /* … */ ] }
  },
  "notes": [],
  "formula_version": "progressao-yuri-2"
}
```

### POST /chart.png · /chart.svg — A Roda desenhada, em imagem

Requer chave de API.

O mesmo corpo de `/chart`, e a resposta é a **imagem** do mapa em vez do JSON — `image/png` ou `image/svg+xml`. É o desenho do próprio Placidus, o mesmo componente que a tela usa: não é uma segunda roda que possa divergir daquela. O SVG sai **autossuficiente** — a paleta em valores literais e as fontes embutidas em base64 —, então abre igual no navegador, no Illustrator e dentro de um PDF, sem depender de nenhuma fonte instalada. O PNG é rasterizado no servidor a partir do mesmo SVG. ⚠️ Os glifos astrológicos vêm de uma fonte embutida de propósito: a pilha de fontes do sistema desenha ♄ diferente em cada máquina, e em servidor nenhum ela existe. Aceita **GET** também, com o mapa na query (`datetime_local`, `place`, `lat`/`lon`, `timezone`, `technique`) — o formato cabe num `curl`. 📌 **Os parâmetros de desenho (de `width` para baixo na tabela) valem nos DOIS lugares: no corpo do POST e na query da URL.** Vindo o mesmo nome dos dois lados, a query vence — é o que permite trocar o tema de uma chamada já pronta mexendo só no endereço. Até 16/08/2026 eles só funcionavam na query e eram descartados **em silêncio** no corpo, com resposta 200: quem pedisse 1600 px sem estrelas recebia 1200 px com o aro cheio delas e não tinha como saber.

**Corpo**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `datetime_local` | `string` | sim | Data e hora LOCAIS do lugar, ISO 8601: '1990-03-15T14:32:00'. Não converta para UTC — o Placidus faz isso com a regra de fuso da data. Alternativa: `jd_ut`. |
| `timezone` | `string` | não | Fuso IANA ('America/Sao_Paulo'). Opcional: sem ele, é resolvido pela cidade (`place`) ou pela coordenada. |
| `jd_ut` | `number` | não | Julian Day UT — o instante já resolvido, sem ambiguidade de fuso. Use quando estiver encadeando chamadas: ele vem em `meta.jd_ut` de toda resposta. |
| `lat` | `number` | não | Latitude decimal, −90 a 90. Obrigatória junto com `lon`, salvo se mandar `place`. |
| `lon` | `number` | não | Longitude decimal, −180 a 180. Negativa a oeste de Greenwich. |
| `place` | `string` | não | Cidade por extenso: 'Goiânia, GO', 'Kesswil, CH'. Resolve lat, lon e fuso de uma vez. Havendo homônimos, vence a de maior população — a cidade escolhida volta em `meta.place`, então dá para conferir. Para escolher você mesmo, use `GET /places`. |
| `technique` | `string` | não | Configuração de partida: 'natal' (padrão), 'horaria' (Regiomontanus, orbe apertado, Parte da Demissão) ou 'eleicao'. Acentos e apelidos em inglês são aceitos. Consulte `GET /techniques`. Técnica é rótulo: isto muda defaults, não comportamento. |
| `config` | `object` | não | Configuração explícita do cálculo — sistema de casas, orbes, tabelas de dignidade, o que ligar e desligar. Vence a `technique`. Ver a seção Configuração. |
| `sections` | `string[]` | não | Só estas seções voltam. Omitido, vem tudo. `meta` volta sempre. Recorta a RESPOSTA, não o cálculo. |
| `exclude` | `string[]` | não | Seções a remover da resposta. Útil para cortar as pesadas (`fixed_stars`). |
| `width` | `number` | não | ⬇️ **Daqui para baixo são os parâmetros de DESENHO: valem no corpo e na query** (a query vence no empate). Lado do quadrado em pixels, de 200 a 4000. Padrão 1200. No PNG é a resolução; no SVG é só o tamanho declarado, porque vetor não perde qualidade. |
| `theme` | `'light' | 'dark'` | não | Padrão 'light'. É tema fixo da imagem — não segue o aparelho de quem abre. |
| `transparent` | `boolean` | não | Sem o fundo de papel. Padrão false. No PNG devolve canal alfa de verdade. |
| `title` | `string` | não | Nome no miolo da roda. Vazio, não desenha. |
| `subtitle` | `string` | não | Linha sob o nome — costuma ser o instante. |
| `aspects` | `'all' | 'major' | 'none'` | não | Quais aspectos traçar. Padrão 'major'. |
| `stars` | `boolean` | não | Estrelas fixas no aro. Padrão true. |
| `parts` | `boolean` | não | Partes árabes. Padrão true. |
| `terms` | `boolean` | não | Anel dos TERMOS, por fora do zodíaco — uma célula por segmento, com o glifo do regente (a escola é a do mapa — `dignity_tables`). Padrão false. A roda cresce para fora; o anel dos signos não muda. |
| `faces` | `boolean` | não | Anel das FACES (decanatos de 10°), por fora do dos termos. Padrão false. |
| `degrees` | `boolean` | não | Grau e minuto ao lado dos planetas. Padrão true. |
| `identity` | `boolean` | não | Nome, instante e seita no miolo. Padrão true — um arquivo que circula precisa se identificar. |

**Exemplo de requisição**

```bash
# POST, com o mapa e o desenho no MESMO corpo
curl -X POST "https://placidus.app/api/public/v1/chart.png" \
  -H "X-API-Key: $PLACIDUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime_local": "1875-07-26T19:32:00",
    "place": "Kesswil, CH",
    "width": 1600,
    "stars": false
  }' \
  -o mapa.png

# ou o desenho na query, por cima de um corpo fixo — a query vence
curl -X POST "https://placidus.app/api/public/v1/chart.png?width=2000&theme=dark" \
  -H "X-API-Key: $PLACIDUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datetime_local":"1875-07-26T19:32:00","place":"Kesswil, CH"}' \
  -o mapa.png

# GET, com tudo na query
curl "https://placidus.app/api/public/v1/chart.svg?datetime_local=1990-03-15T14:32:00&place=Goi%C3%A2nia,%20GO&title=Maria" \
  -H "X-API-Key: $PLACIDUS_API_KEY" -o mapa.svg
```

**Exemplo de resposta**

```json
HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: no-store

<bytes do PNG>

# Um parâmetro inválido é 422 com JSON, e diz o limite:
{ "detail": "'width' vai de 200 a 4000 pixels, e veio 9000." }
```

### POST /synastry — Dois mapas sobrepostos

Requer chave de API.

Calcula os dois mapas e as relações entre eles: aspectos cruzados (planeta de um a planeta do outro) e os corpos de cada um nas casas do outro. Exatamente dois mapas.

**Corpo**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `charts` | `ChartInput[]` | sim | Dois mapas, cada um com os mesmos campos de `/chart` (instante, lugar, config). A configuração de aspectos usada nos cruzamentos é a do primeiro. |

**Exemplo de requisição**

```bash
curl -X POST https://placidus.app/api/public/v1/synastry \
  -H "X-API-Key: $PLACIDUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "charts": [
      { "datetime_local": "1875-07-26T19:32:00", "place": "Kesswil, CH" },
      { "datetime_local": "1856-05-06T18:30:00", "place": "Příbor, CZ" }
    ]
  }'
```

**Exemplo de resposta**

```json
{
  "charts": [ { "meta": { "…": "…" }, "bodies": [ /* … */ ] }, { /* … */ } ],
  "synastry": {
    "cross_aspects": [
      { "from": "sun", "to": "moon", "type": "trine", "orb": 1.4, "applying": true }
    ],
    "a_bodies_in_b_houses": [ { "body": "sun", "house": 9 } ],
    "b_bodies_in_a_houses": [ { "body": "moon", "house": 3 } ]
  }
}
```

### GET /places — Cidade → coordenada e fuso

Requer chave de API.

Busca cidade no catálogo mundial e devolve coordenada e fuso IANA. Use quando quiser ESCOLHER entre homônimos em vez de aceitar a de maior população — há mais de uma Springfield, e mais de uma Londres.

**Parâmetros de consulta**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `q` | `string` | sim | Texto: 'Goiânia, GO', 'Munich, DE'. Mínimo 2 caracteres. |
| `limit` | `number` | não | 1 a 20. Padrão 8. |

**Exemplo de requisição**

```bash
curl "https://placidus.app/api/public/v1/places?q=Kesswil&limit=3" \
  -H "X-API-Key: $PLACIDUS_API_KEY"
```

**Exemplo de resposta**

```json
{
  "query": "Kesswil",
  "count": 1,
  "results": [
    { "display_name": "Kesswil, Thurgau, CH", "city": "Kesswil",
      "state": "Thurgau", "uf": "", "lat": 47.5983, "lon": 9.3216,
      "country": "CH", "tz_name": "Europe/Zurich", "population": 0 }
  ]
}
```

### GET /techniques — Configuração inicial de cada técnica

Requer chave de API.

As técnicas reconhecidas em `technique`, com os apelidos aceitos e a configuração de partida de cada uma. Horária, por exemplo, nasce com Regiomontanus, orbe apertado e a Parte da Demissão ligada.

**Exemplo de requisição**

```bash
curl https://placidus.app/api/public/v1/techniques -H "X-API-Key: $PLACIDUS_API_KEY"
```

**Exemplo de resposta**

```json
{
  "default": "natal",
  "techniques": [
    { "id": "natal", "aliases": ["natal", "nascimento"], "config": { "house_system": "placidus", "…": "…" } },
    { "id": "horaria", "aliases": ["horaria", "horária"], "config": { "house_system": "regiomontanus", "…": "…" } }
  ]
}
```

### GET /house-systems — Sistemas de casas suportados

Requer chave de API.

Os identificadores válidos em `config.house_system`.

**Exemplo de requisição**

```bash
curl https://placidus.app/api/public/v1/house-systems -H "X-API-Key: $PLACIDUS_API_KEY"
```

**Exemplo de resposta**

```json
{ "house_systems": [ { "id": "placidus", "name": "Placidus" }, { "id": "regiomontanus", "…": "…" } ] }
```

### GET /fixed-stars — Catálogo de estrelas fixas

Requer chave de API.

O catálogo validado, com magnitude, natureza planetária e tipo de objeto. Passando `jd_ut`, devolve a posição de cada estrela NAQUELA data — a precessão é calculada para o instante pedido, nunca para hoje. Com `interpretations=1`, cada estrela vem com o verbete em português — desligado por padrão porque uma listagem de 50 com verbete passa de 200 KB.

**Parâmetros de consulta**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `search` | `string` | não | Filtro por nome ou constelação. |
| `limit` | `number` | não | 1 a 500. Padrão 50. |
| `jd_ut` | `number` | não | Julian Day UT: inclui a posição na data. |
| `interpretations` | `boolean` | não | Inclui o verbete em português. Padrão false — é pesado. |

**Exemplo de requisição**

```bash
curl "https://placidus.app/api/public/v1/fixed-stars?search=Regulus&jd_ut=2406096.29" \
  -H "X-API-Key: $PLACIDUS_API_KEY"
```

**Exemplo de resposta**

```json
{ "count": 1, "stars": [ { "name_swiss": "Regulus", "magnitude": 1.36, "longitude": 146.9, "sign": "Leão", "…": "…" } ] }
```

### GET /sections — As seções que um mapa devolve

Não requer chave de API.

A lista de nomes válidos em `sections` e `exclude`, servida pela mesma constante que os valida no servidor. Sem chave: serve para conferir o vocabulário antes de gastar uma chamada de cálculo com um nome errado.

**Exemplo de requisição**

```bash
curl https://placidus.app/api/public/v1/sections
```

**Exemplo de resposta**

```json
{ "sections": ["bodies", "moon_phase", "angles", "points", "houses", "aspects", "fixed_stars", "arabic_parts", "strength_ranking", "antiscia", "temperament", "mentality", "primary_motivation"] }
```

### GET /health — Status da API

Não requer chave de API.

Checagem de conectividade. Sem chave — serve para testar o caminho antes de ter uma.

**Exemplo de requisição**

```bash
curl https://placidus.app/api/public/v1/health
```

**Exemplo de resposta**

```json
{ "status": "ok", "api": "placidus-public", "version": "v1" }
```

## Seções da resposta

Chaves de topo de um mapa calculado, e os nomes válidos em `sections` e `exclude`.

- **`meta`** — Sempre presente, e não removível: instante em Julian Day e em UTC, fuso e offset aplicados, coordenada, sistema de casas, seita (diurno/noturno) e versão do motor. É o que torna a resposta auditável — sem ela não dá para saber o que produziu aqueles números. Quando o lugar veio de `place`, traz também `meta.place` com a cidade escolhida.

- **`bodies`** — Os 10 corpos (7 tradicionais + Urano, Netuno e Plutão). Cada um com longitude, signo, grau/minuto/segundo, latitude, velocidade, retrogradação, casa, orientalidade solar, dignidades essenciais (com os regentes de triplicidade, termo e face, e a pontuação) e dignidades acidentais (com os fatores somados e o estado de combustão). ⚠️ **Combustão exige o MESMO SIGNO do Sol**, além dos 8°30' — em signos diferentes o planeta fica `sob os raios do Sol` (−4), nunca combusto (−5), ainda que a distância seja a de combustão. Sem Lilith e sem Quíron — decisão de escopo do projeto.

- **`moon_phase`** — Quadrante da lunação e o humor correspondente, em código e em português.

- **`angles`** — Ascendente, Meio-do-Céu, Fundo-do-Céu e Descendente, com posição completa.

- **`points`** — Nodo Norte e Nodo Sul (nodo verdadeiro), com signo, grau e casa.

- **`houses`** — O sistema usado e as 12 cúspides em graus de longitude eclíptica.

- **`aspects`** — Aspectos entre os corpos, com tipo, orbe (em decimal e em grau/minuto), se é aplicativo e se passou pelo portão do signo. O orbe é por ASTRO, somado em metades — não por aspecto.

- **`fixed_stars`** — As conjunções de estrela fixa encontradas, calculadas com a precessão da data do mapa. Cada estrela traz magnitude, natureza planetária, constelação, o ponto ao qual está conjunta, o orbe e o **verbete em português** (`interpretation`). A ordem das operações é fixa: primeiro o PISO DE MAGNITUDE (`magnitude_floor`: ≤3 no natal, <3 na revolução — e estrela sem magnitude fica sempre fora), depois o orbe, que é por magnitude (quanto mais brilhante, mais longe alcança). No desempate, a estrela **fundamental** vence o brilho; senão vence a MAIS BRILHANTE, não a mais colada, e o orbe só desempata brilho igual. As **12 fundamentais** são Algol, Aldebaran, Regulus, Antares, Fomalhaut, Sirius, Spica, Arcturus, Vega, Capella, Castor e Pollux — `fundamental_list` na resposta diz qual lista estava valendo. Em **revolução** o orbe não sai da magnitude: são **3°** para dezesseis estrelas (as 12 mais Procyon, Vindemiatrix, Alfard e Betelgeuse) e **1°** para todas as demais; `orb_table` e `revolution_wide_orb_list` declaram o que rodou. ⚠️ As duas listas não se fundem: as quatro extras alcançam mais longe e **não** ganham o desempate por importância. `won_over` mostra quem ela expulsou e por quê, `discarded_by_magnitude` diz quantas conjunções o piso derrubou, `magnitude_source` diz de que tabela veio a magnitude e `object_type` distingue estrela de aglomerado, nebulosa e galáxia. Entrada com `bypassed_floor: true` **não passou pelo piso**: é um objeto não-estelar admitido por tema (visão, olhos, cegueira) porque `config.fixed_stars.include_nebulae` estava ligado.

- **`arabic_parts`** — As 8 partes, com longitude, signo, casa, a fórmula usada e a seita aplicada (as fórmulas invertem em mapa noturno). Partes opcionais entram por `config.arabic_parts_extra`.

- **`strength_ranking`** — Os corpos ordenados por força. `rank: 1` com `lord_of_nativity: true` é o Senhor da Natividade — apurado por SOMA DE DIGNIDADES ESSENCIAIS, com as acidentais como coluna de desempate. Não é almuten figuris.

- **`antiscia`** — Antiscion e contra-antiscion de cada corpo, e o que cada um toca. A reflexão é conferida contra os corpos, os ângulos, os nodos, as partes e as **cúspides intermediárias** (2, 3, 5, 6, 8, 9, 11 e 12) — cúspide que coincide com um ângulo não sai duas vezes. O orbe da incidência é **3°**, e cada toque o declara em `orb_limit_deg`.

- **`temperament`** — O humor resultante e a assinatura em português ('umidade forte, frio forte') — é a assinatura que o produto usa, porque 'Fleumático' sozinho não separa dois fleumáticos de regimes diferentes. Vem em DUAS camadas que nunca se somam: `tally` são os QUATRO pontos (Ascendente pelo elemento, regente do Ascendente pela natureza, fase da Lua pelo elemento da fase, estação do Sol pelo signo), e é ele que decide o humor; `modulation_tally` é a lista fechada de moduladores, e ela desempata o eixo que ficou 2×2 e aponta a qualidade em excesso. Cada linha vale UM voto: não há peso, não há escala com sinal. Os planetas que aspectam a Lua ou o Ascendente entram TODOS, com portão de signo e orbe de 4° — e esses 4° contam-se em GRAU CHEIO, então um aspecto de 4°06' entra e só cai a partir de 5°00'. `resolution` diz por qual camada cada eixo foi decidido — a escada tem QUATRO degraus, nesta ordem: os pontos (`points`), a modulação (`modulation`), o **Senhor da Natividade** (`lord_of_nativity`, pela natureza dele — 'o primeiro entre os iguais') e, só quando não há senhor apurado, o aspecto mais justo (`tightest_aspect`). Qualidade que só passou nesses dois últimos degraus sai marcada na assinatura com **'(por desempate)'** — é a mais fraca que existe, e o texto diz isso. `notes` traz o que o motor não decidiu sozinho — hoje, Mercúrio conjunto a naturezas divergentes. Traz também `balancing`, que é a assinatura virada em DIREÇÃO DE CONDUTA, em **três papéis que não se confundem**: `targets` (a qualidade em excesso e a ação contrária, com prioridade), `constraints` (o que a correção não pode piorar) e `support` (a ação branda que pode acompanhar, sempre com `required_compatibility`). O `mode` diz qual dos quatro caminhos a resposta tomou: `single_axis`, `dual_axis`, `maintenance` ou `indefinite`. ⚠️ **Quem escolhe o alvo é `imbalance`, não a força do eixo** — e é isso que faz um melancólico de secura forte e frio fraco receber "umedecer é o alvo; aquecer brando pode acompanhar, desde que não use calor seco" em vez de "aquecer e umedecer com o mesmo peso". ⚠️ **Serve para não tratar o NOME do temperamento:** sanguíneo de tabela pede "resfriar e secar", mas se o calor dele é fraco, resfriar retira o pouco que há; por isso o eixo fraco nunca vira alvo e ganha uma restrição `do_not_remove_vital` — o que se preserva é sempre calor ou umidade, nunca frio nem secura. Quando um eixo não fecha, `mode` vem `indefinite` e não há direção: é caso de leitura humana. ⛔ Isto é classificação, não prescrição — o motor não escolhe dieta, hábito, erva nem procedimento, e quem escreve o texto consome estes campos e **não inventa limiar próprio**.

- **`mentality`** — A combinação que define a mentalidade (almuten da Lua e almuten de Mercúrio), o polo, a tabela de força, modalidade, orientalidade e os textos de leitura. O polo vem em DUAS camadas: `pole.side` é o lado que os quatro definidores decidiram (Lua, Mercúrio e os dois almutens), e `pole.counterweight.balance` diz se o resto do mapa **abranda** (`attenuated`) ou **agrava** (`aggravated`) esse lado — é balanço de testemunhos, não soma. Sem essa segunda camada, todo mapa de definidores fracos recebe o mesmo repertório duro. Traz também `pending`: os pontos que a especificação cita sem definir critério, e que por isso não entram na conta — declarados em vez de chutados.

- **`primary_motivation`** — Responde a "que tipo de bem eu sou capaz de realizar e desfrutar?". Traz a cadeia de três pontos: `inspiration` (o SIGNO do Ascendente), `action` (o PLANETA regente — o signo dele é só o modo) e `final_disposition` (o dispositor); os casos especiais detectados (regente domiciliado, recepção mútua, dependência, o dispositor que manda); e `livelihood_and_fulfilment`, o cruzamento sustento × satisfação. Traz também as ATIVIDADES: `profession_examples` sai do planeta do ponto 2 e `hobby_examples` do ponto 3 — e do ponto 2 também, quando a cadeia para nele. Cada linha vem com o **verbo** que a justifica, porque afirmar que uma atividade realiza alguém sem mostrar o verbo é o que o método proíbe. ⛔ Três coisas a API não faz, e são do intérprete: inventar entrada fora do dicionário validado; montar a ponte entre os pontos 2 e 3 (só vale com a frase que liga os dois verbos); e recortar pela vida da pessoa — saúde, dinheiro, tempo e formação mudam o FORMATO, nunca a função. Por isso a lista vem inteira, como exemplos, e não como prescrição.

## Configuração do cálculo (`config`)

Todo campo é opcional; o que faltar cai no padrão tradicional. Diferente de `sections`, que só recorta a resposta, `config` muda a conta.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `house_system` | `string` | não | Sistema de casas. Padrão 'placidus'. Ver GET /house-systems. |
| `dignity_tables` | `object` | não | Escola de cada tabela: `triplicity` ('ptolemy' | 'dorotheus'), `terms` ('ptolemaic' | 'egyptian'), `faces` ('chaldean'). |
| `house_offset` | `string` | não | Promoção para a casa seguinte, no mesmo signo: 'five_degrees' (padrão, até 5° antes da cúspide), 'sixth' (até 1/6 da casa) ou 'off'. Partes árabes não seguem esta régua — elas só promovem por minutos. |
| `bodies` | `string[]` | não | Quais corpos calcular. Padrão: os 10. |
| `points` | `string[]` | não | Pontos: asc, mc, ic, dsc, north_node, south_node. |
| `aspects` | `object` | não | `major` (lista), `minor` (vazia por padrão — aspectos menores não existem no esquema por signo) e `orbs`, que é por ASTRO: sun, moon, mercury, venus, mars, jupiter, saturn, `modern` (Urano/Netuno/Plutão), `point_planet` (planeta com ângulo, nodo ou parte — 5°, a regra dos 5 graus) e `point` (quando os DOIS lados são pontos sem corpo, ex.: ASC × MC). Mais dois campos: `flat_orb` é um limite ÚNICO do par, que ignora `orbs` inteiro — é o que horária e eleição usam (3° estritos), porque escrever 3 em cada astro daria 1°30' ao par pelo modelo de metades. E `include_points` diz quais pontos entram na tabela de aspectos além dos corpos: padrão ASC, MC, DSC, IC e os dois nodos; lista vazia devolve só os aspectos entre planetas. Duas restrições de natureza, e não de orbe: Urano/Netuno/Plutão só formam CONJUNÇÃO, e os nodos só conjunção e trígono. E uma régua de eixo, para cada figura sair UMA vez e na forma em que se lê: a ponta primária (ASC, MC) carrega conjunção, trígono e quadratura; a segunda (DSC, IC) carrega conjunção e trígono; entre dois pontos de eixo, só as primárias. Assim sai `saturn conjunction ic` e não `saturn opposition mc` — é a mesma figura, e a primeira é a que o astrólogo lê. As duas pontas de um mesmo eixo nunca aspectam uma à outra: estão a 180° por definição, não por posição. ⚠️ A régua só vale quando a outra ponta está em `include_points`; sem ela, o ponto volta a carregar todos os aspectos, para nenhuma configuração perder figura em silêncio. |
| `fixed_stars` | `object` | não | `mode`: 'closest' (padrão — uma estrela por ponto, a mais brilhante; o nome do modo é histórico), 'all' (todas as conjunções legítimas, para auditar o desempate) ou 'off'. `extra_search` acrescenta estrelas por nome. `chart_kind`: 'natal' (padrão) ou 'revolution', que aperta o piso de magnitude de ≤3 para <3 — a rota /revolution já marca sozinha. O piso não tem como ser desligado. `interpretations`: padrão true; false tira o verbete em português do payload (≈ 1,5 KB por estrela). `include_nebulae`: padrão **false**; true deixa aglomerado, nebulosa e galáxia atravessarem o piso — e só o piso, o orbe continua valendo —, marcando a entrada com `bypassed_floor`. Ligue só quando a leitura tocar visão, olhos ou cegueira: quem sabe o contexto é quem faz a pergunta, não o motor. `fundamental_list` (as 12 do desempate) e `revolution_wide_orb_list` (as 16 de 3° na revolução) sobrescrevem as listas do motor sem precisar de deploy — mande-as só para auditar ou para reproduzir um mapa antigo. `revolution_list` restringe o **universo** da revolução e vem vazia: por padrão a revolução vê o catálogo inteiro sob o piso `<3`. |
| `arabic_parts` | `boolean` | não | Padrão true — as 8 partes. |
| `arabic_parts_extra` | `string[]` | não | Partes opcionais por id (ex.: 'demissao', do padrão de horária). |
| `antiscia` | `boolean` | não | Padrão true. |
| `dignities` | `boolean` | não | Padrão true. |
| `strength_ranking` | `boolean` | não | Padrão true — inclui o Senhor da Natividade. |
| `temperament` | `boolean` | não | Padrão true. |
| `mentality` | `boolean` | não | Padrão true. |
| `primary_motivation` | `boolean` | não | Padrão true. |

## Erros

Erro volta como JSON com o campo `detail` explicando o que houve.

| Código | Significado | O que fazer |
| --- | --- | --- |
| 401 | Chave ausente ou inválida. | Confira o cabeçalho `X-API-Key` e o valor da chave. |
| 403 | Chave revogada. | Peça uma chave nova ao administrador. |
| 422 | O pedido está mal formado ou incompleto. | O campo `detail` diz exatamente o quê — cidade não encontrada, técnica desconhecida, seção inexistente, tabela de dignidade inválida. É erro do pedido: repetir sem mudar nada dá o mesmo resultado. |
| 429 | Limite de requisições estourado para a chave. | Espere o número de segundos do cabeçalho `Retry-After`. Se acontecer em uso normal, o laço está chamando mais do que precisa. |
| 502 | O motor recusou ou falhou. | Tente de novo; persistindo, é falha nossa. |
| 503 | Serviço de cálculo ou de localidades indisponível. | Tente de novo em instantes. |

## Receitas

### Mapa completo, em uma chamada

O caminho mais curto: data, hora e cidade. O fuso vem junto com a cidade.

```bash
curl -X POST https://placidus.app/api/public/v1/chart \
  -H "X-API-Key: $PLACIDUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datetime_local":"1990-03-15T14:32:00","place":"Goiânia, GO"}'
```

### Só o que você vai usar

`sections` corta a resposta. Um mapa inteiro passa de **110 KB** — subiu de 80 KB em 20/08/2026, quando as estrelas ganharam o verbete em português; pedindo três seções ele cabe em poucos KB, o que importa quando a resposta vai para dentro do contexto de um modelo de linguagem. 📌 Se o que pesa forem as estrelas e você só quer as conjunções, `config.fixed_stars.interpretations: false` devolve os 20 KB do verbete sem tirar a seção.

```json
{
  "datetime_local": "1990-03-15T14:32:00",
  "place": "Goiânia, GO",
  "sections": ["bodies", "houses", "temperament"]
}
```

### Node.js

Sem SDK: é HTTP e JSON.

```javascript
const res = await fetch("https://placidus.app/api/public/v1/chart", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.PLACIDUS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    datetime_local: "1990-03-15T14:32:00",
    place: "Goiânia, GO",
  }),
});
if (!res.ok) throw new Error((await res.json()).detail);
const mapa = await res.json();
console.log(mapa.strength_ranking[0]); // o Senhor da Natividade
```

### Python

O mesmo, com httpx ou requests.

```python
import os, httpx

r = httpx.post(
    "https://placidus.app/api/public/v1/chart",
    headers={"X-API-Key": os.environ["PLACIDUS_API_KEY"]},
    json={
        "datetime_local": "1990-03-15T14:32:00",
        "place": "Goiânia, GO",
        "sections": ["bodies", "angles", "temperament"],
    },
    timeout=30,
)
r.raise_for_status()
mapa = r.json()
print(mapa["temperament"]["result"], "—", mapa["temperament"]["signature_pt"])
```

### Andar no tempo sem acumular erro

Guarde o `jd_ut` do mapa base e mande o deslocamento ACUMULADO a cada passo — nunca encadeie. Assim, +1 e depois −1 voltam ao instante exato.

```json
// base: meta.jd_ut do /chart
{ "jd_ut": 2406096.2932175924, "lat": 47.5983, "lon": 9.3216,
  "offsets": { "year": 1, "month": 2 } }
```

### A roda como arquivo

Troque `/chart` por `/chart.png` ou `/chart.svg` e o mesmo pedido devolve a imagem. O SVG é autossuficiente — abre em qualquer lugar sem fonte instalada —, e o PNG sai na resolução que você pedir, até 4000px.

```bash
curl -X POST "https://placidus.app/api/public/v1/chart.png?width=2000" \
  -H "X-API-Key: $PLACIDUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datetime_local":"1990-03-15T14:32:00","place":"Goiânia, GO","title":"Maria"}' \
  -o mapa.png
```

### Horária com a régua da horária

`technique` traz a configuração de partida certa — não é preciso saber que horária pede Regiomontanus e orbe apertado.

```json
{
  "datetime_local": "2026-08-12T15:10:00",
  "place": "Goiânia, GO",
  "technique": "horaria"
}
```

## O que a API não faz

- `primary_motivation` devolve profissões e hobbies de um **dicionário fechado e validado** pelo astrólogo responsável — a API não inventa entradas novas por semelhança, e não recorta a lista pelo contexto de vida da pessoa. O que ela entrega são exemplos com o verbo de cada um; escolher entre eles é do intérprete.
- Os blocos de análise trazem `pending`: onde a doutrina não fechou, o motor DECLARA em vez de chutar. Leia esse campo antes de tratar um resultado como definitivo.
- A profecção mensal e a diária não são mais provisórias, mas continuam pesando menos: `weight: "refinement"`. Elas afinam a data dentro de um período que a análise maior já apontou — não abrem período nem decidem sozinhas. Só o nível anual é `primary`.
- As duas listas que a régua de estrelas fixas ainda espera do astrólogo vêm **vazias**: as estrelas `fundamental` (que venceriam o brilho no desempate) e a lista curta da revolução. O campo existe, a régua está escrita, e o comportamento de hoje é o de antes delas.
- `synastry` aceita exatamente 2 mapas. A estrutura prevê até 4, mas 3 e 4 não estão implementados.
- Não há paginação nem processamento em lote: um mapa por requisição.
- Planetas: os 7 tradicionais mais Urano, Netuno e Plutão. Sem Lilith, sem Quíron, sem asteroides — é decisão de escopo, não omissão.
- A API não guarda nada. Não existe endpoint para reler um cálculo anterior: guarde o input e recalcule.

## Histórico de mudanças

O que mudou para quem consome a API, do mais recente para o mais antigo. Serve para responder "a minha cópia está velha, e o que perdi?" sem precisar comparar dois arquivos inteiros.

### 2026-09-04.2 — 2026-09-04

- 🔴 `GET/POST /chart.svg` e `/chart.png`: os anéis de `terms` e `faces` foram REDESENHADOS no mesmo dia — agora são anéis próprios POR FORA do zodíaco (célula por segmento, fundo alternado, glifo do regente), e o anel dos signos não muda de tamanho. A versão da manhã os espremia dentro do anel do signo e não sobreviveu à primeira olhada do cliente.
- 🔴 Estrela fixa no desenho virou **ícone de estrela** — o nome escrito saiu da borda (ficava grande e truncado); ele continua no `<title>` do SVG e, na tela, no tooltip e na ficha. Com isso a sobreposição (bi-wheel) parou de encolher quando as estrelas ligam: o encolhimento existia só para o nome caber.

### 2026-09-04.1 — 2026-09-04

- 🆕 `meta.dignity_tables`: toda resposta de mapa passou a declarar as tabelas de **termos e faces RESOLVIDAS** — a escola que o cálculo usou (`school`) e as linhas por signo (`rows`). É o que permite desenhar as faixas sem manter cópia local da tabela, que é como um limite de termo já divergiu em silêncio.
- 🆕 `GET/POST /chart.svg` e `/chart.png`: dois parâmetros de desenho novos, `terms` e `faces` — as faixas dos termos e das faces (decanatos) dentro do anel do zodíaco, com o regente de cada segmento. **Padrão false nos dois**: ligar encolhe o glifo do signo, e uma faixa nova ligada por padrão mudaria a imagem de quem já integra.

### 2026-09-03.1 — 2026-09-03

- 🔴 **Temperamento: o desempate ganhou o degrau do SENHOR DA NATIVIDADE.** A escada agora tem quatro degraus, nesta ordem: pontos → modulação → Senhor da Natividade (pela natureza dele) → aspecto mais justo, que só entra quando não há senhor apurado. Mapa que empatava nas duas camadas podia sair com o humor INVERTIDO (o aspecto mais justo decidia contra o Senhor). `resolution.via` pode vir `lord_of_nativity`, e `formula_version` passou a `temperamento-yuri-4`.
- Temperamento: qualidade decidida no voto de minerva (`lord_of_nativity` ou `tightest_aspect`) sai marcada na `signature_pt` com **"(por desempate)"** — é a mais fraca que existe, e o texto agora diz isso.
- 🔴 **Aspecto entre dois ÂNGULOS do mapa não sai mais** (ASC×MC, e qualquer par entre ASC/MC/DSC/IC). A quadratura Ascendente–Meio do Céu é geometria das casas — todo mapa a tem — e saía como figura no topo da lista. No cruzado de sinastria/revolução nada muda: ângulo de um instante sobre ângulo de outro é posição, e continua saindo.
- `GET /chart.svg` e `/chart.png`: as sete partes árabes herméticas saem com o **glifo do planeta de referência num círculo** (Fortuna→Lua, Espírito→Sol, Necessidade→Mercúrio, Amor→Vênus, Valor→Marte, Vitória→Júpiter, Cativeiro→Saturno) em vez do losango genérico; Casamento e Demissão seguem no losango.

### 2026-08-20.3 — 2026-08-20

- 🔴 Estrelas fixas: a lista das **12 fundamentais** foi fechada pelo astrólogo e está **ligada** — Algol, Aldebaran, Regulus, Antares, Fomalhaut, Sirius, Spica, Arcturus, Vega, Capella, Castor e Pollux. No desempate de um ponto disputado, a fundamental **vence a mais brilhante**: onde duas estrelas alcançam o mesmo ponto e só uma é fundamental, a estrela que sai pode ser outra que a de ontem. `formula_version` passou a `estrelas-yuri-4`.
- 🔴 A **revolução** ganhou tabela de orbe própria: **3°** para dezesseis estrelas — as 12 acima **+ Procyon, Vindemiatrix, Alfard e Betelgeuse** — e **1° para todas as demais**. A escala por magnitude (2,5° / 2° / 1°) deixa de valer em revolução; o piso `<3` não mudou. A resposta traz `orb_table` e `revolution_wide_orb_list`.
- ⚠️ As duas listas são **independentes e não se fundem**: `fundamental` (12) decide o desempate, `orb_limit_deg` (16) decide o alcance. As quatro extras alcançam mais longe e **não** vencem o desempate por importância.
- Aglomerado, nebulosa e galáxia passaram a ter orbe declarado de **1°**, fixo — atravessar o piso por tema (`include_nebulae`) **não promove de orbe**. Na prática nenhum objeto do catálogo muda de resultado hoje; a régua é que deixou de depender da magnitude deles.
- 🔴 `POST /progression`: o orbe dos contatos passou de 1° para **4°**, e o antiscion ganhou orbe próprio de **3°** (`antiscion_orb_degrees`). Os dois vêm da régua que o astrólogo fechou; um mapa progredido acende bem mais contatos que na versão anterior. `formula_version` passou a `progressao-yuri-2`.
- `POST /progression` passou a declarar a chave da técnica na resposta (`day_for_a_year.key`: `one_day_per_year`).
- 🔴 **Antiscion e contra-antiscion**: o orbe das incidências passou de **1° para 3°**, e a reflexão passou a alcançar as **cúspides intermediárias** (2, 3, 5, 6, 8, 9, 11 e 12) além dos corpos, ângulos, nodos e partes. Cúspide que coincide com um ângulo não sai duas vezes. Cada incidência declara `orb_limit_deg`.

### 2026-08-20.2 — 2026-08-20

- 🆕 `POST /progression` — **progressão secundária**, um dia de efeméride para cada ano de vida. O mapa avança inteiro (posições, ângulos, cúspides e **partes árabes**, que nascem do Ascendente), e a resposta traz o mapa progredido completo mais duas matrizes de contato: progredido × progredido e progredido × natal.
- ⛔ Só conjunção e oposição, e o antiscion conta como caminho próprio (`via`). Progridem Sol, Lua, Ascendente, MC, Fortuna, Mercúrio, Vênus e Marte; Júpiter, Saturno, os transaturninos e as estrelas fixas recebem mas não progridem.
- 🔴 Na leitura médica a progressão **pesa mais que a profecção** — é o filtro de quais anos podem ter problemas. A cadeia é progressão → revolução solar → revolução lunar.

### 2026-08-20.1 — 2026-08-20

- 🔴 Profecção: o MENSAL e o DIÁRIO **saíram de provisórios**. A aula que a régua esperava aconteceu, e o autor da doutrina os validou — `provisional` agora é `false` nos três níveis e `provisional_note_pt` sumiu. `formula_version` passou a `profeccao-yuri-2`.
- No lugar entrou `weight`: `primary` no ano, `refinement` no mês e no dia. Não é a mesma coisa que provisório — os dois níveis menores **afinam a data dentro do período que a análise maior apontou**, não abrem período nem decidem sozinhos. Continue não tratando os três com o mesmo peso.
- `POST /revolution` passou a devolver `arabic_parts_arc`: as partes do **natal** transportadas para a revolução pelo arco entre os dois Ascendentes (`parte − Asc_natal + Asc_da_revolução`). É uma camada diferente das partes recalculadas, e **as duas se usam** — cada parte diz qual é em `method` (`recalculated` · `arc_transported`).
- Estrelas fixas: cada estrela ativa passou a trazer o **verbete em português** (`interpretation.verbete`, mais `significado`, `mitologia` e `encaixe_interpretativo`) — 286 chaves, o manual mestre do astrólogo. `config.fixed_stars.interpretations: false` desliga, e `GET /fixed-stars?interpretations=1` os traz na busca.
- 🔴 Três estrelas voltaram ao catálogo: **Denebola** (mag 2,13), **Kaus Medius** (2,67) e **Kerb**. As duas primeiras passam do piso — ou seja, **faltavam em mapa**. A extração do catálogo original tinha duplicado três linhas e perdido três.
- Estrelas fixas: `magnitude_source` em toda estrela (de que tabela veio a magnitude), `object_type` (`star` · `cluster` · `nebula` · `galaxy`) e `fundamental`. `formula_version` passou a `estrelas-yuri-3`.
- Aglomerado e nebulosa passaram a poder entrar **por tema** (visão, olhos, cegueira): `config.fixed_stars.include_nebulae` — desligado por padrão — os deixa atravessar o piso de magnitude, e só ele; a entrada volta marcada com `bypassed_floor: true`.

### 2026-08-16.5 — 2026-08-16

- Esta documentação passou a se identificar: versão e data de publicação no topo, e este histórico. Uma cópia local agora carrega a própria idade — antes, um snapshot velho era indistinguível de um novo, e a diferença só aparecia como divergência de cálculo.

### 2026-08-16.4 — 2026-08-16

- `temperament.balancing`: a assinatura do temperamento virada em direção de conduta, em três papéis — `targets` (a qualidade em excesso e a ação contrária), `constraints` (o que a correção não pode piorar) e `support` (a ação branda que acompanha). `mode` diz o caminho: `single_axis`, `dual_axis`, `maintenance` ou `indefinite`.
- O alvo sai de `imbalance`, não da força do eixo: qualidade fraca nunca vira alvo, e o que se preserva num eixo fraco é sempre calor ou umidade — nunca frio nem secura.

### 2026-08-16.3 — 2026-08-16

- 🔴 `POST /profection` estava documentada e respondia **404**: a rota existia no motor, mas não passava pela porta pública. Agora responde.
- 🔴 Os parâmetros de desenho de `/chart.png` e `/chart.svg` (`width`, `theme`, `stars`, `identity` e os demais) eram lidos **só da query**, embora a tabela os liste no corpo. Mandados no corpo, eram descartados em silêncio com resposta 200 — 1600 px pedido, 1200 px entregue. Agora valem nos dois lugares; a query vence no empate, e valor inválido é 422 com o limite.

### 2026-08-16.2 — 2026-08-16

- Régua dos eixos nos aspectos: a ponta primária (ASC, MC) carrega conjunção, trígono e quadratura; a segunda (DSC, IC), conjunção e trígono. Cada figura sai uma vez e na forma em que se lê — `saturn conjunction ic`, e não `saturn opposition mc`.

### 2026-08-16.1 — 2026-08-16

- Profecção: as setas miram no **começo** do período, não no meio. Mirar no meio devolvia um instante sem sentido astrológico apresentado como a data pedida.
- Recepção negativa: o grau passou a devolver `detriment_of` e `fall_of` — de quem aquele signo é o exílio e a queda. Descrevem o lugar e **não pontuam**.

### 2026-08-15.1 — 2026-08-15

- Aspectos aos pontos: a tabela passou a incluir ASC, MC, DSC, IC e os dois nodos (`aspects.include_points`). Antes entravam só os 10 corpos, e o mapa saía sem aspecto nenhum ao Ascendente.
- `aspects.flat_orb`: limite único do par, que ignora o modelo por astro. É o que horária e eleição usam (3° estritos) — escrever 3 em cada astro daria 1°30' ao par, pelo modelo de metades.
- Urano, Netuno e Plutão só formam conjunção; os nodos, só conjunção e trígono.

### 2026-08-14.1 — 2026-08-14

- `POST /profection` (anual, mensal e diária) e `POST /chart.png` · `/chart.svg` (a Roda desenhada).
- `primary_motivation` saiu de `null`: a cadeia de três pontos, os casos especiais e as atividades, cada linha com o verbo que a justifica.
- Estrelas fixas: piso de magnitude antes do orbe (≤3 natal, <3 revolução), e quem fica com o ponto é a **mais brilhante**, não a mais colada.
- Temperamento: quatro pontos com contagem de testemunhos, e o senhor da natividade passou a modular em vez de pontuar. Corrige o que esta documentação ensinava antes.
- Mentalidade: contrapeso do polo, e o empate do almuten decidido pela dignidade acidental.
- Combustão exige o **mesmo signo** do Sol; em signos diferentes é `sob os raios`. As três distâncias: combustão 8°30', sob os raios até 15°, cazimi 17' de arco.

### 2026-08-12.1 — 2026-08-12

- Primeira publicação da documentação da API pública.