API 开发文档

纸鱼博客提供只读 JSON API，方便对接前端应用、微信小程序、静态站点和其他内容工具。

API v1 的基础地址为：

https://你的域名/api/v1

开启 API

登录后台，进入“站点设置 → 开放 API”：

1. 开启“启用开放 API”。

2. 生成或复制 API Key。

3. 按需设置每分钟请求上限、单页最大条数和 CORS 来源。

API Key 只应保存在服务端或受信任的应用中，不要写入公开的前端代码。Key 泄露后请立即重新生成，旧 Key 会失效。

请求鉴权

所有 /api/v1 接口都需要在请求头中携带：

X-API-Key: 你的 API Key

示例：

curl -H "X-API-Key: 你的 API Key" \
  https://example.com/api/v1/posts

文章列表

GET /api/v1/posts

查询参数：

示例：

curl -G -H "X-API-Key: 你的 API Key" \
  --data-urlencode "page=1" \
  --data-urlencode "perPage=10" \
  --data-urlencode "category=php" \
  https://example.com/api/v1/posts

只返回已发布且已到发布时间的文章。返回示例：

{
  "posts": [
    {
      "id": "1",
      "title": "文章标题",
      "slug": "article-slug",
      "excerpt": "文章摘要",
      "coverUrl": null,
      "publishedAt": "2026-09-13T02:00:00Z",
      "viewCount": 12,
      "likeCount": 3,
      "favoriteCount": 1,
      "isPinned": false,
      "categoryPinned": false,
      "hasPassword": false,
      "externalUrl": null,
      "category": {"name": "技术", "slug": "tech"},
      "tags": [{"name": "PHP", "slug": "php"}],
      "author": "admin"
    }
  ],
  "total": 1,
  "page": 1,
  "perPage": 10,
  "totalPages": 1
}

列表接口不返回正文。密码文章只返回 hasPassword: true，不会返回文章密码。

文章详情

GET /api/v1/posts/{slug}

示例：

curl -H "X-API-Key: 你的 API Key" \
  https://example.com/api/v1/posts/article-slug

返回文章列表中的全部字段，并额外包含：

草稿、回收站文章、未到发布时间的定时文章和不存在的 slug 都返回 404。

分类、标签和站点信息

GET /api/v1/categories
GET /api/v1/tags
GET /api/v1/site

分类返回 id、name、slug、description、parentId 和 postCount。标签返回 id、name、slug 和 postCount。站点信息返回 name、subtitle、description、url 和 version。

评论列表

GET /api/v1/comments?postId=1&page=1&perPage=50

postId 必填；page 默认 1，perPage 默认 50，最大值为 100。接口只返回已审核通过的评论。

返回字段包括 id、postId、parentId、authorName、content、createdAt、isPinned 和 likeCount。createdAt 使用 UTC ISO-8601 格式，parentId 可用于还原楼中楼结构。

页面、友链和导航

GET /api/v1/pages
GET /api/v1/links
GET /api/v1/menus

这些接口分别返回已发布的独立页面、可见友链和可见导航项。它们不提供分页。

CORS

后台“开放 API”中的“CORS 来源”支持填写一个或多个来源，多个来源用逗号分隔，例如：

https://app.example.com, https://admin.example.com

留空表示不返回 CORS 响应头。配置 * 可以允许任意来源，但不建议与公开部署的 API Key 一起使用。

限流与错误响应

默认每个 API Key 和客户端 IP 每分钟最多请求 120 次，可在后台修改。超过限制返回 429。

错误响应为 JSON：

{"error":"无效的 API Key"}

常见状态码：