{"openapi":"3.1.0","info":{"title":"苔藓花园文章 API","version":"1.0.0","description":"Read-only article retrieval and private per-user highlight/comment export. Registration and historical trials grant free-content access only. An active paid annual subscription is required for protected content and Agent keys. Annual subscriptions can be purchased through the site's configured checkout."},"servers":[{"url":"https://mossgarden.cn"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ArticleSummary":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"},"excerpt":{"type":"string"},"author":{"type":"string"},"category":{"type":"string"},"cover":{"type":"string"},"updated_at":{"type":"string"},"published_at":{"type":"string"},"access":{"type":"string","description":"free is public; member is the stable API value for paid subscription access. Display member as 付费订阅文章 in Chinese.","enum":["free","member"]},"is_demo":{"type":"integer","enum":[0,1]},"source_url":{"type":["string","null"]}},"required":["id","slug","title","access"]},"Article":{"allOf":[{"$ref":"#/components/schemas/ArticleSummary"},{"type":"object","properties":{"content":{"type":"string","description":"Markdown body"},"format":{"const":"markdown"}}}]}}},"paths":{"/api/v1/articles":{"get":{"operationId":"listArticles","summary":"公开文章目录，不返回正文","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"access","in":"query","schema":{"type":"string","enum":["free","member"]}},{"name":"q","in":"query","description":"按标题、副标题或作者搜索，最多 120 个字符。","schema":{"type":"string","maxLength":120}}],"responses":{"200":{"description":"Metadata with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ArticleSummary"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"},"next_offset":{"type":["integer","null"]}}}}}}}},"400":{"description":"Invalid request"},"401":{"description":"Invalid or expired access"},"404":{"description":"Not found"},"429":{"description":"Rate limited; obey Retry-After"},"503":{"description":"Service unavailable"}}}},"/api/v1/articles/{slug}":{"get":{"operationId":"getArticle","summary":"单篇正文；订阅文章需密钥","security":[{},{"BearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","markdown"],"default":"json"}}],"responses":{"200":{"description":"Authorized article","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Article"}}}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request"},"401":{"description":"Invalid or expired access"},"404":{"description":"Not found"},"429":{"description":"Rate limited; obey Retry-After"},"503":{"description":"Service unavailable"}}}},"/api/v1/articles/batch":{"post":{"operationId":"batchArticles","summary":"批量读取最多 20 篇","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slugs":{"type":"array","minItems":1,"maxItems":20,"uniqueItems":true,"items":{"type":"string","pattern":"^[a-z0-9-]{1,100}$"}}},"required":["slugs"]}}}},"responses":{"200":{"description":"Articles and per-item not_found errors","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Article"},{"type":"object","properties":{"slug":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}]}}}}}}},"400":{"description":"Invalid request"},"401":{"description":"Invalid or expired access"},"404":{"description":"Not found"},"429":{"description":"Rate limited; obey Retry-After"},"503":{"description":"Service unavailable"}}}},"/api/v1/me":{"get":{"operationId":"getMembership","summary":"密钥权限与订阅有效期","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Membership expiry and key scope"},"400":{"description":"Invalid request"},"401":{"description":"Invalid or expired access"},"404":{"description":"Not found"},"429":{"description":"Rate limited; obey Retry-After"},"503":{"description":"Service unavailable"}},"description":"Returns key scope, expiry and the active paid annual subscription. membership is a backward-compatible alias of subscription. Historical trials do not grant protected content access. Reading keys cannot manage accounts or keys."}},"/api/article-assets/{id}":{"get":{"operationId":"getArticleImage","summary":"读取文章配图；付费配图需有效年度订阅 Bearer Key","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"}}],"security":[{},{"BearerAuth":[]}],"responses":{"200":{"description":"WebP image; private no-store","content":{"image/webp":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"付费图片未授权"},"404":{"description":"图片不存在或文章未发布"}}}},"/api/v1/me/annotations":{"get":{"operationId":"exportMyAnnotations","summary":"导出密钥所属用户的全部划线和评论","description":"包含公开和私密记录；只返回当前 Bearer 密钥所属用户的数据。网页用户中心也提供一键下载。","security":[{"BearerAuth":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","markdown"],"default":"json"}}],"responses":{"200":{"description":"Download personal JSON or Markdown export"},"400":{"description":"Invalid format"},"401":{"description":"Invalid or expired key"},"429":{"description":"Rate limited"}}}}}}