# SatNet News · v1 API 参考

只在需要完整参数、字段或翻页时读这个文件；普通问答照 `SKILL.md` 的路由表走就行。

- Base URL：`https://satnet.news`；匿名只读，不需要 API Key，不发送 cookie。
- OpenAPI：`https://satnet.news/openapi.json`
- 参数不合法时返回明确的错误 JSON：`{"error": "invalid_window", "detail": "...", "status": 400}`，不会悄悄回到默认值。
- 每个响应都带 `ETag`；下次带 `If-None-Match`，内容没变回 `304`。

## 最近资讯、分类与搜索

`GET /api/v1/items`

| 参数 | 说明 |
|---|---|
| `mode` | `selected`（精选，默认）或 `all`（全部相关动态） |
| `window` | `24h`、`7d` 或 `30d`；不传则为 24 小时 |
| `by` | `timeline`（默认，与网页一致）或 `published`（严格按原文发布时间） |
| `category` | 北斗 / 国内卫星互联网 / 国际卫星互联网 / 政策标准 / 产业链 / 其他 |
| `q` | 关键词，2—60 字，匹配标题、摘要、机构名 |
| `topic` | 主题 slug，见 `/api/v1/topics` |
| `ids` | 逗号分隔的条目编号（此时忽略时间窗） |
| `limit` | 1—200，默认 30 |
| `cursor` | 原样回传上一页的 `page.nextCursor`；换了任何查询参数旧 cursor 就失效（返回 `invalid_cursor`） |

响应：

```json
{
  "schemaVersion": 1,
  "query": {"mode": "selected", "window": "24h", "by": "timeline", "category": null, "q": null, "topic": null},
  "items": [],
  "page": {"count": 0, "hasMore": false, "nextCursor": null}
}
```

每条 item：

- `id`、`title`（中文标题，可能是 AI 翻译/改写的）、`originalTitle`（来源原标题）
- `summary`、`reason`（推荐理由，可能为 null）、`category`、`score`（0—100，可能为 null）、`selected`
- `source.name`、`source.tier`（T1 官方一手 / T1.5 权威媒体 / T2 其它）
- `links.site`（本站阅读页，默认主链接）、`links.original`（第三方原文）、`links.story`（所属事件页，可能为 null）
- `publishedAt`（原文发布时间，可能为 null）、`discoveredAt`（本站收录时间）、`timelineAt`（时间线上的位置）
- `dims`（五维分：relevance / importance / firsthand / novelty / substance）、`entities`（涉及的机构 / 主体）、`storyId`
- 还有一组下划线命名的旧字段（`url`、`site_url`、`published_at` 等），只为兼容早期接入的程序，新代码不要依赖。

时间口径：`by=timeline` 时，原文发布后 72 小时内被收录的按 `discoveredAt` 算，超过 72 小时的历史回填按 `publishedAt` 算；`publishedAt` 为空时按 `discoveredAt`。

## 当前热点

`GET /api/v1/hot-topics`（可选 `days` 1—30，默认 2；不足 3 个事件时自动放宽到 7 天；`limit` 1—50，默认 10）

响应 `{schemaVersion, windowDays, count, items}`。每个 item：`rank`（从 1 开始）、`title`、`summary`、`category`、`status`（"爆" = 5 家以上信源，"新" = 24 小时内出现，或 null）、`trend`（up / down / flat / new / null，和约 24 小时前比）、`heat`、`heatDelta24h`、`sourceCount`、`itemCount`、`latestAt`、`links.story`（给人看的事件页）、`links.api`（事件详情接口）、`sources[]`。

## 事件详情

`GET /api/v1/stories/{id}`：`story.reports` 是按时间倒序的全部报道，`story.lead` 是最权威的那一条（官方一手优先），`story.status` 为 `developing` 或 `settled`（超过 48 小时没有新报道）。

## 日报 / 周报 / 月报

```text
GET /api/v1/dailies?limit=7          日报索引
GET /api/v1/dailies/latest           最新一期
GET /api/v1/dailies/2026-09-18       指定日期
GET /api/v1/reports/weekly           周报索引（key 形如 2026-W38）
GET /api/v1/reports/weekly/latest
GET /api/v1/reports/monthly/2026-09
```

正文在 `contentMarkdown`（Markdown），收录的条目编号在 `itemIds`，可以再用 `items?ids=` 取结构化数据。

## 主题与其它

- `GET /api/v1/topics`：长期线索清单（slug、名称、关键词）。
- `GET /api/v1/categories`：分类取值。
- `GET /api/v1/stats`：收录总数、精选数、热点事件数、今日更新数。