Developer API & MCP
HD Matrix exposes a free, public Human Design API and an MCP server — so apps, AI agents and custom GPTs can calculate bodygraphs, fetch interpretations and read transits programmatically. No API key required (IP rate-limited).
REST API (v1)
/api/v1/calculate20 / hourCalculate a full Human Design chart (Type, Strategy, Authority, Profile, gates, channels, centers, incarnation cross) from birth data.
/api/v1/interpret30 / hourGet the platform's own interpretation text for a gate, channel, center, authority, profile, type or incarnation cross (7 languages).
/api/v1/interpret/list30 / hourList all valid interpretation types and keys.
/api/v1/transits15 / hourCurrent planetary transits and the gates/channels they activate today.
/api/v1/geocode60 / hourResolve a birth city to { name, lat, lon } before calling /calculate.
Quick start
# 1) Resolve a birth city to coordinates
curl "https://hdmatrix.pro/api/v1/geocode?q=Kyiv, Ukraine"
# -> { "name": "Kyiv, Ukraine", "lat": 50.45, "lon": 30.52 }
# 2) Calculate a full Human Design chart (no API key)
curl -X POST "https://hdmatrix.pro/api/v1/calculate" \
-H "Content-Type: application/json" \
-d '{
"birth_date": "15.05.1990",
"birth_time": "10:30",
"birth_place": "Kyiv, Ukraine",
"lat": 50.45, "lng": 30.52
}'MCP server
Streamable-HTTP, JSON-RPC 2.0, protocol 2025-06-18. Endpoint: https://hdmatrix.pro/mcp. No auth.
Compatible with Claude Desktop, Cursor, Windsurf, Cline, Continue.
FAQ
Is the HD Matrix API free?
Yes. The public v1 API and the MCP server are free and require no API key. Usage is rate-limited per IP to keep the service healthy.
How do I use the API from an AI agent or custom GPT?
Import the OpenAPI 3.1 schema at https://hdmatrix.pro/openapi.json as a tool/Action, or connect the MCP server at https://hdmatrix.pro/mcp. No authentication is needed.
What is the MCP server?
A Model Context Protocol server (JSON-RPC 2.0 over Streamable-HTTP, protocol version 2025-06-18) at https://hdmatrix.pro/mcp. It exposes five tools and works with Claude Desktop, Cursor, Windsurf, Cline and Continue.
Do I need coordinates to calculate a chart?
You can pass latitude/longitude directly, or pass a birth place string — call /api/v1/geocode first to resolve a city to coordinates, then /api/v1/calculate.
What error codes does the API return?
Errors use structured JSON with a code field, e.g. RATE_LIMIT_EXCEEDED, MISSING_FIELD, GEOCODE_FAILED, plus standard HTTP status codes. Rate-limit responses include X-RateLimit-Limit and X-RateLimit-Remaining headers.