# Generate Numerology Report (PDF or HTML)

`POST https://api.astroway.info/v1/reports/numerology`

A numerology reading as an A4 PDF (default), HTML or Markdown: Life Path, Expression, Soul Urge, Personality, Birthday and Maturity with what each position measures and the meaning of its number, the Balance number, the four pinnacles and challenges with their ages, and the personal year. Same engine and meanings as /numerology/{system}/*, five systems. The name must be in Latin letters (diacritics are dropped); any other letter is refused with 400 `NAME_NOT_LATIN` rather than counted as zero. No AI. Texts in Ukrainian or English; any other language gets the English document.

Group: Reports. Auth: `X-Api-Key` header. Operation ID: `reports_numerology`.

## Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `retain_days` | query | no | integer | How many days the PDF stays at its `url`. 1 by default; up to 90 for a link you hand to a client. Delete it sooner with `DELETE /v1/reports/files/{filename}`. |
| `format` | query | no | "pdf" \| "html" \| "markdown" | Same switch as the `format` body field (send one or the other; two different values are a 400). `pdf` stores a PDF and answers with its `url`. `html` returns one self-contained `text/html` document (inline CSS and drawings, no scripts, no external fonts; the white-label logo stays a link to your https image). `markdown` returns `text/markdown` with the same headings, text and tables, drawings left out with a one-line note. Neither html nor markdown is stored, so `retain_days` does not apply. Same price in every format. |
| `fields` | query | no | string | Comma-separated dotted paths, relative to `data`, to keep in the response. A path is applied to every element of an array, so `planets.name` means the name of each planet. Paths that match nothing come back in `_fields_unmatched`; a list where nothing matches at all is a 400, because an empty object would be a confident wrong answer. |
| `precision` | query | no | integer | Round every non-integer number in the response to this many decimal places. Integers are left alone, because an id is not a measurement. Ecliptic longitudes ship with fourteen decimals by default; 2 is about a tenth of an arcminute. |
| `Idempotency-Key` | header | no | string | Unique per logical operation, kept across retries. For 24 hours from the first request, a repeat with the same key, method, path, body and query string returns the stored response with `Idempotent-Replayed: true` and costs 0 credits. The same key with a different body or query string is a 409 `IDEMPOTENCY_KEY_REUSED`; a repeat while the first is still running is a 409 `IDEMPOTENCY_IN_PROGRESS`. Only 2xx responses are kept. See /idempotency/. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Full name in Latin letters; the letter tables hold A to Z. Diacritics are dropped, any other letter is refused with 400 NAME_NOT_LATIN. |
| `date` | string | yes |  |
| `system` | "pythagorean" \| "chaldean" \| "kabbalistic" \| "kabbalistic-strict" \| "vedic" | no | Letter table and master-number rule, as /numerology/{system}/*. Default pythagorean. |
| `year` | integer | no | Year of the personal-year chapter. Defaults to the current year (UTC). |
| `language` | "uk" \| "en" \| "de" \| "ru" \| "pl" \| "es" \| "pt" \| "hi" \| … | no |  |
| `whitelabel` | boolean \| object | no |  |
| `format` | "pdf" \| "html" \| "markdown" | no | `pdf` (default) stores a PDF and answers with its `url`. `html` returns one self-contained `text/html` document, `markdown` returns `text/markdown` with the same sections and tables; neither is stored. Same price in every format. |

```json
{
  "name": "Olena Kovalenko",
  "date": "1990-05-15",
  "system": "pythagorean",
  "year": 2027,
  "language": "uk"
}
```

## Responses

| Status | Meaning |
|---|---|
| 200 | With `format` `pdf` (default): JSON with the stored PDF `url` and its `expires_at`. With `html` or `markdown`: the document itself, nothing stored. |
| 400 | Validation error |
| 401 | Missing or invalid API key |

### Success fields, under `data`

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string | no |  |
| `storage_key` | string | no |  |
| `byte_length` | number | no |  |
| `page_count` | number | no |  |
| `duration_ms` | number | no |  |
| `expires_at` | string | no |  |

## Example

```bash
curl -X POST https://api.astroway.info/v1/reports/numerology \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Olena Kovalenko", "date": "1990-05-15", "system": "pythagorean", "year": 2027, "language": "uk" }'
```

---

Rendered from https://api.astroway.info/v1/openapi.json. HTML page: https://api.astroway.info/docs/api/operations/reports_numerology/