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

OpenAPI 3.1 spec MCP discovery AI plugin manifest llms.txt

REST API (v1)

POST/api/v1/calculate20 / hour

Calculate a full Human Design chart (Type, Strategy, Authority, Profile, gates, channels, centers, incarnation cross) from birth data.

GET/POST/api/v1/interpret30 / hour

Get the platform's own interpretation text for a gate, channel, center, authority, profile, type or incarnation cross (7 languages).

GET/api/v1/interpret/list30 / hour

List all valid interpretation types and keys.

GET/POST/api/v1/transits15 / hour

Current planetary transits and the gates/channels they activate today.

GET/POST/api/v1/geocode60 / hour

Resolve 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.

calculate_chartgeocode_placeget_interpretationlist_interpretation_keysget_transits

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.