Human Design API

Build on the same validated, versioned calculation service that powers HumanDesign.ai through REST, normalized Agent HTTP tools, and MCP. Each plan keeps its published allowance and tier-based access boundary 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. Limits match humandesignapi.com/pricing.

Free
$0/mo
Endpoints: Core Charts (v1), Relationship, Library, Location Search, Agent HTTP & MCP core
  • 100 API calls/mo
  • Complete Creator feature set
  • No credit card required
Start Free
Creator
$25/mo
Endpoints: Everything in Free + commercial use + dashboard
  • 10,000 API calls/mo
  • Commercial use
  • API dashboard & usage tracking
Select Plan
Most Popular
Startup
$50/mo
Endpoints: Everything in Creator + full v3 charts, Transits, Returns, Progressed
  • 100,000 API calls/mo
  • Full forecasts & Returns
  • Email support
Select Plan
Business
$200/mo
Endpoints: Everything in Startup + Celebrity, Batch, Calendars
  • 1,000,000 API calls/mo
  • Batch processing
  • Email + phone support
Select Plan
Enterprise
Custom
Endpoints: Full Business access across REST, Agent HTTP, and MCP + custom agreements
  • Unlimited / custom quota
  • Custom endpoints & contracts
  • 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 exposes the same validated, versioned calculation service that powers HumanDesign.ai. Use REST for direct integrations, Agent HTTP for action clients, or connect an MCP client to the canonical root endpoint.

Base URLs

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

Consuming calculation requests share one quota across REST, Agent HTTP, and MCP and use one unit only after their complete input is validated. Discovery, reference lookup, MCP initialize, ping, and tools/list consume zero units.

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——✓✓
Batch Processing——✓✓
Agent HTTP & MCP (Business tools)——✓✓

Authentication

Every request must include your API key in a header so credentials cannot leak through URLs or query logs. The account-connected MCP uses OAuth.

Header Authentication (Recommended)

X-Api-Key: your_api_key_here
Authorization: Bearer your_api_key_here

Do not place API keys in links, screenshots, analytics, or application logs.

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)
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
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

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
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
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
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
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
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
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)
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)
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
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
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

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)
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)
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)
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)

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")

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
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
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
slugOrIdstring (path)YesCelebrity slug or UUID

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