# Web3Fire API v1 — OpenAPI 规范

> 端点: `https://web3fire.com/api/v1/` · 认证: 公开（除 claims 需 OAuth session）
> 速率限制: 60 req/min/IP · 缓存: `s-maxage=300`

## 端点一览

### GET /api/v1/entities
实体列表（分页）。

**参数**

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `lang` | string | en | 语言（11 种） |
| `type` | string | — | 过滤实体类型（concept/project/tool/chain/person…） |
| `limit` | int | 20 | 每页条数（≤100） |
| `offset` | int | 0 | 偏移 |

**响应** `200`
```json
{
  "entities": [{ "id": "ent-bitcoin", "type": "concept", "slug": "bitcoin", "title": "Bitcoin", "trust_score": 100 }],
  "total": 430,
  "limit": 20, "offset": 0
}
```

### GET /api/v1/entities/[slug]
实体详情（含翻译/分数/关系摘要）。

**参数** `lang`（可选，默认 en）

**响应** `200`
```json
{
  "entity": { "id": "ent-bitcoin", "type": "concept", "slug": "bitcoin", "trust_score": 100 },
  "translation": { "lang": "en", "title": "Bitcoin", "summary": "..." },
  "score": { "quality_score": 90, "authority_score": 100 }
}
```
**错误** `404`（实体不存在）

### POST /api/v1/claims
提交实体信息更正请求（需 Google OAuth session）。

**请求体** `{ "entity_slug": "bitcoin", "contact": "email", "note": "..." }`

**响应** `200` / `401`（未登录）/ `400`（缺 entity_slug）

### GET /api/entity/[slug]
公开实体详情 API（fields 投影）。

**参数** `lang` / `fields`（逗号分隔：summary,relations,compare,sources,timeline,faq,evidence,trust,freshness）

**响应** `200`
```json
{
  "identity": { "id": "ent-bitcoin", "type": "concept", "slug": "bitcoin", "status": "published", "title": "Bitcoin" },
  "summary": "...", "score": { "authority_score": 100 }, "relations": { "outgoing": [], "incoming": [] }
}
```

### GET /api/search
全文搜索（FTS5，含别名/意图路由）。

**参数** `q`（必填）/ `lang`

**响应** `200`
```json
{ "results": [{ "type": "entity", "slug": "bitcoin", "title": "Bitcoin", "summary": "..." }], "total": 15 }
```
**错误** `429`（超 60 req/min/IP）

### GET /api/news · /api/concepts · /api/tools · /api/projects · /api/chains · /api/people
各类型列表（SSOT COUNT）。

**参数** `lang`

### GET /api/compare/[slug]
对比详情（comparison + entities + dimensions + valuesByEntity）。

### GET /api/health
健康检查（D1 连接 + 实体统计 + freshness）。

---

## 错误码

| 码 | 说明 |
|---|---|
| 400 | 参数错误 |
| 401 | 需 OAuth session |
| 404 | 资源不存在 |
| 429 | 速率限制（60 req/min/IP） |
| 500 | 服务端错误（不泄露细节） |

---

## 示例

```bash
# 实体列表
curl "https://web3fire.com/api/v1/entities?type=concept&limit=5"

# 实体详情（中文）
curl "https://web3fire.com/api/v1/entities/bitcoin?lang=zh-CN"

# 搜索
curl "https://web3fire.com/api/search?q=ethereum&lang=en"

# 字段投影
curl "https://web3fire.com/api/entity/ethereum?fields=evidence,trust,freshness"
```

> 完整交互式文档见 `/en/developers/playground/`（API Playground）。