# Quizzman Astro — Public APIs (detailed)

- Markdown: https://astro.quizzman.com/about-api.md
- Overview guide: https://astro.quizzman.com/guide/API_OVERVIEW.md
- OpenAPI (zodiac-support): https://astro.quizzman.com/openapi-zodiac-support.yaml
- LLM index: https://astro.quizzman.com/llms.txt
- Base host: `https://astro.quizzman.com`

## One-sentence definition

Quizzman Astro exposes a small HTTP surface for **health**, **full sky frames**, **civil-day almanacs**, and **zodiac-support** snapshots/events — powered by the same ephemeris engine as the Sky Viewer.

## Endpoint map

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| `GET` | `/health` | none | Liveness JSON |
| `GET` | `/viewer/sky` | none | Planetarium / Explorer frame |
| `GET` | `/astro/day-sky` | none | Civil-day almanac |
| `GET` | `/v1/zodiac-support/catalog` | Bearer* | Signs / half-signs / body names |
| `GET`\|`POST` | `/v1/zodiac-support/snapshot` | Bearer* | Instant chart fields |
| `POST` | `/v1/zodiac-support/snapshot/range` | Bearer* | Multi-day series (max 93 pts) |
| `GET` | `/v1/zodiac-support/sun-sign-calendar` | Bearer* | Year calendar by sign/half |
| `POST` | `/v1/zodiac-support/events` | Bearer* | Ingress / station / moon / solar term |
| `POST` | `/v1/zodiac-support/aspects` | Bearer* | Major aspects |

\*Bearer required only when server env `QM_ASTRO_ALLOWED_TOKENS` is non-empty. If empty (dev), auth is disabled and `meta.warnings` may include `auth_disabled`.

---

## `GET /health`

```bash
curl -s 'https://astro.quizzman.com/health'
```

Example:

```json
{"ok":true,"service":"qm-astro","version":"0.1.0"}
```

---

## `GET /viewer/sky`

Builds one observation frame: time, observer, Sun/Moon/planets, stars, DSO, ISS, grids metadata, astrology angles, explorer relative bodies, `ephemeris_backend`.

### Query parameters

| Param | Default / notes |
|-------|-----------------|
| `jd` | Julian Day UT |
| `lat`, `lon` | Observer degrees (VN defaults if omitted) |
| `magLimit` | Star magnitude cutoff (e.g. `4`) |
| `center` | `earth` \| `sun` \| `moon` \| planet id |
| `zodiac` | `tropical` \| `sidereal` |
| `az`, `alt`, `fov` | Camera hints |

### Example

```bash
curl -s 'https://astro.quizzman.com/viewer/sky?jd=2460000.5&lat=10.82&lon=106.63&magLimit=4&center=earth' \
  | head -c 500
```

### Agent tips

- Always read `ephemeris_backend` before claiming DE440-level precision.  
- For non-Earth `center`, use `data.explorer.bodies[]` (`distance_au`, Cartesian `x,y,z`).  
- UI guide: https://astro.quizzman.com/about-sky-viewer.md  

---

## `GET /astro/day-sky`

Civil-day almanac for calendrics and the Viewer’s date path.

### Query

| Param | Required | Notes |
|-------|----------|-------|
| `date` | yes | `YYYY-MM-DD` |
| `timezone` | no | `VN` (+7) or `CN` (+8) |
| `longitude` | no | East degrees (True Solar / local noon context) |

### Example

```bash
curl -s 'https://astro.quizzman.com/astro/day-sky?date=2026-07-27&timezone=VN&longitude=106.63'
```

Typical fields (names may be camelCase):

- `jdLocalNoon` / `jdn`  
- `solarTerm.currentTerm`  
- `newMoon.previous` / `newMoon.next`  
- `synodicAgeDays`  

Sky Viewer often loads day-sky first, then `/viewer/sky?jd=…`.

---

## `/v1/zodiac-support/*`

HTTP contract for **qm-zodiacsign** → **qm-astro**.

### Auth headers (when tokens enabled)

```http
Authorization: Bearer <service_token>
X-Quizzman-Service: qm-zodiacsign
X-Request-Id: <uuid>
X-Astro-Api-Version: 1
```

### Success envelope

```json
{
  "success": true,
  "meta": {
    "requestId": "…",
    "ephemeris": "de440+vsop+elp",
    "frame": "tropical_ecliptic",
    "serverTime": "…Z",
    "apiVersion": "1"
  },
  "data": {}
}
```

### Snapshot contents (conceptual)

Bodies with ecliptic longitude/speed/retrograde, half-sign, angles (Asc/MC when lat/lon present), Moon phase, solar term.

### Specs & examples

- OpenAPI: https://astro.quizzman.com/openapi-zodiac-support.yaml  
- Guide: https://astro.quizzman.com/guide/ZODIAC_SUPPORT_API.md  
- Curl examples (repo): `docs/examples/zodiac-support/`  

Agents should not invent Asc/MC without lat/lon; should not claim anonymous access if production tokens are required.

---

## Discovery files for AI

| File | URL |
|------|-----|
| llms.txt | https://astro.quizzman.com/llms.txt |
| llms-full.txt | https://astro.quizzman.com/llms-full.txt |
| docs-index.json | https://astro.quizzman.com/docs-index.json |
| search.json | https://astro.quizzman.com/search.json |
| sitemap.xml | https://astro.quizzman.com/sitemap.xml |
| robots.txt | https://astro.quizzman.com/robots.txt |

## Error / honesty policy

- Prefer linking live curls and `/paper/report.json` over paraphrased accuracy numbers.  
- Distinguish **public** sky/day-sky from **service-token** zodiac routes.  
- Calendar folklore and quiz apps belong to other Quizzman hosts — Astro is the astronomy service.