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 a full domain in 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

dotnet add package 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'];

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var loc = await roxy.Location.Search.GetAsync(c => c.QueryParameters.Q = "New York");
var city = loc!.Cities![0];

var bg = await roxy.HumanDesign.Bodygraph.PostAsync(new()
{
    Date = new Date(1990, 7, 15),
    Time = "14:30:00",
    Latitude = city.Latitude,
    Longitude = city.Longitude,
    Timezone = new() { String = city.Timezone },
});

Console.WriteLine(bg!.Type);                 // "Generator"
Console.WriteLine(bg.Strategy);              // "To Respond"
Console.WriteLine(bg.Authority);             // "Sacral"
Console.WriteLine(bg.Profile);               // "5/1"
Console.WriteLine(bg.Signature);             // "Satisfaction"
Console.WriteLine(bg.NotSelf);               // "Frustration"
Console.WriteLine(bg.Definition);            // "Single"
Console.WriteLine(bg.Centers!.Count);        // 9
Console.WriteLine(bg.Channels!.Count);       // defined channels
Console.WriteLine(bg.Gates!.Count);          // activated gates
Console.WriteLine(bg.IncarnationCross!.Name);

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. Full setup for Cursor, Claude Desktop, Antigravity, and other clients: MCP guide.

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.

Lunar node convention (`nodeType`)

Human Design charts can be built with the true (osculating) lunar node or the mean node. RoxyAPI defaults to the true node, the value professional Human Design tools such as HumanDesign.ai and Total Human Design use and the one we verify against. Some free chart calculators and general astrology tools use the mean node instead (Genetic Matrix lets you pick either).

The two agree on almost every chart. They only diverge when a node sits right on a gate boundary, where the choice can move a node gate and, in rare cases, change the type, authority, or definition. So if your output does not match a specific reference tool, that tool is most likely using the mean node. Pass nodeType to match it:

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",
    "timezone": "America/New_York",
    "nodeType": "mean"
  }'

nodeType is optional (default "true") and accepted on every Human Design endpoint that takes birth data: bodygraph, type, profile, centers, channels, gates, variables, transit, connection, and penta.

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.
Different type on another site? Check the node method, not the birth data. A type mismatch is almost always the lunar node convention. We default to the true node (the professional HD standard); pass nodeType: "mean" to match a mean-node calculator. See Lunar node convention above.
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.