主要端点

完整 OpenAPI Schema 见 https://bestblogs.dev/api/v2/openapi.json。本页只列最常用的几条。

Discover（发现）

GET /api/v2/resources — 列精选内容

返回经过 AI 初评 + 专家精审的内容列表。

参数	类型	说明
type	string	article / podcast / video / tweet / newsletter
category	string	分类 slug，例 ai-engineering
language	string	zh / en / all
time	string	24h / 3d / 1w / 1m / all
qualified	boolean	true 仅返回 Featured 精选
score	string	例 80+
limit	int	默认 20，最大 100
cursor	string	翻页游标

GET /api/v2/topics — 主题（Topic）列表

curl https://bestblogs.dev/api/v2/topics?type=event&limit=10 \
  -H "Authorization: Bearer $KEY"

GET /api/v2/brief?date=YYYY-MM-DD — 取某日早报

参数	说明
date	默认今天，格式 YYYY-MM-DD（周日无早报）
flavor	public（默认）/ personal（Pro，需 read:personal scope）

GET /api/v2/sources — 公共订阅源目录

支持按 category / language / type 筛选，分页同上。

Read（阅读）

GET /api/v2/resources/{id} — 单条详情

返回完整正文 + AI 摘要 + 关键观点 + 标签。

POST /api/v2/copilot/summary — 调用 AI 摘要

{
  "resourceId": "art_123",
  "style": "key_points"  // key_points / quotes / socratic
}

返回结构化的摘要 + 引用段落。

POST /api/v2/copilot/ask — 针对内容追问

{
  "resourceId": "art_123",
  "question": "作者推荐的 Agent 架构是什么？"
}

Capture（沉淀，写入）

需要 write:capture scope。

POST /api/v2/bookmarks — 收藏

{
  "resourceId": "art_123",
  "folderId": "fld_inbox",
  "tags": ["待写", "灵感"],
  "note": "对比 Mastra 的 Workflow"
}

POST /api/v2/highlights — 划线

{
  "resourceId": "art_123",
  "text": "AI handles volume, experts handle quality.",
  "comment": "BestBlogs 的核心机制",
  "anchor": { "selector": "p:nth-child(7)" }
}

POST /api/v2/history — 上报阅读历史

智能体或第三方阅读器在用户实际阅读后调用。

{
  "resourceId": "art_123",
  "durationMs": 240000,
  "completedAt": "2026-04-26T08:30:00Z"
}

通用响应

所有端点统一返回：

{
  "data": [/* 资源数组 */],
  "pagination": {
    "nextCursor": "eyJ...",
    "hasMore": true
  },
  "meta": {
    "total": 1234,
    "requestId": "req_abc"
  }
}

错误响应：

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "retryAfterSec": 12
  }
}

---