API Documentation
Welcome to the Total Human Design API documentation. Our API provides programmatic access to Human Design chart calculations, Western astrology, planetary transits, an AI-powered knowledge engine, and an MCP server for AI agent integrations.
Two surfaces, one tier ladder
The API has two surfaces. The Chart API covers chart, composite, astrology, transit, and multi-chart calculations and counts against your Chart requests meter. The SAGE API answers knowledge questions and counts against your SAGE responses meter. SAGE is not a separate signup or billing system. It sits on the same tier ladder as the Chart API.
Pick the tier that covers what you need: the Chart tier for calculations only, the SAGE tier for knowledge only, or Advanced and Pro for both surfaces on a single key. Every key also includes a Free floor on both meters, and subscriptions stack. See Endpoint Access by Tier for the full table.
What's Available
| Category | Description | Endpoints |
|---|---|---|
| Human Design | Chart calculations with full planetary positions, gates, channels, centers, type, authority, profile, PHS, and Variable. Includes composite charts and astrology. | 8 endpoints |
| Transits | Moon range, all-planet transits, full transit charts, transit periods, retrograde periods, and planetary returns | 6 endpoints |
| Multi-Chart | Batch chart generation — up to 10 charts in a single request | 1 endpoint |
| SAGE API | AI-mediated knowledge engine over an ever-growing curated knowledge base spanning Human Design, Western astrology, and BaZi. Part of the tier ladder, available on the SAGE, Advanced, and Pro tiers. | 1 endpoint |
| MCP Server | Model Context Protocol server for AI agent integrations — 4 tools, 2 resources | 1 endpoint |
Quick Links
- Quickstart — Make your first API call in 3 minutes
- Authentication — API key setup and product access
- Human Design Chart — The main chart endpoint
- MCP Quickstart — Connect your AI agent to THD
- Endpoint Access by Tier — Which endpoints each tier unlocks
- Rate Limits — Request limits and meter allowances (Chart requests and SAGE responses)
- Error Codes — Standard error response format