REST API v1

The public REST namespace is:

• /api/developer/v1

Use the same Bearer API key as the hosted MCP endpoint:

Authorization: Bearer YOUR_API_KEY

Endpoints

• POST /api/developer/v1/calculate-chart Returns a Zi Wei Dou Shu chart. Free to call.
• POST /api/developer/v1/analyze-destiny Returns a premium analysis or a basic fallback, depending on balance.
• POST /api/developer/v1/get-energy-metrics Returns premium astrological energy metrics for a target year.

Common Behavior

• All requests require a valid Bearer token.
• Invalid request payloads return 400.
• Missing or invalid Bearer tokens return 401.
• Premium endpoints can return either a basic fallback response or 402, depending on the endpoint and the balance state.
• Successful premium responses include billing metadata in the response body.
• REST requests are limited to 10 calls per second per API key.

Billing Metadata

Successful premium REST responses include billing metadata:

{
  "billing": {
    "premium": true,
    "chargedUsd": 0.08,
    "chargedDisplayUsd": "$0.08",
    "remainingBalanceUsd": 12.42,
    "remainingBalanceDisplayUsd": "$12.42",
    "pricingVersion": "developer-v1-2026-06-27"
  }
}

Error Responses

REST v1 routes return JSON errors in this shape:

{
  "error": "Human-readable message",
  "details": {}
}

400 Bad Request

Returned when the JSON body is missing required fields or contains invalid values.

{
  "error": "Invalid request data",
  "details": {
    "issues": {
      "fieldErrors": {
        "birthDate": ["Required"]
      }
    }
  }
}

401 Unauthorized

Returned when the Bearer token is missing, invalid, or rotated.

{
  "error": "Authorization Bearer token required"
}

{
  "error": "Invalid or expired API token"
}

402 Payment Required

Returned by premium-only routes when the account does not meet the premium balance floor before work begins.

{
  "error": "Payment required",
  "details": {
    "code": "PAYMENT_REQUIRED",
    "minimumBalanceUsd": 1,
    "currentBalanceUsd": 0.42
  }
}

429 Too Many Requests

Returned when a client exceeds the per-key rate limit.

{
  "error": "Developer rate limit exceeded",
  "details": {
    "code": "RATE_LIMITED",
    "limit": "10 requests per second",
    "retryAfterSeconds": 1
  }
}