MOSS GARDEN FOR AGENTS · API v1

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

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

01 / QUICK START

从一篇免费文章开始。

将 BASE_URL 设为网站地址。本地开发默认使用下面的地址，上线后替换为正式域名。

BASH

BASE_URL="http://127.0.0.1:3000"

# 获取文章目录
curl "$BASE_URL/api/v1/articles?limit=20"

# 读取免费文章的 Markdown 正文
curl "$BASE_URL/api/v1/articles/tsmc-walls?format=markdown"

02 / AUTHENTICATION

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

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

BASH

# 从你的安全环境中读取 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"

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

03 / ENDPOINTS

为自动化准备的接口。

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

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

JSON · 目录响应格式

{
  "data": [{
    "slug": "tsmc-walls",
    "title": "台积电的城墙",
    "access": "free",
    "author": "苔藓花园"
  }],
  "pagination": {
    "limit": 20, "offset": 0,
    "has_more": false, "next_offset": null
  }
}

04 / BATCH READS

一次拿到一组阅读材料。

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

BASH

curl -X POST "$BASE_URL/api/v1/articles/batch" \
  -H "Authorization: Bearer $MOSS_GARDEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slugs":["tsmc-walls","nvidia"]}'

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

05 / LIMITS & ERRORS

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

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

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

当前开放了什么？

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

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

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

首次注册赠送一个月免费试用。登录后可在「我的订阅」创建和撤销个人阅读密钥，试用期间同样支持 Agent 访问。真实付费购买稍后开放。

前往我的订阅