Lunar Return
/lunar-returnRESTFrom StartupGenerate a Lunar Return chart for a month.
Calculate the Moon’s return to its birth position for monthly reflection and forecasting experiences.
Authentication
Use Authorization: Bearer YOUR_API_KEY or X-Api-Key. Query-key authentication is deprecated compatibility behavior on supported REST routes and is rejected on Agent HTTP and MCP surfaces. Never put credentials in URLs, request bodies, or browser code.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
Idempotency-Key | header | No | Strongly recommended stable 8–160 character key for consuming operations. Reuse it only when retrying the same request; without it, the API cannot deduplicate a lost-response retry.hdai-example-19900515 |
X-Api-Key | header | Yes | API key used by the authorization middleware.YOUR_API_KEY |
Date | query | Yes | Birth date and local wall clock time, with no Z and no UTC offset.1990-05-15T14:30:00 |
Timezone | query | Yes | IANA timezone identifier.America/New_York |
Month | query | Yes | Return month in YYYY-MM format.2026-08 |
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.
Deprecated: 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. Read the full rule.
Quota effect
A valid authorized execution uses exactly 1 calculation unit immediately before the calculation provider is reached. Invalid input, unresolved references, unsupported detail levels, and denied tiers use 0 units.
Errors
Expect 400 for invalid input, 401 for a missing or malformed key, 403 when the active plan does not include this operation, and 429 when the monthly allowance is exhausted.