{"openapi":"3.1.0","info":{"title":"格局 GrandScheme agent API","version":"1.0.0","description":"Free ZiWei and BaZi charts, and a Stripe Checkout link for a paid 格局命書. No API key. A full book takes about 30–40 minutes and is written one at a time. The MCP server is at /mcp."},"servers":[{"url":"https://www.grandscheme.life"}],"paths":{"/api/agent/v1/pricing":{"get":{"operationId":"get_pricing","summary":"List products, prices, and writing time.","responses":{"200":{"description":"Pricing JSON with a summary field."}}}},"/api/agent/v1/charts":{"post":{"operationId":"cast_free_chart","summary":"Cast a free ZiWei or BaZi chart.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"system":{"type":"string","enum":["ziwei","bazi"],"description":"ziwei for 紫微斗數, bazi for 八字."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Clock birth date YYYY-MM-DD, before True Solar Time correction."},"time":{"description":"Clock time HH:mm. Defaults to 12:00 when omitted.","type":"string","pattern":"^\\d{2}:\\d{2}$"},"name":{"description":"Name. Optional.","type":"string","maxLength":80},"city":{"description":"Birth city label. Optional. Longitude is what corrects True Solar Time.","type":"string","maxLength":80},"gender":{"type":"string","enum":["male","female"],"description":"male or female."},"longitude":{"description":"Birth longitude in degrees east. Defaults to Hong Kong, 114.17.","type":"number","minimum":-180,"maximum":180},"tzOffset":{"description":"Hours from UTC. Defaults to +8.","type":"number","minimum":-12,"maximum":14},"agent_name":{"description":"Optional name of the calling agent, for traffic attribution.","type":"string","maxLength":80},"agent_user_agent":{"description":"Optional client identifier, for traffic attribution.","type":"string","maxLength":300}},"required":["system","date","gender"],"additionalProperties":false}}}},"responses":{"200":{"description":"Chart JSON, summary, and a note that the full book is paid."}}}},"/api/agent/v1/orders":{"post":{"operationId":"create_order","summary":"Create an order and return a Stripe Checkout URL.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Same key and same order returns the original Checkout link."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"product":{"type":"string","enum":["single","combo","annual"],"description":"single is one system, combo is both books, annual is the 2026 year guide."},"system":{"description":"Required when product is single. Ignored for combo and annual.","type":"string","enum":["ziwei","bazi"]},"currency":{"description":"HKD, SGD, TWD, CNY, USD, EUR, or GBP. Anything else is charged in HKD.","type":"string"},"birth":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Clock birth date YYYY-MM-DD, before True Solar Time correction."},"time":{"description":"Clock time HH:mm. Defaults to 12:00 when omitted.","type":"string","pattern":"^\\d{2}:\\d{2}$"},"name":{"description":"Name. Optional.","type":"string","maxLength":80},"city":{"description":"Birth city label. Optional. Longitude is what corrects True Solar Time.","type":"string","maxLength":80},"gender":{"type":"string","enum":["male","female"],"description":"male or female."},"longitude":{"description":"Birth longitude in degrees east. Defaults to Hong Kong, 114.17.","type":"number","minimum":-180,"maximum":180},"tzOffset":{"description":"Hours from UTC. Defaults to +8.","type":"number","minimum":-12,"maximum":14}},"required":["date","gender"],"additionalProperties":false,"description":"Full birth data. Stored in GrandScheme's database, not only in Stripe."},"buyer_email":{"description":"Prefills Stripe Checkout. The receipt email Stripe collects is the one we write to.","type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"callback_url":{"description":"HTTPS URL to POST when the order is paid, generating, ready, or failed.","type":"string","format":"uri"},"agent_name":{"description":"Optional name of the calling agent, for traffic attribution.","type":"string","maxLength":80},"agent_user_agent":{"description":"Optional client identifier, for traffic attribution.","type":"string","maxLength":300},"idempotency_key":{"description":"Same key and same order returns the original Checkout link. A different order with the same key is rejected.","type":"string","minLength":8,"maxLength":80},"fbp":{"description":"Optional Meta _fbp cookie from the human's browser.","type":"string","maxLength":200},"fbc":{"description":"Optional Meta _fbc cookie from the human's browser.","type":"string","maxLength":400},"fbclid":{"description":"Optional Meta click id.","type":"string","maxLength":200},"utm_source":{"type":"string","maxLength":200},"utm_medium":{"type":"string","maxLength":200},"utm_campaign":{"type":"string","maxLength":200},"utm_content":{"type":"string","maxLength":200},"utm_term":{"type":"string","maxLength":200},"utm_id":{"type":"string","maxLength":200},"event_source_url":{"description":"Page the human was on when the order was created.","type":"string","maxLength":500}},"required":["product","birth"],"additionalProperties":false}}}},"responses":{"200":{"description":"order_id, checkout_url, and payment instructions."}}}},"/api/agent/v1/orders/{order_id}":{"get":{"operationId":"get_order_status","summary":"Read order status. Poll about every 5 minutes.","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","pattern":"^gs_ord_[A-Za-z0-9_-]{16}$","description":"The gs_ord_ id returned by create_order."}}],"responses":{"200":{"description":"Status, queue, ETA, and signed book links when ready."}}}}}}