Human Design API guide

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

Human Design is a full domain in the RoxyAPI 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 (3 to 5 members)

Prerequisites

1. A RoxyAPI key. Get your API key.
2. Birth date (YYYY-MM-DD), time (HH:MM:SS), and timezone (IANA name preferred, e.g. "America/New_York"). Latitude and longitude are optional and do not change Human Design activations. Resolve the birth city to obtain its IANA timezone.
3. 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;
using Microsoft.Kiota.Abstractions; // for the Date and Time types

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 = new Time(14, 30, 0),
    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"}}'

The response includes designInstantUtc, the solved Design moment, alongside these chart fields: 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 moves a node gate. That one gate can be half of a channel, so the knock-on effect is not limited to the headline values: a center can switch between defined and open, and the channels, definition, authority or type can move with it. Profile comes from the Personality and Design Sun lines and does not change with the node convention. A node-method difference can leave the type unchanged while changing a center or channel.

When comparing charts, first match the birth date, time, timezone and Design moment. If those agree, check the node convention. Pass nodeType to match a mean-node chart:

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-surface, --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, 3 to 5 members)

POST /human-design/penta (calculatePenta) takes members[] (3 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 template

There is no HD-only template yet. The flagship astrology-ai-chatbot template covers Human Design alongside the other 17 domains via Remote MCP, browse it at /templates/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. Cache generateBodygraph using the complete birth input, node convention and response language. Recompute after a corrected birth record or changed chart options. 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. The timezone establishes the birth instant; coordinates do not alter the ecliptic-longitude activations.
• 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.
• Chart differs from another site? Match the birth instant and compare designInstantUtc, then check the node convention. A matching Design moment alone does not prove all chart inputs or calculation conventions agree. Profile follows the Sun lines, so a profile mismatch needs a birth-time or Design-moment check.
• Penta size is bounded. 3 minimum, 5 maximum members. The endpoint returns 400 for out-of-range arrays.
• Positions read directly from the NASA JPL DE440 ephemeris, 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.