Integration guide

What you can do

These are the endpoints an integration uses. The worked examples below show what to send and what comes back.

• POST/api/v1/chartCast a chartPublic
• POST/api/v1/chart/overviewReading overview, numbers onlyPublic
• POST/api/v1/readings/retro-scanKey-year scan, numbers onlyNeeds readings:write
• POST/api/v1/readingsGenerate a reading from a planNeeds readings:write
• GET/api/v1/readings/{id}Fetch one reportNeeds readings:read
• GET/api/v1/readingsList your own reportsNeeds readings:read
• GET/api/v1/catalogProducts and pricesPublic
• GET/api/v1/samples/{slug}One sample report (fixed content)Public

The overview, the key-year scan and reading a sample make no AI model call at all. Generating a report is asynchronous: submit, then poll the report endpoint for progress.

Option 1: the HTTP API

To create API keys you first need developer access: sign in, open the Developer page in your account and apply. Once approved, you create keys yourself and send one in a request header. The full key is shown only once, at the moment it is created, so save it then. If it is lost, revoke it on the same page and create another.

Authorization: Bearer ok_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

That string is a placeholder; substitute your own key. Never commit a real key to a repository.

The six scopes

• chartCharts
• overviewReading overview
• catalogProducts and prices
• samplesSample reports
• readings:readRead and list reports
• readings:writeGenerate reports, key-year scan, scoring

Each key may make 60 calls a minute; beyond that you get a 429 with Retry-After. An unknown key, a revoked key and a key without the scope all answer with the same 403 and the same sentence — a client only needs to tell “slow down” apart from “this key no longer works”.

Option 2: MCP

MCP is the open protocol AI assistants use to call outside tools. Once it is configured, an assistant like Claude casts the chart and fetches the reading by itself, with nothing extra to code. The server is named cyber-oracle and lives at /mcp on the site.

claude mcp add --transport http cyber-oracle \
  https://<this-site>/mcp \
  --header "Authorization: Bearer ok_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "mcpServers": {
    "cyber-oracle": {
      "type": "http",
      "url": "https://<this-site>/mcp",
      "headers": {
        "Authorization": "Bearer ok_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Eight tools, with exactly the same inputs and outputs as the matching HTTP endpoints:

• bazi_chart
• reading_overview
• reading_retro_scan
• reading_create
• reading_get
• reading_list
• catalog_list
• sample_get

Worked examples

The birth details in every example belong to a fictional chart (1984-03-21 07:40, Beijing), not to a real person.

Cast a chart

{
  "name": "Sample",
  "birth": { "year": 1984, "month": 3, "day": 21, "hour": 7, "minute": 40 },
  "gender": "female",
  "place": {
    "lng": 116.397, "lat": 39.908,
    "tz": "Asia/Shanghai", "coord_system": "GCJ-02", "label": "Beijing"
  },
  "policy": "default",
  "locale": "en"
}

If the birth time is unknown, send "birth": {"year": 1984, "month": 3, "day": 21, "time_unknown": true} — the chart is still cast, with the hour-dependent parts left out. Readings do not accept such a chart.

Reading overview

Same body as a chart, but it must not carry options. Everything that comes back is a number: how much there is to write for each product in this chart.

{"available": true, "as_of": {"year": 2026, "month": 8},
 "products": {"retro": {"total": 4, "years": [{"year": 2023, "count": 4}]},
              "personality": 5, "marriage": 4, "wealth": 7, "health": 1, "career": 1}}

Generate a report

Send an Idempotency-Key header. The report is anchored on the moment you submit it, so do not send a year. plan.retro.mode is one of: recent (the last five years), key (the server scans and picks the key years), custom (you name 1 to 5 years).

{
  "…": "same birth details as above",
  "dimensions": ["性格", "财运", "婚姻", "事业", "健康"],
  "plan": { "version": 2, "retro": { "mode": "key" } }
}

202 means it is queued; poll the report endpoint afterwards. 200 means this chart did not give enough to write, and nothing was queued. The same Idempotency-Key with the same body returns the same report; with a different body it answers 409.

Errors

{"code": "validation_error", "message": "…", "request_id": "…", "fields": {"…": "…"}}

Every error has this shape, with message already localized to the request's locale. Authentication failures are the one exception: the body has a different shape, so handle them by status code.

Pricing

Custom development is available too. If you want to talk through the integration or the cost first, email us; the address is at the bottom of the page.

Contact

For access, pricing and custom development, email us at 954607206@qq.com

You can also look at the sample reports and the privacy policy first to see what the service does and how data is handled.