{"openapi":"3.1.0","info":{"title":"苔藓花园文章 API","version":"1.0.0","description":"Read-only article retrieval for free content, trial and annual subscriptions. First website registration grants one calendar month of trial. Create a personal Bearer key at /account. Payment purchases are not open."},"servers":[{"url":"https://mossgarden.marwen.top"}],"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","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"]}}],"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, its expiry, and subscription (plan trial or annual, status, expires_at). membership is a backward-compatible alias of subscription. Both trial and annual subscriptions can access protected content. This Bearer key cannot manage accounts or other keys."}}}}