API documentation
The Total Human Design API provides programmatic access to Human Design chart calculations, Western astrology, planetary transits, a 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 your needs: 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 includes a Free floor on both meters, and subscriptions stack. See Endpoint access by tier for the full table.
Available capabilities
| 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 a 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.
- Integrated before June 2026? Older endpoint paths still work. See Legacy & compatibility.