MOSS GARDEN FOR AGENTS · API v1

你的 AI，
也有一张阅读证。

结构化目录、干净的 Markdown、明确的订阅权限。

01 / QUICK START

从「苔花精选」开始。

将 BASE_URL 设为苔藓花园正式站点地址。下面的命令可直接用于正式接口。

BASH

BASE_URL="https://mossgarden.cn"

# 获取免费文章目录
curl "$BASE_URL/api/v1/articles?access=free&limit=1"

# 读取免费文章的 Markdown 正文
curl "$BASE_URL/api/v1/articles/archive-2026-08-11-ae11c1d2dc39?format=markdown"

02 / AUTHENTICATION

一个 Key，只授予阅读权限。

订阅正文使用标准 Bearer 鉴权。密钥权限为 articles:read，不能修改账户或支付信息。不要把密钥放进网址或提交到公开代码仓库。

BASH

BASE_URL="https://mossgarden.cn"
# 从你的安全环境中读取 MOSS_GARDEN_API_KEY
curl "$BASE_URL/api/v1/me" \
  -H "Authorization: Bearer $MOSS_GARDEN_API_KEY"

curl "$BASE_URL/api/v1/articles/research-notebook-sample?format=markdown" \
  -H "Authorization: Bearer $MOSS_GARDEN_API_KEY"

订阅和密钥必须同时在有效期内。撤销密钥后，下一次请求就会被拒绝。

个人划线与评论可用下方接口一次导出。JSON 是默认格式；format=markdown 可下载 Markdown。接口只返回密钥所属用户的记录，包括未公开的内容。

BASH

curl "https://mossgarden.cn/api/v1/me/annotations?format=markdown" \
+  -H "Authorization: Bearer $MOSS_GARDEN_API_KEY" \
+  -o mossgarden-annotations.md

03 / ENDPOINTS

为自动化准备的接口。

方法与路径	用途	权限
`GET /api/v1/articles`	公开目录与分页	无需密钥
`GET /api/v1/articles/{slug}`	单篇 JSON / Markdown	订阅正文需密钥
`POST /api/v1/articles/batch`	批量读取，最多 20 篇	需要密钥
`GET /api/v1/me`	订阅状态与密钥权限	需要密钥
`GET /api/v1/me/annotations`	一键导出自己的划线与评论	需要密钥

目录支持 limit（1–50）、offset、category 和 access=free|member。按 pagination.next_offset 翻页，直到值为 null。

接口值 access=member 表示付费订阅权限；向读者展示时请称为“订阅文章”。

JSON · 免费目录响应示例

{
  "data": [{
    "slug": "archive-2026-10-01-61ea56229255",
    "title": "Attention Is All You Need：注意力就是你所需要的一切",
    "access": "free",
    "author": "苔藓花园"
  }],
  "pagination": {
    "limit": 1, "offset": 0, "total": 3,
    "has_more": true, "next_offset": 1
  }
}

文章和总数会随站点更新；上面仅展示响应中的部分字段。

04 / BATCH READS

一次拿到一组阅读材料。

批量接口需要密钥，每次最多 20 个不重复的文章标识。单篇不存在时，该条返回 not_found，其余文章继续返回。

BASH

BASE_URL="https://mossgarden.cn"
curl -X POST "$BASE_URL/api/v1/articles/batch" \
  -H "Authorization: Bearer $MOSS_GARDEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slugs":["archive-2026-08-11-ae11c1d2dc39","research-notebook-sample"]}'

请保留原文的标题、作者、出处与更新时间。is_demo=1 表示阅读样稿，不能当作正式研究报告引用。

05 / LIMITS & ERRORS

知道什么时候继续，什么时候停下。

每个密钥每分钟最多 60 次鉴权请求。批量读取计为一次请求。X-RateLimit-Remaining 表示剩余额度。

400 参数或 JSON 无效，请修正后重试。
401 密钥缺失、无效、已撤销，或订阅未生效 / 已到期。
404 文章不存在或未发布。
429 请求过于频繁，按 Retry-After 等待。
503 服务暂不可用，或相应功能尚未开通。

当前开放了什么？

文章目录与免费正文：已可访问。

订阅正文：有效阅读密钥可访问。

批量接口与权限校验：已可访问。

注册仅可阅读免费内容。付费订阅有效期间，可在「我的订阅」创建和撤销 Agent 阅读密钥。年度订阅支持微信扫码支付。

前往我的订阅