POST /api/developer/v1/analyze-destiny

Returns a premium analysis when the account has enough prepaid balance. If the account does not meet the premium balance floor, it returns a basic fallback instead of charging.

Request Body

Field	Type	Required	Description
birthDate	string	Yes	Birth date in YYYY-MM-DD or DD/MM/YYYY format.
birthTime	string	Yes	Birth time in HH:mm 24-hour format.
gender	enum	Yes	Biological gender: "male" or "female".
timezone	string	Yes	IANA timezone such as Asia/Singapore or America/New_York.
palaces	string[]	Yes	Palace keys to analyze, for example ["soul", "career"]. Use ["all"] to analyze the full chart.
language	enum	No	Response language: "en" or "zh". Defaults to "en".

{
  "birthDate": "1995-10-15",
  "birthTime": "08:30",
  "gender": "female",
  "timezone": "Asia/Singapore",
  "palaces": ["soul", "career"],
  "language": "en"
}

Errors

• 400 for invalid request data or when no requested palace names match the chart
• 401 for missing or invalid Bearer authentication
• No 402 is returned for low balance on this route; it falls back to the basic response shown above
• 429 when the API key exceeds 10 calls per second

Response Body: Basic Fallback

{
  "accessTier": "basic",
  "premiumAvailable": false,
  "premiumRequirement": {
    "minimumBalanceUsd": 1.0,
    "currentBalanceUsd": 0.42
  },
  "result": [
    {
      "palaceName": { "en": "Career", "zh": "官祿" },
      "stars": [
        {
          "name": { "english": "advisor", "chinese": "天机" },
          "type": "major",
          "brightness": "廟",
          "mutagen": null
        }
      ],
      "staticDescription": "Static layout description for the Career palace."
    }
  ]
}

Response Body: Premium

{
  "accessTier": "premium",
  "premiumAvailable": true,
  "result": {
    "career": "A detailed, dynamic AI interpretation of the user's career paths and timing."
  },
  "traitInsights": {
    "career": [
      {
        "key": "actionIndex",
        "name": "Action",
        "tooltip": "Behavioral momentum and execution power.",
        "score": 75,
        "tierLabel": "High",
        "description": "Action is high in this palace, making it a clear strength and a frequent behavioral tendency here."
      }
    ]
  },
  "billing": {
    "premium": true,
    "chargedUsd": 0.08,
    "chargedDisplayUsd": "$0.08",
    "reservedUsd": 0.08,
    "reservedDisplayUsd": "$0.08",
    "remainingBalanceUsd": 12.42,
    "remainingBalanceDisplayUsd": "$12.42",
    "pricingVersion": "developer-v1-2026-06-27"
  }
}