{"openapi":"3.1.0","info":{"title":"MysticAPI","version":"0.1.0","description":"Metered engine API for Human Design–compatible bodygraphs, personal sky charts, ephemeris, and numerology. Deterministic computation (JPL-validated ephemeris port) — no generative output. Flat monthly pricing (never credits): Free 50 calls/mo (no card, POST /v1/keys/free) · Maker $19/mo · Pro $49/mo · Scale $149/mo — payment links in x-pricing. Metered endpoints also accept x402 USDC payments on Base ($0.01/call) as an alternative to a key. Agent-readable overview: https://mysticapi.com/llms.txt","contact":{"url":"https://mysticapi.com"}},"x-pricing":{"unit":"calls","model":"flat-monthly","reset":"monthly on the 1st, UTC","tiers":{"free":{"usdPerMonth":0,"callsPerMonth":50,"signup":"POST /v1/keys/free (no card)"},"maker":{"usdPerMonth":19,"callsPerMonth":2000,"paymentLink":"https://buy.stripe.com/cNi3cufxE0wKbhcaZmaEE00"},"pro":{"usdPerMonth":49,"callsPerMonth":6000,"paymentLink":"https://buy.stripe.com/5kQeVc1GO5R43OK1oMaEE01"},"scale":{"usdPerMonth":149,"callsPerMonth":20000,"paymentLink":"https://buy.stripe.com/dRm9ASetA0wK1GCgjGaEE02"}},"x402":{"network":"base","asset":"USDC","usdPerCall":0.01,"spec":"https://x402.org"},"note":"Pay at a payment link → your API key is emailed automatically within a minute of checkout."},"servers":[{"url":"https://mysticapi.com"}],"security":[{"apiKey":[]}],"paths":{"/health":{"get":{"operationId":"getHealth","summary":"Service health (no auth)","security":[],"responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string"},"environment":{"type":"string"},"time":{"type":"string","format":"date-time"}},"required":["status","service"]}}}}}}},"/v1/sky/today":{"get":{"operationId":"getSkyToday","summary":"Today's universal sky: retrogrades, moon phase, positions, upcoming events","description":"Universal (non-personal) sky snapshot: geocentric positions for 13 bodies with zodiac + Energy-Blueprint gate placements, active retrogrades, moon phase/illumination, and a 30-day forward scan of retrograde stations and new/full moons. Metered: 1 call against your monthly allotment, or one x402 payment ($0.01 USDC).","parameters":[],"responses":{"200":{"description":"Sky snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date"},"generatedAt":{"type":"string","format":"date-time"},"moon":{"type":"object","properties":{"phaseName":{"type":"string"},"illumination":{"type":"number","minimum":0,"maximum":1},"elongationDeg":{"type":"number"},"nextNewMoon":{"$ref":"#/components/schemas/SkyEvent"},"nextFullMoon":{"$ref":"#/components/schemas/SkyEvent"}}},"retrogrades":{"type":"object","properties":{"active":{"type":"array","items":{"type":"object","properties":{"planet":{"type":"string"},"label":{"type":"string"}}}},"upcomingStations":{"type":"array","items":{"$ref":"#/components/schemas/SkyEvent"}}}},"positions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/BodyPosition"}},"upcoming":{"type":"array","items":{"$ref":"#/components/schemas/SkyEvent"}},"attribution":{"type":"string"}},"required":["date","moon","retrogrades","positions","upcoming"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}},"/v1/bodygraph":{"post":{"operationId":"postBodygraph","summary":"Energy Blueprint (Human Design) chart JSON + body-graph SVG from birth data","description":"Birth instant (UTC) → the complete Energy Blueprint chart (type, authority, strategy, profile, definition, cross, channels, centers, conscious + unconscious gate maps) plus a rendered body-graph SVG. Location is not required — the body-graph is location-independent. Metered: 1 call against your monthly allotment, or one x402 payment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthInput"}}}},"responses":{"200":{"description":"Computed chart + SVG","content":{"application/json":{"schema":{"type":"object","properties":{"chart":{"type":"object","description":"Full computation: birth (with jdn), design (88° solar-arc moment), personalityGates + designGates (per-body {gate,line}), and chart (type/authority/strategy/profile/definition/cross/channels/centers)."},"svg":{"type":"string","description":"Body-graph SVG markup."},"attribution":{"type":"string"}},"required":["chart","svg"]}}}},"400":{"$ref":"#/components/responses/InvalidBirthInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}},"/v1/sky/personal":{"get":{"operationId":"getPersonalSky","summary":"Personal-sky SVG from birth data (query params)","description":"Natal geocentric positions rendered as a personal sky (SVG). Birth via query params (year, month, day, hour, minute, optional second, UTC; optional animate=false for a static render). Retrogrades render ℞; fixed stars conjunct natal points light up. Deterministic: the same birth always yields the same sky. Response is image/svg+xml. Metered like /v1/bodygraph.","parameters":[{"name":"year","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":2200}},{"name":"month","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"day","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":31}},{"name":"hour","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":23}},{"name":"minute","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":59}},{"name":"second","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":59}},{"name":"animate","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Personal-sky SVG","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/InvalidBirthInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}},"post":{"operationId":"postPersonalSky","summary":"Personal-sky SVG from birth data (JSON body)","description":"Same as GET /v1/sky/personal but takes the birth instant as a JSON body. Response is image/svg+xml.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthInput"}}}},"responses":{"200":{"description":"Personal-sky SVG","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/InvalidBirthInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}},"/v1/ephemeris":{"get":{"operationId":"getEphemeris","summary":"Raw geocentric positions for any instant (13 bodies + retrograde flags)","description":"JPL-validated ephemeris (Meeus + Standish 1992): geocentric ecliptic longitudes for Sun–Pluto, Chiron, and the lunar nodes at the given UTC instant, with retrograde flags. Query params: year, month, day, hour, minute (optional second). Metered: 1 call.","parameters":[{"name":"year","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":2200}},{"name":"month","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"day","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":31}},{"name":"hour","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":23}},{"name":"minute","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":59}},{"name":"second","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":59}}],"responses":{"200":{"description":"Positions at the instant","content":{"application/json":{"schema":{"type":"object","properties":{"instant":{"type":"string","format":"date-time"},"positions":{"type":"object","additionalProperties":{"type":"object","properties":{"longitude":{"type":"number","minimum":0,"exclusiveMaximum":360},"label":{"type":"string"},"retrograde":{"type":"boolean"}}}}},"required":["instant","positions"]}}}},"400":{"$ref":"#/components/responses/InvalidBirthInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}},"/v1/numerology":{"post":{"operationId":"postNumerology","summary":"Numerology profile from a birth date","description":"Pythagorean life path (master numbers 11/22/33 preserved), birthday number, personal year/month/day cycles, and tarot birth card. Body: the standard birth JSON (only the date fields matter). Metered: 1 call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthInput"}}}},"responses":{"200":{"description":"Numerology profile","content":{"application/json":{"schema":{"type":"object","properties":{"birthDate":{"type":"string","format":"date"},"lifePath":{"type":"object","description":"Life path number with master-number flag and calculation trail."},"birthday":{"type":"object"},"personalYear":{"type":"object"},"personalMonth":{"type":"object"},"personalDay":{"type":"object"},"tarotCard":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/InvalidBirthInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}},"/v1/relationship":{"post":{"operationId":"postRelationship","summary":"Composite/connection chart for two people","description":"Overlays two Energy Blueprint charts: electromagnetic channels (each person provides one gate), dominance, companionship, and compromise channels, combined definition, and qualitative type/authority/profile dynamics. Metered: 1 call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"personA":{"$ref":"#/components/schemas/BirthInput"},"personB":{"$ref":"#/components/schemas/BirthInput"}},"required":["personA","personB"]}}}},"responses":{"200":{"description":"Composite analysis","content":{"application/json":{"schema":{"type":"object","properties":{"electromagnetic":{"type":"array","items":{"type":"object"}},"dominanceA":{"type":"array","items":{"type":"object"}},"dominanceB":{"type":"array","items":{"type":"object"}},"companionship":{"type":"array","items":{"type":"object"}},"compromise":{"type":"array","items":{"type":"object"}},"combinedDefinition":{"type":"string"},"combinedCenters":{"type":"array","items":{"type":"string"}},"personA":{"type":"object"},"personB":{"type":"object"},"dynamics":{"type":"array","items":{"type":"object"}}}}}}},"400":{"$ref":"#/components/responses/InvalidBirthInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}},"/v1/demo":{"post":{"operationId":"postDemo","summary":"Try before key: watermarked bodygraph + personal sky (no auth)","description":"Renders a real chart from birth JSON with no API key. Output SVGs carry a visible demo watermark; heavily rate-limited per IP; never counted as product usage. For evaluation only — production use needs a key.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BirthInput"}}}},"responses":{"200":{"description":"Watermarked demo render","content":{"application/json":{"schema":{"type":"object","properties":{"demo":{"type":"boolean","const":true},"summary":{"type":"object"},"bodygraphSvg":{"type":"string"},"personalSkySvg":{"type":"string"},"next":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/InvalidBirthInput"},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}},"/v1/keys/free":{"post":{"operationId":"createFreeKey","summary":"Self-serve free API key (no card) — delivered by email","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"]}}}},"responses":{"202":{"description":"Key minted and emailed (one active key per email; 50 calls/month)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"docs":{"type":"string"}}}}}},"400":{"description":"Invalid email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Email already has an active key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/QuotaExceeded"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"mk_live_...","description":"API key in the Authorization header: `Authorization: Bearer mk_live_...`"}},"schemas":{"SkyEvent":{"type":["object","null"],"properties":{"date":{"type":"string","format":"date"},"type":{"type":"string","enum":["retrograde_start","retrograde_end","new_moon","full_moon"]},"planet":{"type":"string"},"title":{"type":"string"},"prep":{"type":"string"},"daysAway":{"type":"integer"}}},"BodyPosition":{"type":"object","properties":{"label":{"type":"string"},"longitude":{"type":"number","minimum":0,"exclusiveMaximum":360},"zodiac":{"type":"object","properties":{"sign":{"type":"string"},"degree":{"type":"number"}}},"gate":{"type":"object","properties":{"gate":{"type":"integer","minimum":1,"maximum":64},"line":{"type":"integer","minimum":1,"maximum":6}}},"retrograde":{"type":"boolean"}}},"BirthInput":{"type":"object","description":"A birth instant in UTC. Convert local time + timezone to UTC before calling.","properties":{"year":{"type":"integer","minimum":1,"maximum":2200},"month":{"type":"integer","minimum":1,"maximum":12},"day":{"type":"integer","minimum":1,"maximum":31},"hour":{"type":"integer","minimum":0,"maximum":23},"minute":{"type":"integer","minimum":0,"maximum":59},"second":{"type":"integer","minimum":0,"maximum":59,"default":0}},"required":["year","month","day","hour","minute"],"example":{"year":1979,"month":8,"day":5,"hour":22,"minute":51}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"docs":{"type":"string","format":"uri"}},"required":["error","message"]}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"QuotaExceeded":{"description":"Monthly call allotment reached or rate limited (Retry-After header set)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"No API key supplied and the request carried no valid X-PAYMENT header — body contains x402 payment terms (x402Version, accepts[]) per https://x402.org. Retry with the X-PAYMENT header, or use an API key.","content":{"application/json":{"schema":{"type":"object"}}}},"InvalidBirthInput":{"description":"Birth data was missing or out of range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"x-mcp":{"endpoint":"https://mysticapi.com/mcp","transport":"streamable-http","protocol":"Model Context Protocol (JSON-RPC 2.0)","tools":["sky_today","bodygraph","sky_personal","ephemeris","numerology","relationship"],"auth":"Same Authorization: Bearer mk_live_… key; or x402 payment terms on a keyless tools/call.","note":"initialize + tools/list are free; tools/call is metered."},"x-privacy":{"guarantee":"Birth data is never persisted — processed in memory only; not written to DB, logs, or analytics.","policy":"https://mysticapi.com/legal/privacy"}}