Questions, answered
Everything you need before your first request.
Plans, quotas, endpoint access and the difference between REST, Agent HTTP and MCP.
Why does my chart request return API 404 with a working key?
For an empty 404, check the HTTP method and path. Both POST /agent/v1/tools/generate-chart and POST /agent/v1/tools/get_chart are supported; /agent/v1/tools/generate_chart is not a route. REST clients can use GET /v3/hd-data. Keep your existing API key; changing it will not fix a missing route.
Is there a free API plan?
Yes. Free API includes 100 calls every month and access to the Creator feature set, including core charts, composites, location lookup, reference data and core agent tools.
What happens after 100 free calls?
The API returns HTTP 429 when the monthly allowance is exhausted. Your allowance resets monthly, or you can upgrade immediately for a larger quota.
Which bodygraph endpoint should I use?
Use v3/hd-data for the fullest bodygraph response. Use hd-data when you need the leanest core bodygraph chart and want it available on the Free or Creator plans.
Are Forecast and Returns available?
Yes. Startup includes planetary forecasts, transit charts, Solar Return, Lunar Return, Saturn Return, Chiron Return and progressed charts.
Does the API support celebrity search and real-time data?
Business includes celebrity search, Server-Sent Events, calendars, exports and batch chart generation. Webhooks are not part of the current public contract; reserved compatibility routes return 501 and consume no quota while durable delivery remains on the roadmap.
Are MCP and the REST API the same thing?
They use the same Human Design calculation platform but are different integration surfaces. REST exposes the full endpoint catalog; Agent HTTP and MCP expose curated tools for agent runtimes.
Why are API keys and HumanDesign.ai OAuth both supported?
API keys authorize the published calculation and reference tools and use the API plan's shared calculation quota. OAuth connects an MCP client to the member's permitted HumanDesign.ai account and workspace features. OAuth never reveals or synthesizes an API key.
How do I format a birth date and time?
Send it exactly as it read on the clock where the person was born, with no Z and no UTC offset, and give the zone separately in Timezone as an IANA identifier. Date=1990-05-15T14:30:00 with Timezone=America/New_York means half past two in the afternoon in New York. A value carrying Z or an offset does not name a wall clock time on its own, and whichever zone something reads it in changes the chart.
My integration sends Z or a UTC offset. Does it still work?
For now, yes. Those values are deprecated: the API reads them as UTC and calculates from that, and the response carries Deprecation: true and a Warning header naming the rule. They will stop being accepted, and the date will be announced in advance. Moving to a bare local wall clock time plus an IANA timezone is the safe change, and for anyone whose value did not really mean UTC it also corrects the chart.
Why was my birth time rejected as ambiguous or nonexistent?
Some wall clock times do not name a single moment. A daylight-saving jump forward skips an hour, so a time inside it never happened, and the API returns nonexistent_local_time. A jump back repeats an hour, so a time inside it happened twice, and the API returns ambiguous_local_time. A birth time in the future returns future_birth_datetime. All three are refused before any calculation unit is used, so a rejected request costs nothing.
How does the API protect calculation quality?
The API validates dates, locations, IANA timezones, and daylight-saving context before calculation. All public surfaces delegate to the same versioned calculation authority that powers HumanDesign.ai; agent clients should never approximate chart mathematics.
Where do I manage my key and usage?
API keys, membership, billing and monthly usage remain in the secure dashboard at my.humandesign.ai/api.
Can I use the API commercially?
Yes, subject to the applicable plan and terms. Choose a quota and feature tier that matches your product’s traffic and use case.