# NatalTruth Calculation API

**Base URL (production):** `https://api.nataltruth.com`  
**Phase:** API-first (engine live before marketing front / CMS).

## Always included

Every `/v1/calculate` response contains:

| Block | Contents |
|-------|----------|
| **Ephemeris** | Planets, houses, aspects (Swiss Ephemeris by default) |
| **Patterns** | Chart configurations detected on natal planets (see below) |
| **Gematria / numerology** | From **full legal name** + birth date |

There is no lite response shape.

## Engine modes

| Mode | Header/body | Intent |
|------|-------------|--------|
| `swiss` (default) | `"engineMode": "swiss"` | Premium-grade Swiss Ephemeris WASM — **$199/mo tier** |
| `approx` | `"engineMode": "approx"` | Secondary path (~high accuracy when fully wired) — **always exposed in API** so clients can choose |

Both modes return the **same snapshot fields**. Product billing decides which mode the client requests; the API does not strip data.

## Patterns — what this means

A **natal pattern** is a multi-planet configuration in the birth chart, e.g.:

| Pattern | Meaning (plain language) |
|---------|---------------------------|
| **Grand Trine** | Three planets ~120° apart — ease/flow in an element |
| **T-Square** | Opposition + two squares — drive through tension |
| **Yod** (“Finger of God”) | Two quincunxes + a sextile — adjustment / calling |
| **Stellium** | 3+ planets clustered in one sign/house — concentration |
| **Grand Cross** | Four planets in mutual squares/oppositions — high tension/structure |

The API returns each pattern’s type, planets involved, strength (0–100), and description. Reports and coaching use this list as ground truth — not invented later.

## POST `/v1/calculate`

### Request

```json
{
  "fullName": "Jane Example",
  "birthDate": "1990-06-15",
  "birthTime": "14:30",
  "birthTimeAccuracy": "exact",
  "birthPlaceLabel": "Casablanca, Morocco",
  "latitude": 33.5731,
  "longitude": -7.5898,
  "utcOffset": "+01:00",
  "timeZoneId": "Africa/Casablanca",
  "engineMode": "swiss"
}
```

| Field | Required | Notes |
|-------|----------|--------|
| `fullName` | yes | Full legal name for gematria |
| `birthDate` | yes | `YYYY-MM-DD` |
| `birthTime` | if known | `HH:mm` or `HH:mm:ss` |
| `birthTimeAccuracy` | yes | `exact` \| `approximate` \| `unknown` |
| `birthPlaceLabel` | yes | Display label |
| `latitude` / `longitude` | yes | From city geocode |
| `utcOffset` | strongly recommended | e.g. `+01:00` at birth |
| `timeZoneId` | recommended | IANA id |
| `engineMode` | no | default `swiss` |

If time is `unknown`, local **12:00** is used and **flagged** in `moment.notes`.

### Response (shape)

```json
{
  "ok": true,
  "snapshot": {
    "version": 1,
    "engineMode": "swiss",
    "input": { "...": "..." },
    "moment": { "utcIso": "...", "julianDay": 0, "notes": [] },
    "planets": [],
    "houses": [],
    "aspects": [],
    "patterns": [],
    "numerology": {
      "englishGematria": {},
      "hebrewGematria": {},
      "numerology": {},
      "letterBreakdown": []
    },
    "computedAt": "..."
  }
}
```

## POST `/v1/gematria`

Name + birth date only (subset utility). Prefer full `/v1/calculate` for product flows.

## GET `/health`

Liveness + engine list.

## Auth (next)

Public calculate may be rate-limited / keyed later. Admin dashboard (`nao.nataltruth.com`) will use separate auth. Do not put admin passwords in public clients.