---
title: "Human Design Bodygraph"
method: POST
path: "/visualization/bodygraph"
tags: ["visualization"]
---

# Human Design Bodygraph

`POST /visualization/bodygraph`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/visualization/bodygraph`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-OpenEphemeris-API-Key`
  - API key in header `X-API-Key`
  - API key in header `X-Service-Key`

Generates a visually premium Human Design bodygraph (SVG or PNG).

## Query parameters

- `format` string
- `size` integer
- `style` string
- `show_variables` boolean
- `show_planet_columns` boolean
- `layout` string
- `rings` string
- `house_system` string

## Request body

- HumanDesignChartRequest: Request model for a full Natal Human Design Chart. Exactly one of `birth_datetime_utc` (an instant the caller has already converted) or `birth_datetime_local` (a naive local wall-clock time the SERVER converts, using `latitude`/`longitude` and the historical-correction overlay) is required. Prefer `birth_datetime_local` for a birth time read off a certificate: only the server-side conversion can apply the pre-1970 corrections, and the Human Design design chart is cast ~88° of solar arc earlier, so an hour of error moves gates and lines on both charts.
  - `birth_datetime_local` string: Naive local wall-clock birth datetime (YYYY-MM-DDTHH:MM:SS, no zone suffix), resolved by the server. Mutually exclusive with `birth_datetime_utc` — exactly one of the two is required. The zone comes from the sibling `timezone` field when supplied, otherwise from `latitude`/`longitude`; the historical-correction overlay is consulted for pre-1970 dates. The resolution is echoed back in the response `metadata` as tz_confidence / tz_rule_source / tz_resolved_offset / resolved_utc.
  - `birth_datetime_utc` string, date-time: Birth instant as an RFC 3339 datetime, e.g. '1987-07-15T14:01:00Z'. The caller has already done the timezone math, so the historical-correction overlay does not apply. Mutually exclusive with `birth_datetime_local`.
  - `format` string: Response format: json | llm.
  - `include_chiron` boolean: Include Chiron gate mapping in the calculation.
  - `include_lilith` boolean: Include Black Moon Lilith gate mapping in the calculation.
  - `include_visual` boolean, nullable: When true, a high-fidelity Human Design bodygraph SVG/PNG is embedded in the response alongside the data payload. Adds 2 credits to the request cost.
  - `latitude` number: Birth latitude in decimal degrees. Seeds timezone resolution for `birth_datetime_local` — with `longitude` it selects the IANA zone and lets the historical-correction overlay apply — and, where the endpoint renders one, positions the mandala house ring. Not read at all when `birth_datetime_utc` is used.
  - `longitude` number: Birth longitude in decimal degrees. Seeds timezone resolution for `birth_datetime_local` — with `latitude` it selects the IANA zone and lets the historical-correction overlay apply — and, where the endpoint renders one, positions the mandala house ring. Not read at all when `birth_datetime_utc` is used.
  - `timezone` TimezoneInput: Timezone input using IANA names or UTC offsets.
    - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.
    - `iana_name` string: IANA timezone name
    - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.
    - `utc_offset` number: UTC offset in hours
  - `visual_config` VisualRenderConfig: Optional rendering preferences for inline chart visuals.
    - `format` 'svg' | 'png': Output encoding: "svg" (default) or "png". PNG requires resvg on the server.
    - `layout` 'graph' | 'mandala': Bodygraph composition: "graph" (default) is the classic layout; "mandala" nests the same diagram inside concentric rings. Ignored for wheel renders. Honored on natal and overlay (transit, connection) bodygraph paths.
    - `size` integer: Canvas pixel dimension. Range [200, 4000]. Default 800.
    - `theme` 'light' | 'dark': Colour palette: "light" (default) or "dark".

## Response `200`

Successful Response

## Other responses

- `403`: Forbidden (tier upgrade required)
- `422`: Validation Error

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)