Human Design API

Build against the HumanDesign.ai engine through legacy REST, normalized Agent HTTP tools, and MCP. All paid API tiers share the same monthly quota, with plan-based access control enforced across every surface.

Get Started with the API

Sign in and subscribe to an API plan to receive your private API key and start building.

Sign In

Choose Your Plan

Your API key works across REST, Agent HTTP, and MCP. Monthly quota is shared across billed requests on every surface.

Creator
$25/mo
Endpoints: Core Charts (v1), Relationship, Library, Location Search
  • 1,000 API calls/mo
  • Personal license
  • Community support
Select Plan
Most Popular
Startup
$50/mo
Endpoints: Everything in Creator + Enhanced Charts (v2/v3), Transit & Forecasting, Return Charts
  • 10,000 API calls/mo
  • Commercial license
  • Email support
Select Plan
Business
$200/mo
Endpoints: All endpoints including Calendar, Celebrity, Webhooks, Batch
  • 100,000 API calls/mo
  • Commercial license
  • Email + phone support
Select Plan
Enterprise
Custom
Endpoints: Full Business access across REST, Agent HTTP, and MCP + custom agreements
  • Unlimited API calls
  • Custom endpoints
  • Dedicated support
Contact Sales

API Documentation

Tier-aware reference for REST endpoints, Agent HTTP tools, and MCP access.

General
All Plans
Startup+
Business+

Introduction

The HumanDesign.ai API gives you access to the same data engine used across the HumanDesign.ai ecosystem. Use legacy REST endpoints for direct integrations, Agent HTTP tools for action clients, or connect an MCP client at /mcp for tool-based workflows.

Base URLs

https://api.humandesign.ai
https://api.humandesign.ai/agent/v1/tools/*
https://api.humandesign.ai/mcp

Billing is shared across all three surfaces. REST requests, Agent HTTP tool calls, and MCP tools/call requests each consume one API unit after entitlement checks pass. MCP initialize, ping, and tools/list do not consume usage.

Endpoint Access by Plan

CategoryCreatorStartupBusinessEnterprise
All Plans
Core Charts (v1)✓✓✓✓
Relationship Charts✓✓✓✓
Reference Library✓✓✓✓
Location Search✓✓✓✓
Agent HTTP & MCP (Creator tools)✓✓✓✓
Startup+
Enhanced Charts (v2, v3)—✓✓✓
Transit & Forecasting—✓✓✓
Return Charts—✓✓✓
Agent HTTP & MCP (Startup tools)—✓✓✓
Business+
Calendar & Scheduling——✓✓
Celebrity Database——✓✓
Webhooks & Real-time——✓✓
Batch Processing——✓✓
Agent HTTP & MCP (Business tools)——✓✓

Authentication

Every request must include your API key. Legacy REST still supports query-string auth for backwards compatibility, but Agent HTTP and MCP require headers only.

Header Authentication (Recommended)

X-Api-Key: your_api_key_here
Authorization: Bearer your_api_key_here

Query Parameter

Legacy REST only: ?api_key=your_api_key_here

Error Codes: 401 (missing key), 403 (invalid key or insufficient tier), 429 (monthly quota exceeded), 400 (bad request / invalid params).

Core Charts

GET https://api.humandesign.ai/hd-data
Upgrade to Creator to unlock
Generate Chart (v1)
Returns a complete Human Design chart with type, authority, strategy, profile, definition, and all gate activations.
ParameterTypeRequiredDescription
dateISO 8601YesBirth date & time (e.g. 1990-05-15T14:30:00)
timezonestringYesIANA timezone (e.g. America/New_York)
api_keystringYesYour API key
GET https://api.humandesign.ai/v2/hd-data
Upgrade to Startup to unlock
Enhanced Chart (v2) Startup+
Enhanced natal chart with detailed properties, expanded center and channel data.
ParameterTypeRequiredDescription
dateISO 8601YesBirth date & time
timezonestringYesIANA timezone
api_keystringYesYour API key
GET https://api.humandesign.ai/v3/hd-data
Upgrade to Startup to unlock
Full Chart (v3) Startup+
Most comprehensive chart with zodiac signs, retrograde status, gate categories, and full variable terminology.
ParameterTypeRequiredDescription
dateISO 8601YesBirth date & time
timezonestringYesIANA timezone
api_keystringYesYour API key

Relationship Charts

GET https://api.humandesign.ai/hd-data-composite
Upgrade to Creator to unlock
Composite Chart (v1)
Returns two individual charts and a merged composite showing relationship dynamics.
ParameterTypeRequiredDescription
dateISO 8601YesPerson A birth date & time
timezonestringYesPerson A timezone
date1ISO 8601YesPerson B birth date & time
timezone1stringYesPerson B timezone
api_keystringYesYour API key
GET https://api.humandesign.ai/v2/hd-data-composite
Upgrade to Creator to unlock
Enhanced Composite (v2)
Enhanced composite with chemistry scores, detailed analysis, and gate comparison.
ParameterTypeRequiredDescription
dateISO 8601YesPerson A birth date & time
timezonestringYesPerson A timezone
date1ISO 8601YesPerson B birth date & time
timezone1stringYesPerson B timezone
api_keystringYesYour API key
POST https://api.humandesign.ai/group-composite
Upgrade to Creator to unlock
Group Composite
Generate a composite chart for 3-12 people. Ideal for team analysis and group coaching.
ParameterTypeRequiredDescription
api_keystringYesYour API key (body or query)
membersarrayYesArray of {date, timezone} objects (3-12 people)

Transit & Forecasting Startup+

Overlay transiting positions on natal charts, get current planetary positions, and generate multi-day forecasts.

GET https://api.humandesign.ai/hd-data-transit
Upgrade to Startup to unlock
Transit Chart
Get a transit chart showing your natal chart overlaid with transiting planetary positions.
ParameterTypeRequiredDescription
dateISO 8601YesBirth date & time
timezonestringYesBirth timezone
TransitDateISO 8601YesTransit date & time
TransitTimezonestringYesTransit location timezone
api_keystringYesYour API key
GET https://api.humandesign.ai/planetary-positions
Upgrade to Startup to unlock
Planetary Positions
Get current planetary positions with dignity states, retrograde status, and gate activations.
ParameterTypeRequiredDescription
api_keystringYesYour API key
dateISO 8601NoDate & time (defaults to current UTC)
timezonestringNoIANA timezone (defaults to UTC)
GET https://api.humandesign.ai/planetary-forecast
Upgrade to Startup to unlock
Planetary Forecast
Daily forecast showing gate transitions over a date range (max 31 days).
ParameterTypeRequiredDescription
api_keystringYesYour API key
StartDateISO 8601YesForecast start date
EndDateISO 8601YesForecast end date (max 31 days)
timezonestringNoIANA timezone (defaults to UTC)

Return Charts Startup+

Solar, Lunar, Saturn, and Chiron returns plus secondary progressions.

GET https://api.humandesign.ai/solar-return
Upgrade to Startup to unlock
Solar Return
Chart for the exact moment the Sun returns to your natal position in a given year.
ParameterTypeRequiredDescription
dateISO 8601YesBirth date & time
timezonestringYesBirth timezone
YearintegerYesYear for the Solar Return (e.g. 2024)
api_keystringYesYour API key
GET https://api.humandesign.ai/lunar-return
Upgrade to Startup to unlock
Lunar Return
Chart for when the Moon returns to your natal Moon position in a given month.
ParameterTypeRequiredDescription
dateISO 8601YesBirth date & time
timezonestringYesBirth timezone
MonthstringYesMonth in YYYY-MM format (e.g. 2024-06)
api_keystringYesYour API key
GET https://api.humandesign.ai/saturn-return
Upgrade to Startup to unlock
Saturn Return
Saturn Return info and charts (~29, ~58 years).
ParameterTypeRequiredDescription
dateISO 8601YesBirth date & time
timezonestringYesBirth timezone
api_keystringYesYour API key
GET https://api.humandesign.ai/chiron-return
Upgrade to Startup to unlock
Chiron Return
Chiron Return info and chart (~50 years).
ParameterTypeRequiredDescription
dateISO 8601YesBirth date & time
timezonestringYesBirth timezone
api_keystringYesYour API key
GET https://api.humandesign.ai/progressed-chart
Upgrade to Startup to unlock
Progressed Chart
Secondary progressed chart showing evolution over time.
ParameterTypeRequiredDescription
dateISO 8601YesBirth date & time
timezonestringYesBirth timezone
ProgressedToISO 8601YesTarget progression date
api_keystringYesYour API key

Calendar & Scheduling Business+

Gate calendars, transit alerts, moon phases, and iCal export.

GET https://api.humandesign.ai/gate-calendar
Upgrade to Business to unlock
Gate Calendar
Monthly calendar showing daily planetary positions and gate activations.
ParameterTypeRequiredDescription
YearintegerYesCalendar year (e.g. 2024)
MonthintegerYesCalendar month (1-12)
timezonestringNoIANA timezone (defaults to UTC)
api_keystringYesYour API key
GET https://api.humandesign.ai/transit-alerts
Upgrade to Business to unlock
Transit Alerts
Personalized transit alerts for a natal chart (up to 90 days).
ParameterTypeRequiredDescription
dateISO 8601YesBirth date & time
timezonestringYesBirth timezone
DaysintegerNoDays to look ahead (default: 30, max: 90)
api_keystringYesYour API key
GET https://api.humandesign.ai/moon-phases
Upgrade to Business to unlock
Moon Phases
Monthly moon phases and daily moon gate positions.
ParameterTypeRequiredDescription
YearintegerYesCalendar year
MonthintegerYesCalendar month (1-12)
timezonestringNoIANA timezone (defaults to UTC)
api_keystringYesYour API key
GET https://api.humandesign.ai/ical-export
Upgrade to Business to unlock
iCal Export
Export transit forecast as downloadable .ics calendar file.
ParameterTypeRequiredDescription
dateISO 8601YesBirth date & time
timezonestringYesBirth timezone
DaysintegerNoDays to include (default: 30, max: 90)
api_keystringYesYour API key

Reference Library

Access the complete HD reference database — all 64 gates, 36 channels, 9 centers, and 12 profiles.

GET /library/gates
Upgrade to Creator to unlock
List All Gates
Get all 64 gates with summary information. No additional parameters required.
GET /library/gates/{gateNumber}
Upgrade to Creator to unlock
Get Gate Detail
Detailed gate info (1-64) including lines, themes, and descriptions.
ParameterTypeRequiredDescription
gateNumberinteger (path)YesGate number (1-64)
GET /library/channels
Upgrade to Creator to unlock
List All Channels
Get all 36 channels with summary information.
GET /library/channels/{channelId}
Upgrade to Creator to unlock
Get Channel Detail
Detailed channel info (e.g. "1-8").
ParameterTypeRequiredDescription
channelIdstring (path)YesChannel ID (e.g. "1-8")
GET /library/centers
Upgrade to Creator to unlock
List All Centers
Get all 9 centers with summary information.
GET /library/centers/{centerName}
Upgrade to Creator to unlock
Get Center Detail
Detailed center info (e.g. "Sacral", "G", "Solar Plexus").
ParameterTypeRequiredDescription
centerNamestring (path)YesCenter name (e.g. "Sacral")
GET /library/profiles
Upgrade to Creator to unlock
List All Profiles
Get all 12 profiles with summary information.
GET /library/profiles/{profileId}
Upgrade to Creator to unlock
Get Profile Detail
Detailed profile info (e.g. "1/3", "4-6").
ParameterTypeRequiredDescription
profileIdstring (path)YesProfile ID (e.g. "1/3" or "4-6")

Location Search

GET https://api.humandesign.ai/locations
Upgrade to Creator to unlock
Search Locations & Timezones
Search for cities by name. Returns matching locations with IANA timezone data for accurate chart calculations. Supports autocomplete-style partial queries.
ParameterTypeRequiredDescription
querystringYesCity or region to search (e.g. "London")
api_keystringYesYour API key

Webhooks & Real-time Business+

POST https://api.humandesign.ai/webhooks/subscribe
Upgrade to Business to unlock
Subscribe to Webhooks
Subscribe to transit alert webhooks for real-time notifications.
ParameterTypeRequiredDescription
api_keystringYesYour API key
urlstringYesYour webhook endpoint URL
dateISO 8601YesBirth date to monitor
timezonestringYesBirth timezone
eventsstring[]NoEvent types (e.g. gate_change)
POST https://api.humandesign.ai/webhooks/unsubscribe
Upgrade to Business to unlock
Unsubscribe from Webhooks
Unsubscribe by providing the subscription ID.
ParameterTypeRequiredDescription
api_keystringYesYour API key
subscriptionIdstringYesSubscription ID
GET https://api.humandesign.ai/webhooks/status
Upgrade to Business to unlock
Webhook Status
Check webhook subscription status.
ParameterTypeRequiredDescription
api_keystringYesYour API key
subscriptionIdstringYesSubscription ID
GET https://api.humandesign.ai/stream/planetary-positions
Upgrade to Business to unlock
SSE Planetary Stream
Stream real-time planetary positions via Server-Sent Events. Configurable update interval.
ParameterTypeRequiredDescription
api_keystringYesYour API key
intervalintegerNoUpdate interval in seconds (10-3600, default: 60)

Batch Processing Business+

POST https://api.humandesign.ai/batch/charts
Upgrade to Business to unlock
Batch Chart Generation
Generate up to 50 charts in a single request for efficient bulk processing.
ParameterTypeRequiredDescription
api_keystringYesYour API key (body or query)
chartsarrayYesArray of {id?, date, timezone} objects (max 50)

Celebrity Database Business+

Search and retrieve Human Design chart data for celebrities.

GET https://api.humandesign.ai/celebrity/search
Upgrade to Business to unlock
Search Celebrities
Search by name. Returns matching results with basic chart data.
ParameterTypeRequiredDescription
api_keystringYesYour API key
querystringYesSearch query (name)
limitintegerNoMax results (default: 20, max: 100)
GET https://api.humandesign.ai/celebrity/{slugOrId}
Upgrade to Business to unlock
Get Celebrity Detail
Full celebrity details by slug (e.g. "elon-musk") or UUID.
ParameterTypeRequiredDescription
api_keystringYesYour API key
slugOrIdstring (path)YesCelebrity slug or UUID

Need help? Contact our API team at [email protected]