---
title: "Build a calculation-fact natal report with HTML, PDF, DOCX, XLSX, ODS, EPUB, ODT, RTF, JSON, CSV, XML, NDJSON, TSV, Markdown, text, or ZIP delivery"
method: POST
path: "/api/astro/natal-report"
tags: ["Calculations"]
---

# Build a calculation-fact natal report with HTML, PDF, DOCX, XLSX, ODS, EPUB, ODT, RTF, JSON, CSV, XML, NDJSON, TSV, Markdown, text, or ZIP delivery

`POST /api/astro/natal-report`

## Request

- Base URL: `https://api.cosmicephemeris.com`
- URL: `https://api.cosmicephemeris.com/api/astro/natal-report`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Returns bounded standalone HTML and a structured fact list whose IDs link each displayed value to its chart response path. Optional embedded original SVG. Optional report_branding adds an escaped, text-only HTML co-brand with one fixed contrast-tested accent; it accepts no logo, URL, markup, template, or remote resource and is invalid with non-HTML formats. Strict include_download:true adds a deterministic base64 artifact; HTML remains the default, while download_format selects PDF, editable macro-free DOCX, editable formula-free macro-free XLSX, editable formula-free macro-free ODF 1.3 ODS, offline script-free EPUB 3, editable macro-free ODF 1.3 ODT, editable dependency-free RTF, deterministic UTF-8 JSON, deterministic RFC 4180-style UTF-8 CSV, deterministic fixed-order UTF-8 XML, deterministic one-record-per-fact UTF-8 NDJSON, deterministic escaped UTF-8 TSV, deterministic UTF-8 Markdown, deterministic UTF-8 plain text, or the predecessor ZIP with fixed HTML, PDF and calculation-JSON members. Every format has a fixed filename, byte count, media type and SHA-256. Omission/false preserves the predecessor response; no report is stored. Contains no generated interpretation, prediction, scripts, macros, formulas, customer templates or external resources. failed or timed-out admitted attempts are not refunded.
Historical mode uses an explicit BCE/CE date object and UT1 conventions. Its response is the versioned historical envelope, not the modern UTC envelope. Read result for calculation fields and metadata for limits and uncertainty.

## Request body

- union
  - NatalReportRequest
    - `birth` CalculationBirthInput, required: Strict nested birth input; no unknown properties, nulls, booleans or numeric strings. Known civil time required; semantic date/DST/undefined-angle validation occurs on the server.
      - `date` string, date, required: Valid Gregorian YYYY-MM-DD local civil date, inclusive 1800-01-01 through 2200-12-31. Calendar validity and timezone conversion are checked by the server.
      - `time` string, required: HH:MM or HH:MM:SS; no offset in this field. Use timezone to select the civil-time zone.
      - `timezone` string: Valid IANA zone; UTC when omitted. Ambiguous and nonexistent civil times are rejected.
      - `lat` number, required
      - `lon` number, required
    - `zodiac` string, nullable: tropical or sidereal; server trims whitespace and ignores case. Omitted/null selects tropical.
    - `ayanamsa` string, nullable: Sidereal supports lahiri, raman, krishnamurti, fagan_bradley, yukteshwar, sassanian, true_chitra, true_revati, true_pushya, galactic_center_0_sagittarius, galactic_alignment_mardyks, with case/whitespace normalization; other names return 400 in sidereal mode. Omitted/null selects lahiri. Tropical mode ignores a nonempty string and outputs null. This schema describes that compatibility behavior rather than claiming every string is a supported sidereal model.
    - `house_system` 'equal' | 'whole_sign' | 'placidus'
    - `theme` 'light' | 'dark' | 'monochrome'
    - `include_svg` boolean
    - `include_download` boolean: When true, response.download contains the selected deterministic artifact as strict base64 plus its fixed safe filename, byte count, media type, and SHA-256. Omission or false preserves the predecessor response.
    - `download_format` 'html' | 'pdf' | 'docx' | 'xlsx' | 'ods' | 'epub' | 'odt' | 'rtf' | 'json' | 'csv' | 'xml' | 'ndjson' | 'tsv' | 'markdown' | 'text' | 'zip': Optional only with include_download:true. Omission retains the HTML download. DOCX and XLSX are editable macro-free OOXML; XLSX contains formula-free inline-string fact rows. ODS is an editable formula-free and macro-free ODF 1.3 spreadsheet. EPUB is an offline script-free EPUB 3 publication. ODT is editable macro-free ODF 1.3 text; RTF is an editable dependency-free rich-text document; JSON, CSV, XML, NDJSON, TSV, Markdown, and text are deterministic UTF-8 fact documents. ZIP retains its fixed HTML, PDF, and calculation-JSON members.
    - `report_branding` ReportBranding: Optional text-only HTML co-brand. ASCII display name is escaped; accent selects a fixed contrast-tested palette. No logo, URL, HTML, prose template, remote resource, or non-HTML artifact is accepted.
      - `display_name` string, required
      - `accent` 'amber' | 'blue' | 'green'
  - HistoricalNatalReportRequest: Explicit historical mode, 1000 BCE (BC)–2500 CE (AD). No year zero, implicit calendar, UTC or IANA zone. Preserve tool-specific mathematical, geographic and search limits; calendar/time conventions and estimated Delta-T are not certified historical accuracy.
    - `birth` HistoricalBirthInput, required
      - `date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
        - `year` integer, required
        - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
        - `month` integer, required
        - `day` integer, required
        - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
      - `time` string, required: Explicit HH:MM[:SS]; whole seconds only, no leap seconds. Normalized helper output includes seconds.
      - `timezone` string, required: Explicit UT1 or fixed offset UT1+/-HH:MM[:SS], within 14 hours. Local clock minus offset yields UT1, not UTC. No IANA timezone inference. Original offset spelling is preserved.
      - `lat` number, required
      - `lon` number, required
    - `zodiac` string, nullable: tropical or sidereal; server trims whitespace and ignores case. Omitted/null selects tropical.
    - `ayanamsa` string, nullable: Sidereal supports lahiri, raman, krishnamurti, fagan_bradley, yukteshwar, sassanian, true_chitra, true_revati, true_pushya, galactic_center_0_sagittarius, galactic_alignment_mardyks, with case/whitespace normalization; other names return 400 in sidereal mode. Omitted/null selects lahiri. Tropical mode ignores a nonempty string and outputs null. This schema describes that compatibility behavior rather than claiming every string is a supported sidereal model.
    - `house_system` 'equal' | 'whole_sign' | 'placidus'
    - `theme` 'light' | 'dark' | 'monochrome'
    - `include_svg` boolean
    - `include_download` boolean: When true, response.download contains the selected deterministic artifact as strict base64 plus its fixed safe filename, byte count, media type, and SHA-256. Omission or false preserves the predecessor response.
    - `download_format` 'html' | 'pdf' | 'docx' | 'xlsx' | 'ods' | 'epub' | 'odt' | 'rtf' | 'json' | 'csv' | 'xml' | 'ndjson' | 'tsv' | 'markdown' | 'text' | 'zip': Optional only with include_download:true. Omission retains the HTML download. DOCX and XLSX are editable macro-free OOXML; XLSX contains formula-free inline-string fact rows. ODS is an editable formula-free and macro-free ODF 1.3 spreadsheet. EPUB is an offline script-free EPUB 3 publication. ODT is editable macro-free ODF 1.3 text; RTF is an editable dependency-free rich-text document; JSON, CSV, XML, NDJSON, TSV, Markdown, and text are deterministic UTF-8 fact documents. ZIP retains its fixed HTML, PDF, and calculation-JSON members.
    - `report_branding` ReportBranding: Optional text-only HTML co-brand. ASCII display name is escaped; accent selects a fixed contrast-tested palette. No logo, URL, HTML, prose template, remote resource, or non-HTML artifact is accepted.
      - `display_name` string, required
      - `accent` 'amber' | 'blue' | 'green'

## Response `200`

Fact-linked report.

- union
  - NatalReportResponse
    - `type` 'natal_report', required
    - `status` 'current', required
    - `format` 'html', required
    - `html` string, required
    - `facts` object[], required
    - `input` object, required
    - `metadata` object, required
    - `download` union: Present only for include_download:true. Strict base64 decodes to the selected deterministic HTML, PDF, DOCX, XLSX, ODS, EPUB, ODT, RTF, JSON, CSV, XML, NDJSON, TSV, Markdown, plain-text, or ZIP artifact; bytes and sha256 verify it. Filenames and media types are fixed. No server-side report is persisted.
      - object
        - `filename` 'cosmicephemeris-natal-report.html', required
        - `media_type` 'text/html; charset=utf-8', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.pdf', required
        - `media_type` 'application/pdf', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.docx', required
        - `media_type` 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.xlsx', required
        - `media_type` 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.ods', required
        - `media_type` 'application/vnd.oasis.opendocument.spreadsheet', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.epub', required
        - `media_type` 'application/epub+zip', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.odt', required
        - `media_type` 'application/vnd.oasis.opendocument.text', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.rtf', required
        - `media_type` 'application/rtf', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.json', required
        - `media_type` 'application/json', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.csv', required
        - `media_type` 'text/csv; charset=utf-8', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.xml', required
        - `media_type` 'application/xml', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.ndjson', required
        - `media_type` 'application/x-ndjson', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.tsv', required
        - `media_type` 'text/tab-separated-values; charset=utf-8', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.md', required
        - `media_type` 'text/markdown; charset=utf-8', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report.txt', required
        - `media_type` 'text/plain; charset=utf-8', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
      - object
        - `filename` 'cosmicephemeris-natal-report-bundle.zip', required
        - `media_type` 'application/zip', required
        - `encoding` 'base64', required
        - `bytes` integer, required
        - `sha256` string, required
        - `base64` string, required
  - HistoricalNatalReportResponse
    - `schema` 'cosmicephemeris-historical-calculation-v1', required
    - `status` 'historical', required
    - `type` 'natal-report', required
    - `input` HistoricalNatalReportRequest, required: Explicit historical mode, 1000 BCE (BC)–2500 CE (AD). No year zero, implicit calendar, UTC or IANA zone. Preserve tool-specific mathematical, geographic and search limits; calendar/time conventions and estimated Delta-T are not certified historical accuracy.
      - `birth` HistoricalBirthInput, required
        - `date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
          - `year` integer, required
          - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
          - `month` integer, required
          - `day` integer, required
          - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
        - `time` string, required: Explicit HH:MM[:SS]; whole seconds only, no leap seconds. Normalized helper output includes seconds.
        - `timezone` string, required: Explicit UT1 or fixed offset UT1+/-HH:MM[:SS], within 14 hours. Local clock minus offset yields UT1, not UTC. No IANA timezone inference. Original offset spelling is preserved.
        - `lat` number, required
        - `lon` number, required
      - `zodiac` string, nullable: tropical or sidereal; server trims whitespace and ignores case. Omitted/null selects tropical.
      - `ayanamsa` string, nullable: Sidereal supports lahiri, raman, krishnamurti, fagan_bradley, yukteshwar, sassanian, true_chitra, true_revati, true_pushya, galactic_center_0_sagittarius, galactic_alignment_mardyks, with case/whitespace normalization; other names return 400 in sidereal mode. Omitted/null selects lahiri. Tropical mode ignores a nonempty string and outputs null. This schema describes that compatibility behavior rather than claiming every string is a supported sidereal model.
      - `house_system` 'equal' | 'whole_sign' | 'placidus'
      - `theme` 'light' | 'dark' | 'monochrome'
      - `include_svg` boolean
      - `include_download` boolean: When true, response.download contains the selected deterministic artifact as strict base64 plus its fixed safe filename, byte count, media type, and SHA-256. Omission or false preserves the predecessor response.
      - `download_format` 'html' | 'pdf' | 'docx' | 'xlsx' | 'ods' | 'epub' | 'odt' | 'rtf' | 'json' | 'csv' | 'xml' | 'ndjson' | 'tsv' | 'markdown' | 'text' | 'zip': Optional only with include_download:true. Omission retains the HTML download. DOCX and XLSX are editable macro-free OOXML; XLSX contains formula-free inline-string fact rows. ODS is an editable formula-free and macro-free ODF 1.3 spreadsheet. EPUB is an offline script-free EPUB 3 publication. ODT is editable macro-free ODF 1.3 text; RTF is an editable dependency-free rich-text document; JSON, CSV, XML, NDJSON, TSV, Markdown, and text are deterministic UTF-8 fact documents. ZIP retains its fixed HTML, PDF, and calculation-JSON members.
      - `report_branding` ReportBranding: Optional text-only HTML co-brand. ASCII display name is escaped; accent selects a fixed contrast-tested palette. No logo, URL, HTML, prose template, remote resource, or non-HTML artifact is accepted.
        - `display_name` string, required
        - `accent` 'amber' | 'blue' | 'green'
    - `result` object, required: Complete historical calculation adapter result. Times are explicit UT1 date records, never UTC strings; derived times may include fractional seconds and years outside the input range.
    - `metadata` object, required
      - `time_standard` 'UT1', required
      - `historical_accuracy_certified` unknown, required
      - `warnings` string[], required

## Other responses

- `400`: Invalid request, malformed JSON, out-of-range date/location, unknown model, invalid timezone or ambiguous/nonexistent clock-change time. Invalid attempts reaching quota reservation consume one unit.
- `401`: Missing, invalid, revoked API key or unavailable activated key owner. Dashboard cookies do not authenticate calculation routes.
- `403`: Origin not allowed by production CORS policy. Server-to-server requests can omit Origin.
- `429`: Monthly quota exhausted, per-user two-request concurrency reached, or nginx rate/connection admission refused. Retry-After: 2 is sent for application per-user concurrency only, not a promise that monthly quota resets in two seconds.
- `502`: Engine unavailable, unsuccessful internal server response or invalid upstream JSON. No engine internals are exposed.
- `503`: Four-request global calculation pool full (Retry-After: 2), maintenance or upstream service unavailable.
- `504`: Application engine timeout: 15 seconds normally; planetary events, house ingresses, aspect windows, event calendar, eclipse geometry, electional search, and event-rule search use 30 seconds; Nakshatra Timeline plus the explicitly enumerated readiness, robustness, location, uncertainty, and electional-audit family use 60 seconds. Timer includes response-body parsing; an admitted timeout consumes quota.

---

[API](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api.md) · [All operations](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/revisions/f041e924cea3?raw)