{"openapi":"3.1.0","info":{"title":"AsterNym reading API","version":"1.2.0","summary":"Birth-chart readings, BaZi, numerology and zodiac engines for AI agents and the people they work for.","description":"Public, read-only, keyless. No site-owner approval, account or key is required; that permission covers nothing involving private data, payments or account state, and nothing about an agent's obligations to its own human. Same engine as every page on asternym.com. Not cached: every call counts toward the fair-use limit of 60 a minute per address, which is shared across every endpoint here. Prefer POST so birth details stay out of URLs and access logs. The same tools are available over MCP at https://asternym.com/mcp (streamable HTTP, no key). Terms are returned inside every response and at https://asternym.com/for-agents.","contact":{"url":"https://asternym.com/for-agents"}},"servers":[{"url":"https://asternym.com"}],"paths":{"/api/v1/reading":{"get":{"operationId":"getReading","summary":"A whole reading from a birth date, and optionally a time and place. Inputs travel in the URL; use POST to keep them out of access logs.","description":"Sun sign, Chinese animal and element, BaZi day master and pillars, Life Path and the AsterNym identity, from the same engine as every page on the site.","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Local civil date, YYYY-MM-DD. Required."},{"name":"time","in":"query","required":false,"schema":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"description":"Local clock time, HH:MM. Omit if unknown; nothing is assumed and noon is never substituted."},{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90},"description":"Decimal degrees."},{"name":"lng","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180},"description":"Decimal degrees."},{"name":"tz","in":"query","required":false,"schema":{"type":"string"},"description":"IANA time zone, e.g. Asia/Singapore. Required when lat and lng are given."},{"name":"agent","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"Optional: the name of the agent or product calling. Logged for usage counts; never required, never verified."}],"responses":{"200":{"description":"A whole reading from a birth date, and optionally a time and place.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reading"}}}},"400":{"description":"A field was missing or malformed. The body says which, and points at the docs."},"429":{"description":"Fair-use limit: more than 60 requests a minute from one address, counted across servers and shared by every /api/v1 endpoint. Retry-After says how long to wait. Never cached."}}},"post":{"operationId":"postReading","summary":"A whole reading from a birth date, and optionally a time and place. Recommended over GET: the details then stay out of hosting and CDN access logs.","description":"Sun sign, Chinese animal and element, BaZi day master and pillars, Life Path and the AsterNym identity, from the same engine as every page on the site.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date","description":"Local civil date, YYYY-MM-DD. Required."},"time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"Local clock time, HH:MM. Omit if unknown; nothing is assumed and noon is never substituted."},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Decimal degrees."},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Decimal degrees."},"tz":{"type":"string","description":"IANA time zone, e.g. Asia/Singapore. Required when lat and lng are given."},"agent":{"type":"string","maxLength":80,"description":"Optional: the name of the agent or product calling. Logged for usage counts; never required, never verified."}}}}}},"responses":{"200":{"description":"A whole reading from a birth date, and optionally a time and place.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reading"}}}},"400":{"description":"A field was missing or malformed. The body says which, and points at the docs."},"429":{"description":"Fair-use limit: more than 60 requests a minute from one address, counted across servers and shared by every /api/v1 endpoint. Retry-After says how long to wait. Never cached."}}}},"/api/v1/bazi":{"get":{"operationId":"getBazi","summary":"The BaZi Four Pillars alone, with hidden stems and ten gods. Inputs travel in the URL; use POST to keep them out of access logs.","description":"Pillars, day master, hidden stems (藏干) with their ten gods (十神), element counts, dominant and missing elements, na yin, the twelve stages and the void branches. The year turns at Li Chun, not at 1 January or Lunar New Year. Without a time there is no hour pillar and the response says so.","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Local civil date, YYYY-MM-DD. Required."},{"name":"time","in":"query","required":false,"schema":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"description":"Local clock time, HH:MM. Omit if unknown; nothing is assumed and noon is never substituted."},{"name":"tz","in":"query","required":false,"schema":{"type":"string"},"description":"IANA time zone, e.g. Asia/Singapore. Required when lat and lng are given."},{"name":"sexCategory","in":"query","required":false,"schema":{"type":"string","enum":["F","M","both"]},"description":"Echoed back. Only the luck-pillar cycle reads it, and this endpoint does not return luck pillars."},{"name":"agent","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"Optional: the name of the agent or product calling. Logged for usage counts; never required, never verified."}],"responses":{"200":{"description":"The BaZi Four Pillars alone, with hidden stems and ten gods.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResult"}}}},"400":{"description":"A field was missing or malformed. The body says which, and points at the docs."},"429":{"description":"Fair-use limit: more than 60 requests a minute from one address, counted across servers and shared by every /api/v1 endpoint. Retry-After says how long to wait. Never cached."}}},"post":{"operationId":"postBazi","summary":"The BaZi Four Pillars alone, with hidden stems and ten gods. Recommended over GET: the details then stay out of hosting and CDN access logs.","description":"Pillars, day master, hidden stems (藏干) with their ten gods (十神), element counts, dominant and missing elements, na yin, the twelve stages and the void branches. The year turns at Li Chun, not at 1 January or Lunar New Year. Without a time there is no hour pillar and the response says so.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date","description":"Local civil date, YYYY-MM-DD. Required."},"time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"Local clock time, HH:MM. Omit if unknown; nothing is assumed and noon is never substituted."},"tz":{"type":"string","description":"IANA time zone, e.g. Asia/Singapore. Required when lat and lng are given."},"sexCategory":{"type":"string","enum":["F","M","both"],"description":"Echoed back. Only the luck-pillar cycle reads it, and this endpoint does not return luck pillars."},"agent":{"type":"string","maxLength":80,"description":"Optional: the name of the agent or product calling. Logged for usage counts; never required, never verified."}}}}}},"responses":{"200":{"description":"The BaZi Four Pillars alone, with hidden stems and ten gods.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResult"}}}},"400":{"description":"A field was missing or malformed. The body says which, and points at the docs."},"429":{"description":"Fair-use limit: more than 60 requests a minute from one address, counted across servers and shared by every /api/v1 endpoint. Retry-After says how long to wait. Never cached."}}}},"/api/v1/bazi/hours":{"get":{"operationId":"getBaziHours","summary":"Every BaZi double-hour of one civil date, optionally ranked by element. Inputs travel in the URL; use POST to keep them out of access logs.","description":"The twelve 時辰 of a day, each with its hour pillar, hidden stems, ten god and the element counts of the whole chart at that hour. The 23:00-00:00 slot is returned separately as lateZi: from 23:00 the hour pillar has already turned to the next day's 子 (早子時) while the day pillar has not, so it differs from the 00:00-01:00 slot on the same date. These are the Chinese double-hours, not the Western planetary hours.","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Local civil date, YYYY-MM-DD. Required."},{"name":"tz","in":"query","required":false,"schema":{"type":"string"},"description":"IANA time zone, e.g. Asia/Singapore. Required when lat and lng are given."},{"name":"element","in":"query","required":false,"schema":{"type":"string","enum":["Wood","Fire","Earth","Metal","Water"]},"description":"Optional: rank the hours by how much of this element the chart carries."},{"name":"agent","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"Optional: the name of the agent or product calling. Logged for usage counts; never required, never verified."}],"responses":{"200":{"description":"Every BaZi double-hour of one civil date, optionally ranked by element.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResult"}}}},"400":{"description":"A field was missing or malformed. The body says which, and points at the docs."},"429":{"description":"Fair-use limit: more than 60 requests a minute from one address, counted across servers and shared by every /api/v1 endpoint. Retry-After says how long to wait. Never cached."}}},"post":{"operationId":"postBaziHours","summary":"Every BaZi double-hour of one civil date, optionally ranked by element. Recommended over GET: the details then stay out of hosting and CDN access logs.","description":"The twelve 時辰 of a day, each with its hour pillar, hidden stems, ten god and the element counts of the whole chart at that hour. The 23:00-00:00 slot is returned separately as lateZi: from 23:00 the hour pillar has already turned to the next day's 子 (早子時) while the day pillar has not, so it differs from the 00:00-01:00 slot on the same date. These are the Chinese double-hours, not the Western planetary hours.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date","description":"Local civil date, YYYY-MM-DD. Required."},"tz":{"type":"string","description":"IANA time zone, e.g. Asia/Singapore. Required when lat and lng are given."},"element":{"type":"string","enum":["Wood","Fire","Earth","Metal","Water"],"description":"Optional: rank the hours by how much of this element the chart carries."},"agent":{"type":"string","maxLength":80,"description":"Optional: the name of the agent or product calling. Logged for usage counts; never required, never verified."}}}}}},"responses":{"200":{"description":"Every BaZi double-hour of one civil date, optionally ranked by element.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResult"}}}},"400":{"description":"A field was missing or malformed. The body says which, and points at the docs."},"429":{"description":"Fair-use limit: more than 60 requests a minute from one address, counted across servers and shared by every /api/v1 endpoint. Retry-After says how long to wait. Never cached."}}}},"/api/v1/numerology":{"get":{"operationId":"getNumerology","summary":"Life Path and birthday number, plus the name numbers when a name is sent. Inputs travel in the URL; use POST to keep them out of access logs.","description":"Pythagorean numerology: Life Path, birthday number and its components, and with a name the expression, soul urge, personality, cornerstone, capstone and hidden passion. Master numbers are kept where the position allows.","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Local civil date, YYYY-MM-DD. Required."},{"name":"name","in":"query","required":false,"schema":{"type":"string","maxLength":120},"description":"Optional given name. Without it the name numbers are omitted rather than guessed. Used and discarded; never stored."},{"name":"surname","in":"query","required":false,"schema":{"type":"string","maxLength":120},"description":"Optional surname, used with the given name where the method uses the full name."},{"name":"agent","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"Optional: the name of the agent or product calling. Logged for usage counts; never required, never verified."}],"responses":{"200":{"description":"Life Path and birthday number, plus the name numbers when a name is sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResult"}}}},"400":{"description":"A field was missing or malformed. The body says which, and points at the docs."},"429":{"description":"Fair-use limit: more than 60 requests a minute from one address, counted across servers and shared by every /api/v1 endpoint. Retry-After says how long to wait. Never cached."}}},"post":{"operationId":"postNumerology","summary":"Life Path and birthday number, plus the name numbers when a name is sent. Recommended over GET: the details then stay out of hosting and CDN access logs.","description":"Pythagorean numerology: Life Path, birthday number and its components, and with a name the expression, soul urge, personality, cornerstone, capstone and hidden passion. Master numbers are kept where the position allows.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date","description":"Local civil date, YYYY-MM-DD. Required."},"name":{"type":"string","maxLength":120,"description":"Optional given name. Without it the name numbers are omitted rather than guessed. Used and discarded; never stored."},"surname":{"type":"string","maxLength":120,"description":"Optional surname, used with the given name where the method uses the full name."},"agent":{"type":"string","maxLength":80,"description":"Optional: the name of the agent or product calling. Logged for usage counts; never required, never verified."}}}}}},"responses":{"200":{"description":"Life Path and birthday number, plus the name numbers when a name is sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResult"}}}},"400":{"description":"A field was missing or malformed. The body says which, and points at the docs."},"429":{"description":"Fair-use limit: more than 60 requests a minute from one address, counted across servers and shared by every /api/v1 endpoint. Retry-After says how long to wait. Never cached."}}}},"/api/v1/zodiac":{"get":{"operationId":"getZodiac","summary":"Both zodiacs: the Western sun sign and the Chinese animal. Inputs travel in the URL; use POST to keep them out of access logs.","description":"The Sun's sign from its apparent ecliptic longitude, with a cusp reported rather than resolved by assuming noon, and the Chinese animal, element and polarity with the Lunar New Year boundary. Note the two calendars differ on purpose: the Chinese year here turns at Lunar New Year, while the BaZi year pillar turns at Li Chun.","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Local civil date, YYYY-MM-DD. Required."},{"name":"time","in":"query","required":false,"schema":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"description":"Local clock time, HH:MM. Omit if unknown; nothing is assumed and noon is never substituted."},{"name":"tz","in":"query","required":false,"schema":{"type":"string"},"description":"IANA time zone, e.g. Asia/Singapore. Required when lat and lng are given."},{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90},"description":"Decimal degrees."},{"name":"lng","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180},"description":"Decimal degrees."},{"name":"agent","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"Optional: the name of the agent or product calling. Logged for usage counts; never required, never verified."}],"responses":{"200":{"description":"Both zodiacs: the Western sun sign and the Chinese animal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResult"}}}},"400":{"description":"A field was missing or malformed. The body says which, and points at the docs."},"429":{"description":"Fair-use limit: more than 60 requests a minute from one address, counted across servers and shared by every /api/v1 endpoint. Retry-After says how long to wait. Never cached."}}},"post":{"operationId":"postZodiac","summary":"Both zodiacs: the Western sun sign and the Chinese animal. Recommended over GET: the details then stay out of hosting and CDN access logs.","description":"The Sun's sign from its apparent ecliptic longitude, with a cusp reported rather than resolved by assuming noon, and the Chinese animal, element and polarity with the Lunar New Year boundary. Note the two calendars differ on purpose: the Chinese year here turns at Lunar New Year, while the BaZi year pillar turns at Li Chun.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date","description":"Local civil date, YYYY-MM-DD. Required."},"time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"Local clock time, HH:MM. Omit if unknown; nothing is assumed and noon is never substituted."},"tz":{"type":"string","description":"IANA time zone, e.g. Asia/Singapore. Required when lat and lng are given."},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Decimal degrees."},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Decimal degrees."},"agent":{"type":"string","maxLength":80,"description":"Optional: the name of the agent or product calling. Logged for usage counts; never required, never verified."}}}}}},"responses":{"200":{"description":"Both zodiacs: the Western sun sign and the Chinese animal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EngineResult"}}}},"400":{"description":"A field was missing or malformed. The body says which, and points at the docs."},"429":{"description":"Fair-use limit: more than 60 requests a minute from one address, counted across servers and shared by every /api/v1 endpoint. Retry-After says how long to wait. Never cached."}}}}},"components":{"schemas":{"Reading":{"type":"object","properties":{"version":{"type":"object","description":"API, identity-formula and engine versions, so a stored response can be told from a later one."},"input":{"type":"object"},"western":{"type":"object","properties":{"sunSign":{"type":["string","null"]},"cusp":{"type":"boolean"}}},"chinese":{"type":"object","properties":{"animal":{"type":"string"},"yearElement":{"type":"string"}}},"bazi":{"type":"object","properties":{"dayMaster":{"type":"object"},"dominantElement":{"type":"string"},"pillars":{"type":"array"},"hourPillar":{"type":"string"}}},"numerology":{"type":"object","properties":{"lifePath":{"type":"integer"}}},"identity":{"type":["object","null"]},"method":{"type":"object"},"page_url":{"type":"string","format":"uri"},"terms":{"type":"object"}},"required":["version","input","western","chinese","bazi","numerology","method","page_url","terms"]},"EngineResult":{"type":"object","description":"One engine's own output. The shape differs per endpoint — pillars for BaZi, hours for the hour endpoint, numbers for numerology, signs for the zodiac — and these five fields are always present.","properties":{"version":{"type":"object","description":"API and engine version."},"input":{"type":"object","description":"The inputs as they were understood, including what was left unset."},"method":{"type":"object","description":"How it was computed, and which convention was used where traditions differ."},"notes":{"type":"array","description":"Caveats the engine raised for these inputs, each with a key and a sentence.","items":{"type":"object","properties":{"key":{"type":"string"},"note":{"type":"string"}}}},"page_url":{"type":"string","format":"uri","description":"A page a person can open. Birth details ride in the fragment, which browsers never send to a server."},"terms":{"type":"object","description":"Scope, privacy, attribution and the honesty policy. Present in every response."}},"required":["version","input","method","notes","page_url","terms"]}}}}