{"openapi":"3.1.0","info":{"title":"data-api","version":"0.1.0","description":"Snapshot API for hot lists, reports, feeds, live news and deal alerts. Report sources are checked at Beijing midnight; JSON date-time values use Asia/Shanghai (+08:00)."},"paths":{"/health":{"get":{"summary":"Process health","responses":{"200":{"description":"Process is running"}}}},"/ready":{"get":{"summary":"Storage readiness","responses":{"200":{"description":"Storage is reachable"},"503":{"description":"Storage is unavailable"}}}},"/v1/channels":{"get":{"summary":"List published channels","responses":{"200":{"description":"Channel catalog"}}}},"/v1/channels/{id}/items":{"get":{"summary":"Read one published channel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Channel snapshot"},"404":{"description":"Not published"},"503":{"description":"No usable snapshot"}}}},"/v1/hotlists":{"get":{"summary":"Aggregate published hot lists","parameters":[{"name":"category","in":"query","schema":{"type":"string"}},{"name":"channel","in":"query","description":"Comma-separated channel IDs","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Aggregate items with source coverage. JSON aggregation defaults to channel groups; set AGGREGATE_MODE=sorted to return globally sorted items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregateResponse"}}}}}}},"/v1/feeds":{"get":{"summary":"Aggregate published feed items","parameters":[{"name":"category","in":"query","schema":{"type":"string"}},{"name":"channel","in":"query","description":"Comma-separated channel IDs","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Aggregate items with source coverage. JSON aggregation defaults to channel groups; set AGGREGATE_MODE=sorted to return globally sorted items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregateResponse"}}}}}}},"/v1/reports":{"get":{"summary":"Aggregate published daily, weekly and monthly reports","description":"Returns fresh, stale, partial or unavailable status plus sourceStatus coverage.","parameters":[{"name":"category","in":"query","schema":{"type":"string"}},{"name":"channel","in":"query","description":"Comma-separated channel IDs","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"period","in":"query","schema":{"type":"string","enum":["daily","weekly","monthly","digest","newsletter"]}},{"name":"edition","in":"query","schema":{"type":"string","enum":["morning","noon","evening","weekly","monthly"]}},{"name":"periodKey","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"includeSummary","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Aggregate items with source coverage. JSON aggregation defaults to channel groups; set AGGREGATE_MODE=sorted to return globally sorted items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregateResponse"}}}}}}},"/v1/reports/{id}/items":{"get":{"summary":"Read one published report channel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","schema":{"type":"string","enum":["daily","weekly","monthly","digest","newsletter"]}},{"name":"edition","in":"query","schema":{"type":"string","enum":["morning","noon","evening","weekly","monthly"]}},{"name":"periodKey","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"includeSummary","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Report channel snapshot"},"404":{"description":"Not published"},"503":{"description":"No usable snapshot"}}}},"/v1/news/live":{"get":{"summary":"Aggregate published live-news items","parameters":[{"name":"category","in":"query","schema":{"type":"string"}},{"name":"channel","in":"query","description":"Comma-separated channel IDs","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Aggregate items with source coverage. JSON aggregation defaults to channel groups; set AGGREGATE_MODE=sorted to return globally sorted items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregateResponse"}}}}}}},"/v1/deals":{"get":{"summary":"Aggregate published deal alerts","parameters":[{"name":"category","in":"query","schema":{"type":"string"}},{"name":"channel","in":"query","description":"Comma-separated channel IDs","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Aggregate items with source coverage. JSON aggregation defaults to channel groups; set AGGREGATE_MODE=sorted to return globally sorted items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregateResponse"}}}}}}},"/v1/cps":{"get":{"summary":"Aggregate credential-enabled CPS promotional resources","parameters":[{"name":"category","in":"query","schema":{"type":"string"}},{"name":"channel","in":"query","description":"Comma-separated channel IDs","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Aggregate items with source coverage. JSON aggregation defaults to channel groups; set AGGREGATE_MODE=sorted to return globally sorted items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregateResponse"}}}}}}},"/v1/hotlists.rss":{"get":{"summary":"Aggregate hot lists as RSS 2.0","responses":{"200":{"description":"RSS XML","content":{"application/rss+xml":{}}}}}},"/v1/feeds.rss":{"get":{"summary":"Aggregate feed items as RSS 2.0","responses":{"200":{"description":"RSS XML","content":{"application/rss+xml":{}}}}}},"/v1/news/live.rss":{"get":{"summary":"Aggregate live news as RSS 2.0","responses":{"200":{"description":"RSS XML","content":{"application/rss+xml":{}}}}}},"/v1/deals.rss":{"get":{"summary":"Aggregate deal alerts as RSS 2.0","responses":{"200":{"description":"RSS XML","content":{"application/rss+xml":{}}}}}},"/v1/reports.rss":{"get":{"summary":"Aggregate reports as RSS 2.0","responses":{"200":{"description":"RSS XML","content":{"application/rss+xml":{}}}}}},"/v1/channels/{id}.rss":{"get":{"summary":"Read one channel as RSS 2.0","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"RSS XML","content":{"application/rss+xml":{}}},"404":{"description":"Not published"},"503":{"description":"No usable snapshot"}}}},"/internal/collect":{"get":{"summary":"Vercel Cron entry for due collection","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Collection results"},"401":{"description":"Unauthorized"}}},"post":{"summary":"Collect enabled sources that are due","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Collection results"},"401":{"description":"Unauthorized"}}}},"/internal/cps/convert":{"post":{"summary":"Convert an allow-listed platform URL with the configured CPS account","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Attributed promotion URL"},"400":{"description":"Invalid platform URL"},"401":{"description":"Unauthorized"},"404":{"description":"Platform unavailable"},"502":{"description":"Upstream conversion failed"}}}},"/internal/status":{"get":{"summary":"Inspect enabled source health","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Source states"},"401":{"description":"Unauthorized"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AggregateStatus":{"type":"string","enum":["fresh","stale","partial","unavailable"]},"SourceStatus":{"type":"object","required":["total","withData","failed"],"properties":{"total":{"type":"integer"},"withData":{"type":"integer"},"failed":{"type":"integer"}}},"AggregateResponse":{"type":"object","required":["status","total","items","sourceStatus","mode"],"properties":{"status":{"$ref":"#/components/schemas/AggregateStatus"},"total":{"type":"integer"},"mode":{"type":"string","enum":["grouped","sorted"],"description":"Effective aggregation mode. grouped is the default JSON response; sorted is enabled by AGGREGATE_MODE."},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Item"},{"type":"object","required":["channelId","channelName"],"properties":{"channelId":{"type":"string"},"channelName":{"type":"string"}}}]}},"nextCursor":{"type":"string"},"groups":{"type":"array","description":"Channel-separated data in grouped mode. Each group is independently limited by limit.","items":{"$ref":"#/components/schemas/AggregateGroup"}},"sourceStatus":{"$ref":"#/components/schemas/SourceStatus"}}},"AggregateGroup":{"type":"object","required":["channelId","channelName","status","total","items"],"properties":{"channelId":{"type":"string"},"channelName":{"type":"string"},"status":{"$ref":"#/components/schemas/AggregateStatus"},"fetchedAt":{"type":"string","format":"date-time"},"validatedAt":{"type":"string","format":"date-time"},"total":{"type":"integer"},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Item"},{"type":"object","required":["channelId","channelName"],"properties":{"channelId":{"type":"string"},"channelName":{"type":"string"}}}]}}}},"Item":{"type":"object","required":["title","url"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"rank":{"type":"integer"},"hot":{"oneOf":[{"type":"number"},{"type":"string"}]},"description":{"type":"string"},"imageUrl":{"type":"string","format":"uri"},"publishedAt":{"type":"string","format":"date-time","description":"RFC 3339 date-time in Asia/Shanghai (+08:00)"},"rankingId":{"type":"string"},"rankingName":{"type":"string"},"surface":{"type":"string","enum":["hotlist","live","deal","cps","feed","report","digest","authority"]},"reportPeriod":{"type":"string","enum":["daily","weekly","monthly","digest","newsletter"]},"edition":{"type":"string","enum":["morning","noon","evening","weekly","monthly"]},"periodKey":{"type":"string"},"provider":{"type":"string"},"providerUrl":{"type":"string","format":"uri"}}}}}}