# D8ly Read Agent & Developer API

> Deterministic Bazi (八字), Chinese almanac, and fortune-related tools for agents and developers.

D8ly Read exposes a stateless Model Context Protocol endpoint and a versioned HTTP API. MCP tools are read-only and deterministic. They do not create accounts, change profiles, save readings, or call generative AI.

## Agent entry points

- [MCP endpoint](https://d8ly.app/mcp): Streamable HTTP endpoint for compatible agent clients.
- [OpenAPI 3.1 contract](https://d8ly.app/openapi.json): Machine-readable HTTP API contract.
- [MCP quickstart](https://d8ly.app/developers/quickstart): Copy-ready connection config and starter prompts.
- [Developer page](https://d8ly.app/developers): Human-readable setup and endpoint directory.
- [General site guide](https://d8ly.app/llms.txt): Curated guide to D8ly Read content.
- [Full agent reference](https://d8ly.app/llms-full.txt): Expanded selection, calculation, privacy, and capability guide.

## MCP tools

- `get_daily_almanac` — Use this when a date-only request needs the day pillar, lunar date, suitable and unsuitable activities, auspicious directions, or zodiac clash. Do not use it for personalized Bazi readings. / 當僅依日期查詢日柱、農曆日期、宜忌、吉神方位或生肖相沖時使用；個人化八字解讀請勿使用。
- `calculate_bazi_chart` — Use this when complete birth details are supplied and a Four Pillars chart with True Solar Time correction is needed. Do not infer missing birth details. / 當已提供完整出生資料，且需要以真太陽時校正建立四柱八字時使用；請勿推測缺少的出生資料。
- `get_daily_bazi_guidance` — Use this when complete birth details and a reading date are supplied for deterministic daily Bazi guidance. Do not use it for a date-only almanac request. / 當已提供完整出生資料與解讀日期，且需要確定式八字每日指引時使用；僅查日期黃曆時請勿使用。

## Existing HTTP API v1

The HTTP API requires a bearer key created at https://d8ly.app/settings/api-keys. The account-wide limit is currently 100 requests per day.

- `POST /api/v1/bazi` — Bazi chart / 八字命盤
- `POST /api/v1/daily` — Daily fortune / 每日運勢
- `POST /api/v1/number-energy` — Number energy / 數字能量
- `POST /api/v1/tarot` — Tarot reading / 塔羅解讀
- `POST /api/v1/compatibility` — Compatibility / 人際合盤
- `POST /api/v1/kids` — Kids daily fortune / 兒童每日運勢
- `POST /api/v1/face` — Face reading / 面相解讀
- `POST /api/v1/aura` — Aura reading / 氣場解讀
- `POST /api/v1/couple-face` — Couple face match / 夫妻臉分析

## Data handling

- MCP tool arguments are used only to calculate the requested response.
- MCP tools do not persist birth data or full tool arguments.
- Operational telemetry contains the tool name, success status, latency, schema version, protocol version, and a shortened client User-Agent only.
- Avoid submitting another person's birth data without their permission.

## Interpretation notice

- English: For entertainment and personal reflection only. Do not use this result as medical, legal, financial, or other professional advice.
- 繁體中文：本結果僅供娛樂與個人反思，不應作為醫療、法律、財務或其他專業建議。