{"openapi":"3.0.3","info":{"title":"WeRSS API","version":"1.0.0","description":"WeRSS 公开只读 API：搜索公众号 / 文章，读取文章流，并输出 RSS / Atom / JSON Feed。\n\n在账户设置页创建 / 重置绑定到当前账户的 API Key（格式 `wer_...`）。\n服务端配置的 `ARTICLES_API_TOKEN` 仍可作为可选系统 Key 使用。\n\n以下两种请求头任选其一：\n\n- `Authorization: Bearer <key>`\n- `X-API-Key: <key>`\n\nKey 缺失、错误、已重置或账户不可用时返回 401。\n除 `/api/v1/openapi.json` 外，所有接口都需要鉴权。"},"servers":[{"url":"https://rss.tdzero.com","description":"WeRSS"}],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"tags":[{"name":"Search","description":"搜索公众号和文章"},{"name":"Accounts","description":"公众号资料与文章"},{"name":"Feed","description":"文章流与 Feed 文档"},{"name":"Meta","description":"OpenAPI 描述"}],"paths":{"/api/v1/search":{"get":{"tags":["Search"],"operationId":"search","summary":"搜索公众号和文章","description":"账号仅返回 status=active 的记录，匹配名称、alias、gh_id；文章仅返回 status=ready 的记录，匹配标题、摘要、作者和公众号名。q 为空时返回热门账号 / 最新文章。","parameters":[{"$ref":"#/components/parameters/Q"},{"$ref":"#/components/parameters/SearchType"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/SearchPageSize"}],"responses":{"200":{"description":"搜索成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/accounts/{idOrGhId}":{"get":{"tags":["Accounts"],"operationId":"getAccount","summary":"获取公众号资料和文章","description":"idOrGhId 支持账号 UUID、gh_id 或 alias。只返回 ready 文章，按发布时间倒序。","parameters":[{"name":"idOrGhId","in":"path","required":true,"description":"账号 UUID、gh_id 或 alias。","schema":{"type":"string"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/AccountLimit"},{"$ref":"#/components/parameters/Full"}],"responses":{"200":{"description":"账号详情","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDetailResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/feed":{"get":{"tags":["Feed"],"operationId":"getFeed","summary":"读取文章流 / 输出 Feed 文档","description":"默认返回 JSON 文章流。format=rss|atom|jsonfeed 时直接返回对应 Feed 文档。文章均来自 status=ready 的记录，按发布时间倒序。","parameters":[{"$ref":"#/components/parameters/FeedFormat"},{"$ref":"#/components/parameters/GhId"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/Q"},{"$ref":"#/components/parameters/AfterAt"},{"$ref":"#/components/parameters/BeforeAt"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/FeedPageSize"},{"$ref":"#/components/parameters/Full"}],"responses":{"200":{"description":"JSON 文章流，或 RSS / Atom / JSON Feed 文档（由 format 决定）。","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedJsonResponse"}},"application/rss+xml":{"schema":{"type":"string"}},"application/atom+xml":{"schema":{"type":"string"}},"application/feed+json":{"schema":{"type":"object"}}}},"304":{"description":"Feed 文档未变化（ETag 命中）"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/openapi.json":{"get":{"tags":["Meta"],"operationId":"getOpenApi","summary":"获取 OpenAPI 描述","security":[],"responses":{"200":{"description":"OpenAPI 3.0 文档","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"账户设置中创建的 API Key，或服务端 ARTICLES_API_TOKEN。"},"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"与 Bearer 相同的 Key。"}},"parameters":{"Q":{"name":"q","in":"query","required":false,"description":"搜索关键词，最大 200 字符。为空时返回默认列表。","schema":{"type":"string","maxLength":200}},"SearchType":{"name":"type","in":"query","required":false,"description":"搜索类型，默认 all。","schema":{"type":"string","enum":["all","account","article"],"default":"all"}},"Page":{"name":"page","in":"query","required":false,"description":"页码，从 1 开始。","schema":{"type":"integer","minimum":1,"maximum":1000000,"default":1}},"SearchPageSize":{"name":"page_size","in":"query","required":false,"description":"搜索每页数量，1-50。","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},"FeedPageSize":{"name":"page_size","in":"query","required":false,"description":"文章流每页数量，1-200。","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},"AccountLimit":{"name":"limit","in":"query","required":false,"description":"账号详情返回的文章数量，1-50。","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},"GhId":{"name":"gh_id","in":"query","required":false,"description":"按公众号 gh_id 或 alias 过滤。","schema":{"type":"string"}},"AccountId":{"name":"account_id","in":"query","required":false,"description":"按公众号 UUID 过滤。","schema":{"type":"string","format":"uuid"}},"AfterAt":{"name":"after_at","in":"query","required":false,"description":"发布时间下界（含）。支持 ISO 时间、Unix 秒或 Unix 毫秒。","schema":{"type":"string"}},"BeforeAt":{"name":"before_at","in":"query","required":false,"description":"发布时间上界（含）。支持 ISO 时间、Unix 秒或 Unix 毫秒。","schema":{"type":"string"}},"Full":{"name":"full","in":"query","required":false,"description":"是否返回正文。JSON 默认 0；RSS / Atom / JSON Feed 默认 1。","schema":{"type":"string","enum":["0","1","false","true"]}},"FeedFormat":{"name":"format","in":"query","required":false,"description":"输出格式：json 为统一 JSON 文章流；其余直接返回 Feed 文档。","schema":{"type":"string","enum":["json","rss","atom","jsonfeed"],"default":"json"}}},"responses":{"BadRequest":{"description":"参数不合法","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"缺少或错误的 API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"资源不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","example":"unauthorized"},"message":{"type":"string","example":"A valid API key is required."}}},"Pagination":{"type":"object","required":["page","page_size","total","has_more"],"properties":{"page":{"type":"integer","minimum":1,"example":1},"page_size":{"type":"integer","minimum":1,"example":20},"total":{"type":"integer","minimum":0,"example":42},"has_more":{"type":"boolean","example":true}}},"AccountSummary":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"gh_id":{"type":"string","nullable":true},"name":{"type":"string"},"alias":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true}}},"Account":{"type":"object","required":["id","name","status","follower_count"],"properties":{"id":{"type":"string","format":"uuid"},"biz_id":{"type":"string","nullable":true},"gh_id":{"type":"string","nullable":true},"name":{"type":"string"},"alias":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"follower_count":{"type":"integer"},"status":{"type":"string","enum":["pending","active","rejected","archived"]},"ready_articles":{"type":"integer"},"last_synced_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true}}},"Article":{"type":"object","required":["id","title","url","source_url","published_at","account"],"properties":{"id":{"type":"string","format":"uuid"},"biz_id":{"type":"string","nullable":true},"mid":{"type":"string","nullable":true},"idx":{"type":"integer","nullable":true},"sn":{"type":"string","nullable":true},"title":{"type":"string"},"digest":{"type":"string","nullable":true},"author":{"type":"string","nullable":true},"cover_url":{"type":"string","nullable":true,"description":"图片已通过 /api/media 代理，避免微信 CDN 防盗链。"},"url":{"type":"string","description":"优先返回抓取链接，否则返回原文链接。"},"source_url":{"type":"string"},"fetch_url":{"type":"string","nullable":true},"published_at":{"type":"string","format":"date-time","nullable":true},"fetched_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"account":{"$ref":"#/components/schemas/AccountSummary"},"content_html":{"type":"string","nullable":true,"description":"仅在 full=1 时返回，图片链接已重写。"},"content_text":{"type":"string","nullable":true,"description":"仅在 full=1 时返回。"}}},"AccountPage":{"type":"object","required":["items","page","page_size","total","has_more"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Account"}},"page":{"type":"integer","minimum":1,"example":1},"page_size":{"type":"integer","minimum":1,"example":20},"total":{"type":"integer","minimum":0,"example":42},"has_more":{"type":"boolean","example":true}}},"ArticlePage":{"type":"object","required":["items","page","page_size","total","has_more"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Article"}},"page":{"type":"integer","minimum":1,"example":1},"page_size":{"type":"integer","minimum":1,"example":20},"total":{"type":"integer","minimum":0,"example":42},"has_more":{"type":"boolean","example":true}}},"SearchResponse":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["query","type"],"properties":{"query":{"type":"string"},"type":{"type":"string","enum":["all","account","article"]},"accounts":{"$ref":"#/components/schemas/AccountPage"},"articles":{"$ref":"#/components/schemas/ArticlePage"}}}}},"AccountDetailResponse":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["account","articles","page","page_size","total","has_more"],"properties":{"account":{"$ref":"#/components/schemas/Account"},"articles":{"type":"array","items":{"$ref":"#/components/schemas/Article"}},"page":{"type":"integer","minimum":1,"example":1},"page_size":{"type":"integer","minimum":1,"example":20},"total":{"type":"integer","minimum":0,"example":42},"has_more":{"type":"boolean","example":true}}}}},"FeedJsonResponse":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["items","page","page_size","total","has_more","filters"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Article"}},"page":{"type":"integer","minimum":1,"example":1},"page_size":{"type":"integer","minimum":1,"example":20},"total":{"type":"integer","minimum":0,"example":42},"has_more":{"type":"boolean","example":true},"filters":{"type":"object","properties":{"gh_id":{"type":"string","nullable":true},"account_id":{"type":"string","nullable":true},"q":{"type":"string","nullable":true},"after_at":{"type":"string","format":"date-time","nullable":true},"before_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}}}