{"openapi":"3.1.0","info":{"title":"askTIAN — public read API","version":"1.0.0","summary":"Read a public natal chart across 23 divination systems, plus the daily almanac.","description":"The public, credential-free surface of asktian.com. Use it to read a public profile's\nchart across 23 systems, the synthesised cross-tradition reading, and the daily\nalmanac (黄历) or Vedic day (panchāng).\n\n**Privacy:** only profiles whose owner opted into public visibility are readable. A private\nor restricted profile returns 403, an unknown handle 404. Birth details (date, time, place)\nare never exposed by these endpoints — only derived chart output.\n\n**Not covered here:** owner-scoped endpoints (your own profile, the paid Wealth/Health\nlayers, family readings) require a Privy bearer token and are not part of this contract.\n\n**Interpretation:** readings are symbolic and cultural, not empirical prediction. Health\ncontent is wellness reflection only — not medical advice, diagnosis, or treatment — and its\ndisclaimer must be reproduced verbatim. Nothing here is financial advice.\n\nFor richer computation (145 systems, compatibility, elections) call https://api.asktian.com.\nFor conversational readings, https://chat.asktian.com. MCP: https://mcp.asktian.com/mcp.","contact":{"url":"https://asktian.com/agents"}},"servers":[{"url":"https://asktian.com","description":"Production"}],"tags":[{"name":"profiles","description":"Public charts and readings"},{"name":"almanac","description":"Date-based readings that need no birth data"}],"paths":{"/api/profile/public/{username}":{"get":{"tags":["profiles"],"operationId":"getPublicProfile","summary":"A public profile's identity card","description":"Handle, display name, bio, avatar and the headline zodiac placements. No birth data.","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"},"example":"einstein"}],"responses":{"200":{"description":"The public profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProfile"}}}},"403":{"description":"Profile is private or restricted","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"No such handle","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/profile/charts/{username}":{"get":{"tags":["profiles"],"operationId":"getPublicCharts","summary":"The 23-system natal chart bundle","description":"Structured output from every system that computed for this chart. Keys are system slugs (bazi, ziwei, western, vedic, humanDesign, numerology, …). A system that could not compute for this birth data appears with an `error` field rather than being absent, so callers should skip entries carrying `error`.","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"},"example":"einstein"}],"responses":{"200":{"description":"Chart bundle","content":{"application/json":{"schema":{"type":"object","properties":{"systems":{"type":"object","additionalProperties":true,"description":"system slug → that system's structured reading"},"systemsRun":{"type":"integer","description":"how many systems computed cleanly"},"hasBirthTime":{"type":"boolean","description":"false means time-dependent systems (e.g. Zi Wei, house cusps) are degraded"},"calculatedAt":{"type":["string","null"],"format":"date-time"}}}}}},"403":{"description":"Profile is private or restricted","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"No such handle","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/profile/digest/{username}":{"get":{"tags":["profiles"],"operationId":"getDigest","summary":"The synthesised cross-tradition reading","description":"One plain-language reading woven from all systems: identity, purpose, life domains, the life arc, and — distinctively — `tensions`, where the traditions genuinely disagree rather than being averaged out. `pending: true` means the synthesis is still computing; retry shortly.","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"},"example":"einstein"}],"responses":{"200":{"description":"The digest (or a pending marker)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Profile is private or restricted","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"No such handle","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/profile/forecast/{username}":{"get":{"tags":["profiles"],"operationId":"getForecast","summary":"A date-anchored forecast for a public profile","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"},"example":"einstein"},{"name":"asOf","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Anchor date (YYYY-MM-DD). Defaults to today."}],"responses":{"200":{"description":"Forecast payload; `locked: true` when the date is outside the free window","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Profile is private or restricted","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"No such handle","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/profile/list":{"get":{"tags":["profiles"],"operationId":"listPublicProfiles","summary":"Browse profiles that opted into public listing","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":60}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Public profiles","content":{"application/json":{"schema":{"type":"object","properties":{"profiles":{"type":"array","items":{"$ref":"#/components/schemas/PublicProfile"}}}}}}}}}},"/api/almanac/daily":{"get":{"tags":["almanac"],"operationId":"getDailyAlmanac","summary":"The day's almanac (黄历) — identical for everyone","description":"Day pillar (干支), lunar date, whether it is a 黄道 auspicious day, what the day favours (宜) and what to avoid (忌), and the lucky directions. Needs no birth data.","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"},"example":"2026-08-16"}],"responses":{"200":{"description":"Almanac for that date","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Malformed date","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"502":{"description":"Upstream unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/panchanga":{"get":{"tags":["almanac"],"operationId":"getPanchanga","summary":"The Vedic day (panchāng) with intra-day transition times","description":"Tithi, nakshatra, yoga and karana with their end-times — e.g. \"Navami until 16:43, then Dashami\". Sunrise-based, so it is location-specific: pass the coordinates you want it computed for.","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"lat","in":"query","required":true,"schema":{"type":"number"},"example":28.61},{"name":"lng","in":"query","required":true,"schema":{"type":"number"},"example":77.21},{"name":"tz","in":"query","required":true,"schema":{"type":"number"},"description":"Hours east of UTC","example":5.5}],"responses":{"200":{"description":"Panchāng with transitions","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Malformed date or location","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"502":{"description":"Upstream unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/profile/check-username":{"get":{"tags":["profiles"],"operationId":"checkUsername","summary":"Is a handle available?","parameters":[{"name":"u","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Availability","content":{"application/json":{"schema":{"type":"object","properties":{"available":{"type":"boolean"},"reason":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PublicProfile":{"type":"object","properties":{"username":{"type":"string"},"displayName":{"type":["string","null"]},"bio":{"type":["string","null"]},"avatarUrl":{"type":["string","null"]},"isPublic":{"type":"boolean"},"westernZodiac":{"type":["string","null"]},"chineseZodiac":{"type":["string","null"]},"chineseElement":{"type":["string","null"]},"category":{"type":["string","null"]}},"required":["username"]}}}}