---
title: "Human Design Composite"
method: POST
path: "/human-design/composite"
tags: ["Human Design"]
---

# Human Design Composite

`POST /human-design/composite`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/human-design/composite`
- 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`

Generate a Composite / Relationship Chart.
Analyzes Electromagnetic connection scoring between two charts.

**Pricing:** 3 credits (+2 with include_visual). Available on every plan.

## Request body

- HumanDesignCompositeRequest: Request for a Relationship/Composite Chart.
  - `format` string: Response format: json | llm.
  - `include_visual` boolean: If true, a full visual SVG or PNG output will be rendered and returned alongside the chart data. Note: Visuals incur a +2 credit surcharge.
  - `subject_1` HumanDesignChartRequest, required: 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".
  - `subject_2` HumanDesignChartRequest, required: 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".
  - `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

- HumanDesignCompositeResponse: Composite / Relationship Analysis.
  - `composite_chart` HumanDesignChartData, required: The core chart data.
    - `activations` HDActivation[], required
      - `base` integer, required: Base, the third PHS deep variable: the fifth of the tone (about 0.0052 degrees). 1-5. Always present.
      - `color` integer, required: Color, the first PHS deep variable: the sixth of the line this activation falls in (0.15625 degrees). 1-6. Always present.
      - `color_label` string: Doctrinal name of this activation's Color, present only at the four Variable positions of the PHS model — the Sun and North Node in each register (and their Earth / South Node opposites, which share the identical line/color/tone/base because 180 degrees is exactly 32 gates). Personality Sun: Motivation. Design Sun: Determination, with its fixed family name ('Consecutive - Appetite'). Personality Node: Perspective. Design Node: the Environment place-type ('Markets'). Absent on every other body, and on transit activations, because Color carries no named meaning off those positions — a real coordinate with no label, not a missing value.
      - `context` string, required
      - `gate` integer, required
      - `line` integer, required
      - `planet` string, required
      - `tone` integer, required: Tone, the second PHS deep variable: the sixth of the color (about 0.026 degrees). 1-6. Always present.
      - `tone_label` string: Doctrinal name of this activation's Tone, present only at the Variable positions where Tone names something. Personality Sun: Sense. Design Sun: Cognition. Design Node: the Environment variant that qualifies color_label's place-type ('Internal', which joins it as 'Internal - Markets'). Absent on the Personality Node, whose Tone only sets arrow direction, and on every non-Variable body and transit activation.
    - `authority` string: Inner Authority, e.g. 'Emotional', 'Sacral', 'Splenic'.
    - `centers` object, required
    - `channels` HDChannel[], required
      - `centers` string[], required
      - `gates` integer[], required
      - `id` string, required
      - `name` string, required
    - `definition` string: Definition type: 'Single', 'Split', 'Triple Split', 'Quadruple Split', or 'No Definition'.
    - `design` object, required
    - `incarnation_cross` string: Named Incarnation Cross, e.g. 'Right Angle Cross of the Sphinx'.
    - `personality` object, required
    - `profile` string: Profile, e.g. '1/3', '4/6'.
    - `strategy` string: Strategy, e.g. 'To Respond', 'To Inform'.
    - `type` string: HD Type, e.g. 'Generator', 'Manifestor', 'Projector', 'Reflector', 'Manifesting Generator'.
    - `variables` HDVariables: The 4 Transformations (Color/Tone Summary).
      - `arrows` HDVariableArrows: Derived Left/Right arrow direction for each HDVariables field, computed engine-side from the same Tone values used to build HDVariables.string — avoids re-deriving direction by parsing the string's character parity.
        - `awareness` string, required: 'L' or 'R', from the Personality Sun activation — the top-right arrow, the same body and direction the bodygraph SVG draws as g.variable--awareness (data-source=personality). Before this fix it wrongly mirrored digestion (the Design Sun).
        - `digestion` string, required: 'L' or 'R', from the Design Sun activation (top-left arrow).
        - `environment` string, required: 'L' or 'R', from the Design Node activation.
        - `perspective` string, required: 'L' or 'R', from the Personality Node activation.
      - `awareness` string, required: DEPRECATED — read 'cognition' instead. Despite the name this is the Design Sun Tone label (Cognition), not the Personality Sun the SVG's awareness arrow is drawn on. Kept with its original value so existing readers do not silently change meaning.
      - `cognition` string: Design Sun Tone label (1–6): 'Smell', 'Taste', 'Outer Vision', 'Inner Vision', 'Feeling', 'Touch'. Same value as the deprecated 'awareness' field.
      - `digestion` string, required
      - `environment` string, required
      - `motivation` string: Personality Sun Color motivation, e.g. 'Fear', 'Hope', 'Desire', 'Need', 'Guilt', 'Innocence'.
      - `perspective` string, required
      - `sense` string: Personality Sun Tone label (1–6): 'Security', 'Uncertainty', 'Action', 'Meditation', 'Judgement', 'Acceptance'. Pairs with 'motivation' (the Personality Sun Colour) on the top-right arrow.
      - `string` string, required: The code, e.g. 'PLL DLL'
  - `connections` HDConnectionChannel[], required
    - `compromised_gate` integer
    - `defined_by` string, required
    - `id` string, required
    - `name` string, required
    - `type` string, required
  - `metadata` object, required
  - `summary` object, required
  - `visual` VisualResult: Embedded diagram payload returned alongside chart data when include_visual=true.
    - `content_type` string, required: MIME type of the data payload.
    - `credits_charged` integer, required: Additional credits consumed to render the visual: 2, or 0 on a re-render that presented a valid render_token.
    - `data` string, required: Raw SVG string (format=svg) or standard base64-encoded PNG bytes (format=png, no data: URI prefix).
    - `format` string, required: Output format: "svg" or "png".
    - `render_token` string: Short-lived (15 min) token for re-rendering this same chart. Send it back in the X-OE-Render-Token header (or a top-level render_token body field) with a request for the same chart inputs — e.g. the same birth data in a different theme or layout — and that request is not charged again. Bound to your account and to the chart-defining inputs; any other request is charged normally.
    - `type` string, required: Diagram kind: "wheel" or "bodygraph".

## Other responses

- `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)