API v1

Daymaster API

White-label access to our Bazi + ZWDS chart engines, AI-driven readings, and chart-contextualised Tarot. Build your own UI, use our data. Pay per successful call, billed monthly.

📘 Full partner playbook

Single .md file with API reference + design system + business model + 15 build ideas. Drop it into your AI coding assistant.

Download .md

Authentication

Every request requires a Bearer API key in the Authorization header. Request a key from your account manager — we mint one for you in the admin portal and share it exactly once. Keep it out of source control and client-side bundles.

Optionally pass X-End-User-Id as an opaque string identifying the end user on your side — we never map it to one of our auth users, but it shows up on usage events so you can correlate billing to specific customers.

Generate a chart

POST /api/v1/readings/generate runs the Bazi engine (and optionally ZWDS) on a birth profile and persists the chart to our database for later reference. No LLM call — this is cheap and fast.

POST /api/v1/readings/generate HTTP/1.1
Host: daymaster.ai
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
X-End-User-Id: your_user_42
Content-Type: application/json

{
  "birth_datetime": "1990-05-15T08:00:00+08:00",
  "longitude": 121.47,
  "latitude": 31.23,
  "gender": "male",
  "include_zwds": true,
  "language": "en"
}

Draw tarot

POST /api/v1/tarot performs a seeded shuffle for the chosen spread and returns the drawn cards plus an LLM-generated narrative woven through the user's chart (when areading_id is passed). Set skip_llm: true for deterministic cards only.

POST /api/v1/tarot HTTP/1.1
Host: daymaster.ai
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
X-End-User-Id: your_user_42
Content-Type: application/json

{
  "spread_id": "past_present_future",
  "question": "Should I take the new job offer?",
  "reading_id": "uuid-of-previously-generated-chart",
  "lang": "en"
}

Response shape

Every successful call returns a usage block with the billed module_id, per-call cost frozen at event time, and your month-to-date revenue so you can budget client-side without a second round trip.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "chart": {
    "bazi": { "dayMaster": "甲", "year": { ... }, "luckPillars": [...] },
    "zwds": { "palaces": [...], "daxians": [...] }
  },
  "reading_id": "abc-123-def",
  "usage": {
    "event_id": 42,
    "module_id": "bazi_chart",
    "unit_cost_usd": 0.10,
    "mtd_revenue_usd": 127.50
  }
}

Modules

You opt into modules explicitly. New Daymaster features never auto-appear in your offering.

Module	Endpoint	Typical price
bazi_chart (incl. ZWDS)	POST /api/v1/readings/generate	$0.10 / call
ai_reading	(coming soon)	$0.50 / call
tarot	POST /api/v1/tarot	$0.30 / call
chat	(coming soon)	$0.02 / message
compatibility	(coming soon)	$0.80 / call

Errors

Standard HTTP status codes:

400 — bad request (missing or invalid body field)
401 — missing or invalid API key
403 — key revoked, tenant paused, or module not enabled
422 — chart could not be computed (invalid birth inputs)
502 — LLM provider failed after fallback chain exhausted
503 — database temporarily unavailable

Versioning

The base path /api/v1/* is stable. New features ship as new endpoints within v1 or as/api/v2/* when breaking changes are necessary. We never change the response shape of an existing endpoint without a version bump.