# 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

1. A Roxy API key from [/account](/account).
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 but recommended for transit precision.
3. For city -> lat/lng/timezone use [`GET /location/search`](/api-reference#tag/location/GET/location/search). Required if your users type a city name.

## Install


### npm
```bash
npm install @roxyapi/sdk
```

### Python
```bash
pip install roxy-sdk
```

### PHP
```bash
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`.


### curl
```bash
# 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"
  }'
```

### TypeScript SDK
```typescript
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 }
```

### Python SDK
```python
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 SDK
```php
<?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'];
```

### MCP
```bash
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`](/docs/ui) renders the full graphical bodygraph (9 centers, 36 channels, 64 gates, profile, type, authority, definition).

```html
<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](/docs/ui).

### Option B: build your own headline

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

```html
<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`](/api-reference#tag/human-design/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`](/api-reference#tag/human-design/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`](/api-reference#tag/human-design/POST/human-design/centers) (`calculateCenters`) returns each center with `defined: boolean` and the activated gates within it. Plus [`GET /human-design/centers/{id}`](/api-reference#tag/human-design/GET/human-design/centers/{id}) (`getCenter`) for the static catalog entry per center.

### Gates (64 gates, by line)

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

### Channels (36 channels)

[`POST /human-design/channels`](/api-reference#tag/human-design/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`](/api-reference#tag/human-design/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`](/api-reference#tag/human-design/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`](/api-reference#tag/human-design/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`](/api-reference#tag/human-design/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](/api-reference#tag/human-design).

## Ready-made starter

There is no HD-only starter yet. The flagship [astrology-ai-chatbot starter](https://github.com/RoxyAPI/astrology-ai-chatbot) covers Human Design alongside the other 11 domains via Remote MCP, browse it at [/starters/astrology-ai-chatbot](/starters). For a custom HD-only app, the [Next.js integration guide](/docs/integrations/nextjs) 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](/docs/tutorials/personalized-tracker) wires `generateBodygraph` + forecast timeline + numerology Life Path into a single dashboard.
- The [forecast guide](/docs/guides/forecast) covers transit timelines that pair with the daily HD activation.
- The [AI chatbot tutorial](/docs/tutorials/ai-chatbot) shows HD tool registration so users can ask "what is my type" in natural language.