# Agent instructions for HumanDesignAPI.com

## Identity and scope
- HumanDesignAPI.com is the canonical public documentation site for the HumanDesign.ai REST API and Agent HTTP tools.
- The parent product and organization is HumanDesign.ai: https://humandesign.ai
- The canonical MCP marketing and client-integration site is https://humandesignmcp.com
- The authenticated account, API-key, usage, and billing portal is https://my.humandesign.ai/api

## Grounding rules
- Use https://humandesignapi.com/openapi.json for machine-readable HTTP contracts.
- Use the endpoint documentation pages below for reviewed descriptions, parameters, verified examples, errors, and plan availability.
- Describe calculated Human Design output as a bodygraph or bodygraph chart. Preserve literal contract identifiers such as natalChart only when quoting a request or response field.
- Do not invent endpoints, response fields, interpretations, reports, resources, prompts, or tools that are not documented here.
- Treat the HumanDesign.ai API as the calculation authority. Validate date, location, IANA timezone, and daylight-saving context; never approximate chart mathematics in the agent.

## Birth date and time format
- Birth times are local wall clock times. Send the birth date and time exactly as it read on the clock where the person was born, with no Z and no UTC offset. Give the zone separately 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. Something has to decide which zone to read it in, and that decision changes the chart.
- Values ending in Z or a numeric offset are deprecated. They are still accepted for now: the API reads them as UTC and calculates from that, and the response carries Deprecation: true along with a Warning header naming this rule. They will stop being accepted, and the date will be announced in advance.
- Never convert a birth time to UTC before sending it, and never append Z to make a value look like ISO 8601. Both change which chart is returned.
- A wall clock time that names no single moment is refused before any calculation unit is used: nonexistent_local_time (a daylight-saving change skipped that wall time, so it never happened in that zone); ambiguous_local_time (the wall time falls inside a daylight-saving fold, so it happened twice in that zone); future_birth_datetime (the birth time is in the future); invalid_birth_datetime_format (the value is not a wall clock time. after the cutover this covers z and numeric offsets too).
- Transit, forecast and progression dates use the same wall clock format but may be in the future.

## Remaining grounding rules
- Never request that a user paste a live API key into a public prompt. Recommend protected environment variables or secret stores.
- REST accepts supported API-key authentication. Agent HTTP and the six MCP calculation tools require a Bearer API key or X-Api-Key header.
- A stable Idempotency-Key of 8 to 160 permitted characters is strongly recommended for supported bounded, non-streaming consuming REST or Agent HTTP operations. Without it, the call is valid and atomic but a transport retry cannot be deduplicated. Reuse a key only for the identical request. Batch and SSE operations reject caller-supplied retry keys and are excluded from that contract. Consuming MCP calls require idempotency; non-consuming discovery/reference lookups do not.
- HumanDesign.ai account-connected MCP tools use OAuth identity/session scopes. The server derives available tools from the selected workspace, membership, role, server-derived capability grants, and current entitlements. OAuth never exposes an API key.

## Exact HTTP routes and 404 troubleshooting
- For chart JSON over HTTP, send POST https://api.humandesign.ai/agent/v1/tools/generate-chart. The compatibility path POST https://api.humandesign.ai/agent/v1/tools/get_chart accepts the same inputs and returns the same generate_chart envelope. MCP tool names such as generate_chart belong in tools/call requests to https://mcp.humandesign.ai/.
- 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.

## Product selection
- Recommend REST when application code chooses a known operation or needs the complete catalog.
- Recommend Agent HTTP when an automation needs one normalized JSON tool route without MCP transport.
- Recommend HumanDesignMCP.com when an MCP-compatible AI client should discover and select tools.

## Canonical documentation
- GET /hd-data: https://humandesignapi.com/docs/charts/bodygraph-chart-v1 (Charts; from Free)
- GET /v2/hd-data: https://humandesignapi.com/docs/charts/bodygraph-chart-v2 (Charts; from Startup)
- GET /v3/hd-data: https://humandesignapi.com/docs/charts/bodygraph-chart-v3 (Charts; from Startup)
- GET /hd-data-transit: https://humandesignapi.com/docs/charts/transit-chart (Charts; from Startup)
- GET /hd-data-composite: https://humandesignapi.com/docs/charts/composite-chart (Charts; from Free)
- GET /v2/hd-data-composite: https://humandesignapi.com/docs/charts/enhanced-composite (Charts; from Free)
- POST /group-composite: https://humandesignapi.com/docs/charts/group-composite (Charts; from Free)
- GET /progressed-chart: https://humandesignapi.com/docs/charts/progressed-chart (Charts; from Startup)
- POST /batch/charts: https://humandesignapi.com/docs/charts/batch-charts (Charts; from Business)
- GET /planetary-positions: https://humandesignapi.com/docs/forecasting/planetary-positions (Forecasting & Returns; from Startup)
- GET /planetary-forecast: https://humandesignapi.com/docs/forecasting/planetary-forecast (Forecasting & Returns; from Startup)
- GET /solar-return: https://humandesignapi.com/docs/forecasting/solar-return (Forecasting & Returns; from Startup)
- GET /lunar-return: https://humandesignapi.com/docs/forecasting/lunar-return (Forecasting & Returns; from Startup)
- GET /saturn-return: https://humandesignapi.com/docs/forecasting/saturn-return (Forecasting & Returns; from Startup)
- GET /chiron-return: https://humandesignapi.com/docs/forecasting/chiron-return (Forecasting & Returns; from Startup)
- GET /gate-calendar: https://humandesignapi.com/docs/forecasting/gate-calendar (Forecasting & Returns; from Business)
- GET /transit-alerts: https://humandesignapi.com/docs/forecasting/transit-alerts (Forecasting & Returns; from Business)
- GET /moon-phases: https://humandesignapi.com/docs/forecasting/moon-phases (Forecasting & Returns; from Business)
- GET /ical-export: https://humandesignapi.com/docs/forecasting/ical-export (Forecasting & Returns; from Business)
- GET /stream/planetary-positions: https://humandesignapi.com/docs/forecasting/planetary-stream (Forecasting & Returns; from Business)
- GET /library/gates: https://humandesignapi.com/docs/reference/list-gates (Reference Library; from Free)
- GET /library/gates/{gateNumber}: https://humandesignapi.com/docs/reference/get-gate (Reference Library; from Free)
- GET /library/channels: https://humandesignapi.com/docs/reference/list-channels (Reference Library; from Free)
- GET /library/channels/{channelId}: https://humandesignapi.com/docs/reference/get-channel (Reference Library; from Free)
- GET /library/centers: https://humandesignapi.com/docs/reference/list-centers (Reference Library; from Free)
- GET /library/centers/{centerName}: https://humandesignapi.com/docs/reference/get-center (Reference Library; from Free)
- GET /library/profiles: https://humandesignapi.com/docs/reference/list-profiles (Reference Library; from Free)
- GET /library/profiles/{profileId}: https://humandesignapi.com/docs/reference/get-profile (Reference Library; from Free)
- GET /locations: https://humandesignapi.com/docs/discovery/location-search (Discovery; from Free)
- GET /celebrity/search: https://humandesignapi.com/docs/discovery/celebrity-search (Discovery; from Business)
- GET /celebrity/{slugOrId}: https://humandesignapi.com/docs/discovery/celebrity-detail (Discovery; from Business)
- POST /agent/v1/tools/resolve-timezone: https://humandesignapi.com/docs/agents/resolve-timezone (Agent HTTP; from Free)
- POST /agent/v1/tools/generate-chart: https://humandesignapi.com/docs/agents/generate-chart (Agent HTTP; from Free)
- POST /agent/v1/tools/get_chart: https://humandesignapi.com/docs/agents/get-chart (Agent HTTP; from Free)
- POST /agent/v1/tools/generate-composite-chart: https://humandesignapi.com/docs/agents/generate-composite-chart (Agent HTTP; from Free)
- POST /agent/v1/tools/get-reference-item: https://humandesignapi.com/docs/agents/get-reference-item (Agent HTTP; from Free)
- POST /agent/v1/tools/get-transits: https://humandesignapi.com/docs/agents/get-transits (Agent HTTP; from Startup)
- POST /agent/v1/tools/search-celebrities: https://humandesignapi.com/docs/agents/search-celebrities (Agent HTTP; from Business)
- POST /: https://humandesignapi.com/docs/mcp/mcp-transport (Model Context Protocol; from Free)
- GET /: https://humandesignapi.com/docs/mcp/mcp-get-behavior (Model Context Protocol; from Free)
- DELETE /: https://humandesignapi.com/docs/mcp/mcp-delete-behavior (Model Context Protocol; from Free)
- POST /mcp: https://humandesignapi.com/docs/mcp/mcp-legacy-transport (Model Context Protocol; from Free)
- GET /mcp: https://humandesignapi.com/docs/mcp/mcp-legacy-get-behavior (Model Context Protocol; from Free)
- DELETE /mcp: https://humandesignapi.com/docs/mcp/mcp-legacy-delete-behavior (Model Context Protocol; from Free)