Human Design API, what to build and how to call it

Ship a Human Design bodygraph reader, a type and authority coach, a profile assistant, a transit tracker, or a relationship connection report in under 30 minutes. No HD certification required.

Human Design is the May 2026 addition to the Roxy catalog. 12 endpoints covering bodygraph generation, type, profile, centers, channels, gates, variables, daily transits, two-person connection, and group penta. Built on the same Roxy Ephemeris that powers Western and Vedic astrology, verified against NASA JPL Horizons. One key.

What you can build

Bodygraph generators (type, strategy, authority, profile, defined centers, channels, gates, incarnation cross)
Type and authority coaches (Manifestor, Generator, Manifesting Generator, Projector, Reflector with their not-self themes)
Profile reading apps (6 lines, 12 profiles)
Gate and channel deep-dives (64 gates by line, 36 channels by activation)
Variables (cognition, environment, motivation, perspective, color/tone/base)
Daily transit dashboards (today activations and temporary centers per user)
Couples connection reports (electromagnetic, compromise, friendship, dominance channels)
Group penta calculator (2 to 5 members)

Prerequisites

A Roxy API key from /account.
Birth date (YYYY-MM-DD), time (HH:MM:SS), and timezone (IANA name preferred, e.g. "America/New_York"). Latitude and longitude are optional but recommended for transit precision.
For city -> lat/lng/timezone use GET /location/search. Required if your users type a city name.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

Call the endpoint

The #1 HD call is the bodygraph. One POST, all of type, strategy, authority, profile, signature, not-self theme, definition, incarnation cross, centers, channels, gates. Verified operationId: generateBodygraph.

# 1. geocode the city
curl "https://roxyapi.com/api/v2/location/search?q=New+York" \
  -H "X-API-Key: $ROXY_API_KEY"

# 2. post the bodygraph request
curl -X POST https://roxyapi.com/api/v2/human-design/bodygraph \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-07-15",
    "time": "14:30:00",
    "latitude": 40.7128,
    "longitude": -74.006,
    "timezone": "America/New_York"
  }'

import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data: loc } = await roxy.location.searchCities({ query: { q: 'New York' } });
const { latitude, longitude, timezone } = loc.cities[0];

const { data: bg } = await roxy.humanDesign.generateBodygraph({
  body: { date: '1990-07-15', time: '14:30:00', latitude, longitude, timezone },
});

console.log(bg.type);              // "Generator"
console.log(bg.strategy);          // "To Respond"
console.log(bg.authority);         // "Sacral"
console.log(bg.profile);           // "5/1"
console.log(bg.signature);         // "Satisfaction"
console.log(bg.notSelf);           // "Frustration"
console.log(bg.definition);        // "Single"
console.log(bg.centers.length);    // 9
console.log(bg.channels.length);   // count of defined channels
console.log(bg.gates.length);      // count of activated gates
console.log(bg.incarnationCross);  // { name, gates }

import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

loc = roxy.location.search_cities(q='New York')
city = loc['cities'][0]

bg = roxy.human_design.generate_bodygraph(
    date='1990-07-15', time='14:30:00', timezone=city['timezone'],
    latitude=city['latitude'], longitude=city['longitude'],
)
print(bg['type'], bg['authority'], bg['profile'])

<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$loc = $roxy->location->searchCities(q: 'New York');
$city = $loc['cities'][0];

$bg = $roxy->humanDesign->generateBodygraph(
    date: '1990-07-15',
    time: '14:30:00',
    timezone: $city['timezone'],
    latitude: $city['latitude'],
    longitude: $city['longitude'],
);
echo $bg['type'], ' ', $bg['authority'], ' ', $bg['profile'];

claude mcp add-json --scope user roxy-human-design '{"type":"http","url":"https://roxyapi.com/mcp/human-design","headers":{"X-API-Key":"YOUR_KEY"}}'
claude mcp add-json --scope user roxy-location     '{"type":"http","url":"https://roxyapi.com/mcp/location","headers":{"X-API-Key":"YOUR_KEY"}}'

Then in any MCP client: "what is the Human Design type and authority for someone born July 15 1990 at 2:30 PM in New York?" The agent geocodes the city, calls generateBodygraph, and summarizes.

The response top-level keys: type, strategy, authority, signature, notSelf, profile, definition, incarnationCross, centers, channels, gates. Use the type and authority for the headline, centers for the visual graph, gates and channels for the deep-dive sections.

Render the result

Option A: drop-in web component

<roxy-bodygraph> from @roxyapi/ui renders the full graphical bodygraph (9 centers, 36 channels, 64 gates, profile, type, authority, definition).

<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@0/dist/cdn/roxy-ui.js" defer></script>
<roxy-bodygraph id="bg"></roxy-bodygraph>
<script type="module">
  // After fetching from your backend with the SDK:
  document.getElementById('bg').data = bodygraphResponse;
</script>

The component is framework-agnostic (vanilla, React, Vue, Svelte, WordPress). Theme via CSS custom properties (--roxy-accent, --roxy-bg, --roxy-border). See the UI components page.

Option B: build your own headline

If you only need the textual summary (type + authority + profile + signature + not-self), three lines:

<dl>
  <dt>Type</dt><dd>${bg.type} (${bg.strategy})</dd>
  <dt>Authority</dt><dd>${bg.authority}</dd>
  <dt>Profile</dt><dd>${bg.profile}</dd>
  <dt>Signature / Not-self</dt><dd>${bg.signature} vs ${bg.notSelf}</dd>
</dl>

Ship the rest

Type, strategy, and authority (single-shot)

POST /human-design/type (calculateType) returns just type, strategy, authority, signature, not-self, profile. Lighter than the full bodygraph. Ideal for onboarding screens that ask for birth data and show the headline before unlocking the full graph.

Profile (1/3, 2/4, ..., 6/2)

POST /human-design/profile (calculateProfile) returns the profile, personality and design lines, and the keynote for each. Useful for profile-focused coaching content.

Centers (9 centers, defined or open)

POST /human-design/centers (calculateCenters) returns each center with defined: boolean and the activated gates within it. Plus GET /human-design/centers/{id} (getCenter) for the static catalog entry per center.

Gates (64 gates, by line)

POST /human-design/gates (calculateGates) returns the user activated gates with their lines, color, tone, base. Plus GET /human-design/gates/{number} (getGate) for the static catalog of all 64 gates by number.

Channels (36 channels)

POST /human-design/channels (calculateChannels) returns the defined channels for one user with the two gates that complete each.

Variables (cognition, environment, motivation, perspective)

POST /human-design/variables (calculateVariables) returns the four variables (PHS / cognition, design / environment, etc.) for advanced practitioners.

Daily transit (today activations)

POST /human-design/transit (generateTransit) returns today activated gates and channels plus temporary centers for the user. Pair with the bodygraph from the user record to render "what is active for you today" coaching content.

Connection (two-person)

POST /human-design/connection (calculateConnection) takes personA and personB, returns the connection report (electromagnetic, compromise, friendship, dominance channels) for partnerships, business pairings, or matchmaking.

Penta (group, 2 to 5 members)

POST /human-design/penta (calculatePenta) takes members[] (2 to 5 birth records), returns the group penta with conditioning channels. Useful for team and family dynamics apps.

See the full Human Design domain at the API Reference.

Ready-made starter

There is no HD-only starter yet. The flagship astrology-ai-chatbot starter covers Human Design alongside the other 11 domains via Remote MCP, browse it at /starters/astrology-ai-chatbot. For a custom HD-only app, the Next.js integration guide is the fastest path; combine it with <roxy-bodygraph> for the render layer.

Gotchas

Bodygraph is the one to cache per user. Birth data is immutable, so call generateBodygraph once per user and persist the result. Daily transit is the only call that changes; everything else (type, authority, profile, centers, channels, gates, variables, incarnation cross) is constant.
Timezone is required. Latitude and longitude default to 0 if omitted. For transit-driven features, pass real lat/lng so the daily activations reflect the user actual location.
IANA timezones DST-resolve against the birth date. Use "America/New_York" not -5. The server resolves to EST or EDT automatically.
Type is one of five values. Manifestor, Generator, Manifesting Generator, Projector, Reflector. Stable strings, never localized, safe to branch on.
Authority is one of seven values. Emotional, Sacral, Splenic, Ego, Self-Projected, Mental, Lunar. Stable strings.
Profile is personality/design (e.g. 5/1, 4/6). Never raw integers.
Penta size is bounded. 2 minimum, 5 maximum members. The endpoint returns 400 for out-of-range arrays.
Calculations verified against NASA JPL Horizons. Roxy Ephemeris is the same engine that backs Western and Vedic.

What to build next

The personalized tracker tutorial wires generateBodygraph + forecast timeline + numerology Life Path into a single dashboard.
The forecast guide covers transit timelines that pair with the daily HD activation.
The AI chatbot tutorial shows HD tool registration so users can ask "what is my type" in natural language.