HDAI API: Complete Reference

Human Design AI API — Complete Reference

The HDAI API is a RESTful service built on ASP.NET Core that calculates Human Design bodygraph charts using the Swiss Ephemeris. It powers chart generation, transit tracking, calendar features, and the reference library across all HDAI applications.

Base URL: Hosted on Railway. All endpoints accept query parameters unless noted otherwise. Authentication is via the api_key query parameter on every request.

Authentication

Every request requires a valid api_key parameter. Include it as a query string parameter:

GET /hd-data?api_key=YOUR_KEY&date=1990-05-15T14:30:00&timezone=America/New_York

Common Parameters

Parameter	Type	Description
api_key	string (required)	Your API key for authentication
date	DateTime (required)	Birth date/time in ISO 8601 format: YYYY-MM-DDTHH:MM:SS
timezone	string (required)	IANA timezone identifier (e.g., America/New_York, Europe/London, Asia/Tokyo)

Chart Generation Endpoints

GET /hd-data

Generate a personal Human Design bodygraph chart (v1 format).

Parameter	Type	Required	Description
api_key	string	Yes	API key
date	DateTime	Yes	Birth date/time in ISO 8601
timezone	string	Yes	IANA timezone for birth location

Returns: Full bodygraph chart data including Type, Strategy, Authority, Profile, defined centers, gates (with planetary activations), channels, and properties.

GET /v2/hd-data

Generate a personal Human Design chart (v2 format with structured property IDs).

Same parameters as /hd-data. Returns chart data with structured IDs for Type, Profile, etc., making it easier to programmatically process.

GET /v3/hd-data

Generate a personal Human Design chart (v3 format — latest and most detailed).

Same parameters as /hd-data. Enhanced response includes:

• Zodiac sign for each planetary position
• Retrograde status for each planet
• Gate categories (personality vs. design activation)
• Full variable terminology

GET /hd-data-composite

Generate a composite (relationship) chart comparing two people.

Parameter	Type	Required	Description
api_key	string	Yes	API key
date	DateTime	Yes	First person’s birth date/time
timezone	string	Yes	First person’s birth timezone
date1	DateTime	Yes	Second person’s birth date/time
timezone1	string	Yes	Second person’s birth timezone

Returns: Three objects — Person 0’s chart, Person 1’s chart, and the Combined composite showing electromagnetic channels, companion channels, compromise channels, and dominant channels.

GET /v2/hd-data-composite

Enhanced composite chart with detailed relationship analysis (v2).

Same parameters as /hd-data-composite. Enhanced response includes chemistry scores, gate-by-gate comparison, and detailed relationship dynamics analysis.

POST /group-composite

Generate a group composite chart for 3–12 people.

Request Body (JSON):

{
  "api_key": "YOUR_KEY",
  "members": [
    { "name": "Alice", "date": "1990-05-15T14:30:00", "timezone": "America/New_York" },
    { "name": "Bob", "date": "1988-03-22T08:00:00", "timezone": "Europe/London" },
    { "name": "Carol", "date": "1995-11-10T20:45:00", "timezone": "Asia/Tokyo" }
  ]
}

Returns: Group composite analysis with shared gates, channels, chemistry scores, and individual chart summaries. Minimum 3, maximum 12 members.

POST /batch/charts

Generate multiple individual charts in a single request (max 50).

Request Body (JSON):

{
  "api_key": "YOUR_KEY",
  "version": "v3",
  "charts": [
    { "id": "person-1", "date": "1990-05-15T14:30:00", "timezone": "America/New_York" },
    { "id": "person-2", "date": "1988-03-22T08:00:00", "timezone": "Europe/London" }
  ]
}

Field	Type	Description
version	string	Chart version: v1, v2, or v3 (default: v3)
charts[].id	string	Optional custom identifier for each chart
charts[].date	DateTime	Birth date/time
charts[].timezone	string	IANA timezone

Returns: Array of results (each with success/error status and chart data), plus summary statistics including Type distribution, Profile distribution, most common gates, and processing time.

Transit & Forecast Endpoints

GET /hd-data-transit

Generate a transit chart overlaying current (or specified) planetary positions on a natal chart.

Parameter	Type	Required	Description
api_key	string	Yes	API key
date	DateTime	Yes	Natal birth date/time
timezone	string	Yes	Natal birth timezone
transitDate	DateTime	Yes	Transit date/time to overlay
transitTimezone	string	Yes	Timezone for transit location (your current location)

Returns: Transit chart showing which transiting gates and channels are activating your natal chart, with channel activation details and gate overlays.

GET /planetary-positions

Get current (or specified) planetary positions with dignity states and gate activations.

Parameter	Type	Required	Description
api_key	string	Yes	API key
date	DateTime	No	Date/time (defaults to current UTC)
timezone	string	No	Timezone (defaults to UTC)

Returns: All planetary positions with gate number, line, zodiac sign, and retrograde status for Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, South Node, and Chiron.

GET /planetary-forecast

Get a multi-day planetary forecast showing daily gate activations and transitions.

Parameter	Type	Required	Description
api_key	string	Yes	API key
startDate	DateTime	Yes	Forecast start date
endDate	DateTime	Yes	Forecast end date (max 31 days from start)
timezone	string	No	Timezone (defaults to UTC)

Returns: Daily planetary positions, gate transitions (when a planet moves from one gate to another), and forecast summary for the period.

Calendar Endpoints

GET /gate-calendar

Get a monthly gate activation calendar showing daily planetary positions.

Parameter	Type	Required	Description
api_key	string	Yes	API key
year	int	Yes	Calendar year (1900–2100)
month	int	Yes	Calendar month (1–12)
timezone	string	No	Timezone (default: UTC)

Returns: For each day of the month: planetary positions with gate/line/sign/retrograde, active gates, active channels, gate changes. Plus a summary of most active gates, total gate changes, and significant dates.

GET /transit-alerts

Get personalized transit alerts based on your natal chart.

Parameter	Type	Required	Description
api_key	string	Yes	API key
date	DateTime	Yes	Your birth date/time
timezone	string	Yes	Your birth timezone
days	int	No	Days to forecast (default: 30, max: 90)

Returns: List of alerts categorized by type (ChannelCompletion, SunGateChange, NewMoon, FullMoon, Retrograde) with severity level (High/Medium/Low), title, description, and details (planet, gates involved, channel formed). Includes summary with high-priority count and upcoming highlights.

GET /moon-phases

Get moon phases and daily moon gate positions for a month.

Parameter	Type	Required	Description
api_key	string	Yes	API key
year	int	Yes	Calendar year (1900–2100)
month	int	Yes	Calendar month (1–12)
timezone	string	No	Timezone (default: UTC)

Returns: Moon phases (New Moon, First Quarter, Full Moon, Last Quarter) with gate/line/sign for each phase. Daily moon positions with gate, line, sign, phase description (e.g., Waxing Crescent), and illumination percentage. Summary includes next New/Full Moon and total moon gate changes.

GET /ical-export

Export transit forecast as a downloadable iCal (.ics) calendar file.

Parameter	Type	Required	Description
api_key	string	Yes	API key
date	DateTime	Yes	Your birth date/time
timezone	string	Yes	Your birth timezone
days	int	No	Days to include (default: 30, max: 90)

Returns: A .ics file download (text/calendar content type) that can be imported into Google Calendar, Apple Calendar, Outlook, etc.

Return & Progressed Chart Endpoints

GET /solar-return

Calculate your Solar Return chart for a specific year (annual birthday chart).

Parameter	Type	Required	Description
api_key	string	Yes	API key
date	DateTime	Yes	Your birth date/time
timezone	string	Yes	Your birth timezone
year	int	Yes	Target year (1900–2100)

Returns: Solar Return date/time, chart Type/Definition/Authority/Profile, planetary positions, active gates and channels, defined centers, and a Year Theme (main theme, Sun/Earth gate focus, key channels, year highlights).

GET /lunar-return

Calculate your Lunar Return chart for a specific month.

Parameter	Type	Required	Description
api_key	string	Yes	API key
date	DateTime	Yes	Your birth date/time
timezone	string	Yes	Your birth timezone
month	string	Yes	Target month in YYYY-MM format (e.g., 2024-06)

Returns: Lunar Return date/time, chart Type/Profile, planetary positions, active gates and channels, and Month Theme (main theme, Moon gate focus, emotional tone, month highlights).

GET /saturn-return

Calculate your Saturn Return dates and charts (occurs ~every 29.5 years).

Parameter	Type	Required	Description
api_key	string	Yes	API key
date	DateTime	Yes	Your birth date/time
timezone	string	Yes	Your birth timezone

Returns: Natal Saturn position (gate, line, sign), list of return events (1st ~29, 2nd ~58, 3rd ~87) each with approximate date/age, whether it has occurred, and chart data. Also includes Saturn Return Meaning with gate theme, life lesson, maturity challenge, and key questions for reflection.

GET /chiron-return

Calculate your Chiron Return date and chart (occurs ~age 50–51).

Parameter	Type	Required	Description
api_key	string	Yes	API key
date	DateTime	Yes	Your birth date/time
timezone	string	Yes	Your birth timezone

Returns: Natal Chiron position, return event with approximate date/age and chart data, and Chiron Return Meaning with wound theme, healing path, wisdom gift, and reflection questions.

GET /progressed-chart

Calculate a Secondary Progressed chart (1 day of life = 1 year of progression).

Parameter	Type	Required	Description
api_key	string	Yes	API key
date	DateTime	Yes	Your birth date/time
timezone	string	Yes	Your birth timezone
progressedTo	DateTime	Yes	Date to progress to (must be after birth date)

Returns: Progressed chart Type/Definition/Authority/Profile, comparison with natal Type/Profile, a Changes object detailing whether Type/Profile/Authority changed, new gate activations, new channel activations, new defined centers, and a summary. Also returns full progressed planetary positions, active gates, channels, and defined centers.

Celebrity Endpoints

GET /celebrity/search

Search for celebrity Human Design charts by name.

Parameter	Type	Required	Description
api_key	string	Yes	API key
query	string	Yes	Search term (name)
limit	int	No	Max results (default: 20, max: 100)

Returns: List of matching celebrities from the Supabase database with chart information.

GET /celebrity/{slugOrId}

Get a specific celebrity’s chart data by slug or numeric ID.

Parameter	Type	Required	Description
api_key	string	Yes	API key (query param)
slugOrId	string	Yes	Celebrity slug (e.g., elon-musk) or numeric ID (path param)

Returns: Celebrity data including birth information and Human Design chart details.

Location Search

GET /locations

Search for birth locations (city/timezone lookup).

Parameter	Type	Required	Description
query	string	Yes	City or location name to search

Returns: List of matching cities with timezone information for use in chart generation.

Library Reference Endpoints

All library endpoints are prefixed with /library.

GET /library/gates

Get all 64 Human Design gates with summary information.

Returns: List of all gates with basic details including gate number, name, center, and theme.

GET /library/gates/{gateNumber}

Get detailed information for a specific gate (1–64).

Returns: Complete gate information including I Ching correlation, Gene Keys connection, all 6 line descriptions, associated center, and theme.

GET /library/channels

Get all 36 Human Design channels with summary information.

Returns: List of all channels with basic details including connecting gates, centers, and circuit.

GET /library/channels/{channelId}

Get detailed information for a specific channel.

Parameter	Type	Description
channelId	string	Channel identifier, e.g., 1-8 or 8-1 (either direction works)

Returns: Complete channel information including both gates, connecting centers, circuit, and theme.

GET /library/centers

Get all 9 Human Design centers with summary information.

Returns: List of all centers with basic details including biological correlation and associated gates.

GET /library/centers/{centerName}

Get detailed information for a specific center.

Parameter	Type	Description
centerName	string	Center name: Head, Ajna, Throat, G, Heart, Sacral, Solar Plexus, Spleen, Root

Returns: Complete center information including gates belonging to this center, biological correlation, defined/open themes, and not-self theme.

GET /library/profiles

Get all 12 Human Design profiles with summary information.

Returns: List of all profiles (1/3, 1/4, 2/4, 2/5, 3/5, 3/6, 4/6, 4/1, 5/1, 5/2, 6/2, 6/3) with basic details.

GET /library/profiles/{profileId}

Get detailed information for a specific profile.

Parameter	Type	Description
profileId	string	Profile identifier: 1/3, 4-6, or 51 (various formats accepted)

Returns: Complete profile information including characteristics, strategy, strengths, and life theme.

Webhook & Streaming Endpoints

POST /webhooks/subscribe

Subscribe to receive transit alert notifications via webhook.

Request Body (JSON):

{
  "api_key": "YOUR_KEY",
  "callbackUrl": "https://your-server.com/webhook",
  "natalDate": "1990-05-15T14:30:00",
  "timezone": "America/New_York",
  "alertTypes": ["channel_completion", "sun_gate_change", "moon_phase", "retrograde"],
  "secret": "optional-signing-secret"
}

Field	Type	Required	Description
callbackUrl	string (URL)	Yes	URL to receive POST notifications
natalDate	DateTime	Yes	Birth date to track transits for
timezone	string	Yes	IANA timezone
alertTypes	string[]	No	Types: channel_completion, sun_gate_change, moon_phase, retrograde. Default: channel_completion + sun_gate_change
secret	string	No	Secret key for signing webhook payloads

Returns: Subscription confirmation with subscriptionId, status, alert types, created/expires timestamps.

POST /webhooks/unsubscribe

Unsubscribe from webhook notifications.

Request Body (JSON):

{
  "api_key": "YOUR_KEY",
  "subscriptionId": "sub_abc123"
}

GET /webhooks/status

Check the status of a webhook subscription.

Parameter	Type	Required	Description
api_key	string	Yes	API key
subscriptionId	string	Yes	The subscription ID to check

Returns: Full subscription details or 404 if not found.

Webhook Payload Format

When a transit event occurs, the API sends a POST request to your callback URL:

{
  "eventId": "evt_abc123",
  "eventType": "transit_alert",
  "timestamp": "2024-06-15T12:00:00Z",
  "subscriptionId": "sub_abc123",
  "data": {
    "alertType": "channel_completion",
    "title": "Channel 1-8 Activated",
    "description": "Transit Sun in Gate 1 completes your natal Gate 8...",
    "date": "2024-06-15",
    "details": { ... }
  }
}

GET /stream/planetary-positions

Stream real-time planetary positions via Server-Sent Events (SSE).

Parameter	Type	Required	Description
api_key	string	Yes	API key
interval	int	No	Update interval in seconds (min: 10, max: 3600, default: 60)

Returns: A Server-Sent Events stream. Each event contains:

• event: planetary-update
• data: JSON with planets (each with gate, line, sign, retrograde status) and highlights (current Sun gate, Moon gate, active channels, retrograde planets)

Connect with an EventSource client. The stream continues until the client disconnects.

Error Handling

All endpoints return standard HTTP status codes:

Code	Meaning
200	Success
400	Bad Request — invalid parameters (timezone format, date range, etc.)
404	Not Found — resource doesn’t exist (celebrity, subscription, library item)
500	Internal Server Error — calculation or server failure

Error responses include a JSON object with error and optional message fields:

{ "error": "time zone not properly formatted" }

Technical Details

• Calculation Engine: Swiss Ephemeris (SwissEphNet) for astronomical calculations
• Database: Supabase (PostgreSQL) for celebrity data and persistent storage
• Deployment: Railway (Docker container)
• Response Format: All responses use capitalized property names (custom JSON naming policy)
• Date Format: All dates in ISO 8601 format (YYYY-MM-DDTHH:MM:SS)
• Timezone Format: IANA timezone identifiers only (e.g., America/New_York, not EST or UTC-5)