post HTML content
\",\n \"language\": \"en\",\n \"url\": \"https://truthsocial.com/@realDonaldTrump/...\",\n \"account\": { \"username\": \"realDonaldTrump\", \"followers_count\": 9200000, \"verified\": true, ... },\n \"media_attachments\": [ { \"id\": \"...\", \"type\": \"image\", \"url\": \"/media/....png\", \"preview_url\": \"...\", ... } ],\n \"card\": { \"url\": \"...\", \"title\": \"...\", \"description\": \"...\", \"image\": \"...\", \"provider_name\": \"...\" }, // or null\n \"replies_count\": 1200,\n \"reblogs_count\": 2100,\n \"favourites_count\": 8500,\n \"_analysis\": { ... } // AnalysisResult if available, else null\n }\n ],\n \"total\": 842,\n \"page\": 1,\n \"limit\": 20,\n \"hasMore\": true\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"posts":[{"id":"114090816417968547","created_at":"2025-02-28T14:23:00.000Z","content":"post HTML content
","language":"en","url":"https://truthsocial.com/@realDonaldTrump/...","account":{"username":"realDonaldTrump","followers_count":9200000,"verified":true},"media_attachments":[{"id":"...","type":"image","url":"/media/....png","preview_url":"..."}],"card":{"url":"...","title":"...","description":"...","image":"...","provider_name":"..."},"replies_count":1200,"reblogs_count":2100,"favourites_count":8500,"_analysis":{}}],"total":842,"page":1,"limit":20,"hasMore":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"page","in":"query","required":false,"description":"Page number (1-based); values below 1 are clamped to 1, and 0 or a non-numeric value falls back to 1.","schema":{"type":"integer","default":1,"minimum":1}},{"name":"limit","in":"query","required":false,"description":"Posts per page, clamped to 1–100; 0 or a non-numeric value falls back to 20.","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring search over the post text and the linked card's title and description.","schema":{"type":"string","example":"tariff"}},{"name":"from","in":"query","required":false,"description":"Date range start, YYYY-MM-DD (inclusive, from 00:00 UTC).","schema":{"type":"string","example":"2025-03-01"}},{"name":"to","in":"query","required":false,"description":"Date range end, YYYY-MM-DD (inclusive, through 23:59:59.999 UTC).","schema":{"type":"string","example":"2025-03-31"}}]}},"/api/analyze":{"post":{"operationId":"analyze","tags":["Trump Truth Social"],"summary":"AI analysis of a Trump post's market impact","description":"Returns the cached `AnalysisResult` when one exists (with `X-AI-Provider: cache`); otherwise runs the LLM on the post text, its linked article excerpt and attached images, stores the result, and returns it with `X-AI-Provider` / `X-AI-Model` headers.\n\n⚠ This endpoint triggers an LLM call (typically ~60 s; the route allows up to 300 s). Returns `202` if analysis is already in progress for this post.\n\nCached results are served with `X-AI-Provider: cache` and `X-AI-Model: cached`; fresh results carry the provider and model that produced them.\n\nLLM-backed: counts against the `llm` rate limit and returns `X-AI-Provider` / `X-AI-Model` headers.\n\n```bash\ncurl -X POST https://news.all-vista.org/api/analyze -H \"Content-Type: application/json\" -d '{\"post_id\": \"114090816417968547\"}'\n```","responses":{"200":{"description":"AnalysisResult\n\n```json\n{\n \"topic\": \"tariff\", // macro|energy|tariff|social_media|legal|election|other\n \"impact_direction\": \"bearish\", // bullish|bearish|neutral|uncertain\n \"impact_magnitude\": 2, // 0-3\n \"confidence\": 0.85, // 0.0-1.0\n \"suggested_symbols\": [\"SPY\", \"QQQ\", \"EEM\"],\n \"headline\": \"...\", // Chinese headline\n \"headline_en\": \"...\", // English headline\n \"translation\": \"...\", // Chinese translation of post\n \"rationale\": \"...\", // Chinese summary\n \"rationale_en\": \"...\", // English summary\n \"key_points\": [\"...\"], // Chinese key points\n \"key_points_en\": [\"...\"], // English key points\n \"market_impact\": \"...\", // Chinese detailed analysis\n \"market_impact_en\": \"...\", // English detailed analysis\n \"risk_factors\": [\"...\"], // Chinese risk factors\n \"risk_factors_en\": [\"...\"], // English risk factors\n \"time_horizon\": \"short_term\" // short_term|medium_term|long_term|unclear\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"topic":"tariff","impact_direction":"bearish","impact_magnitude":2,"confidence":0.85,"suggested_symbols":["SPY","QQQ","EEM"],"headline":"...","headline_en":"...","translation":"...","rationale":"...","rationale_en":"...","key_points":["..."],"key_points_en":["..."],"market_impact":"...","market_impact_en":"...","risk_factors":["..."],"risk_factors_en":["..."],"time_horizon":"short_term"}}}},"202":{"description":"Analysis already in progress for this post — retry later"},"400":{"description":"Missing `post_id`"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Post not found"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Analysis failed (all LLM providers errored)"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"post_id":{"type":"string","example":"114090816417968547","description":"Truth Social post ID."}},"required":["post_id"]}}}},"x-llm":true}},"/api/trump-impact":{"get":{"operationId":"trumpImpact","tags":["Trump Truth Social"],"summary":"Market reaction to Trump posts — per-post session moves or a rolling summary","description":"Exactly one of `ids` or `summary` is required; `ids` takes precedence when both are present. Each post maps to the first US session it could move (posts at or after 16:00 ET, or on a weekend / holiday, roll to the next session) and the reaction is that session's close-to-close % move for SPY, QQQ, TLT, USO, GLD and IBIT.\n\nClose-to-close moves of the session a post landed in. This is correlation, not attribution — several posts usually share one session.\n\n`pending` means the session has not closed or its bars have not arrived yet (files land about 00:10 ET the next day); such rows are re-evaluated after 10 minutes. Unknown ids come back as `no_data`. The summary is memoised for 10 minutes per `days` value and lists at most 5 `topPosts` (one representative post per session).\n\n```bash\ncurl \"https://news.all-vista.org/api/trump-impact?summary=30\"\n\ncurl \"https://news.all-vista.org/api/trump-impact?ids=114090816417968547,114090900000000000\"\n```","responses":{"200":{"description":"PostReaction / ImpactSummary\n\n```json\n// ?ids=114090816417968547\n{\n \"reactions\": {\n \"114090816417968547\": {\n \"session\": \"2025-02-28\", // US session the post maps to; null while pending / no_data\n \"status\": \"done\", // done | pending | no_data\n \"moves\": { \"SPY\": -1.59, \"QQQ\": -2.11, \"TLT\": 0.42, \"USO\": -0.8, \"GLD\": 0.31, \"IBIT\": -3.2 }\n }\n }\n}\n\n// ?summary=30\n{\n \"days\": 30,\n \"posts\": 212, \"postsDone\": 204, \"postsPending\": 8,\n \"postsWithSpyMoveGe1pct\": 61,\n \"avgAbsSpyOnPostingDays\": 0.84, // mean |SPY %| over sessions with >= 1 post (null when none)\n \"avgAbsSpyAllDays\": 0.71, // mean |SPY %| over every completed session in the window\n \"sessions\": 21, \"postingSessions\": 19,\n \"latestSession\": \"2026-08-14\",\n \"topPosts\": [\n { \"id\": \"...\", \"created_at\": \"...\", \"headline\": \"...\", \"headline_en\": \"...\", \"url\": \"...\",\n \"session\": \"2026-08-14\", \"spyPct\": -2.31, \"sessionPosts\": 4 }\n ],\n \"generatedAt\": \"2026-08-15T12:00:00.000Z\"\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"x-example-text":"// ?ids=114090816417968547\n{\n \"reactions\": {\n \"114090816417968547\": {\n \"session\": \"2025-02-28\", // US session the post maps to; null while pending / no_data\n \"status\": \"done\", // done | pending | no_data\n \"moves\": { \"SPY\": -1.59, \"QQQ\": -2.11, \"TLT\": 0.42, \"USO\": -0.8, \"GLD\": 0.31, \"IBIT\": -3.2 }\n }\n }\n}\n\n// ?summary=30\n{\n \"days\": 30,\n \"posts\": 212, \"postsDone\": 204, \"postsPending\": 8,\n \"postsWithSpyMoveGe1pct\": 61,\n \"avgAbsSpyOnPostingDays\": 0.84, // mean |SPY %| over sessions with >= 1 post (null when none)\n \"avgAbsSpyAllDays\": 0.71, // mean |SPY %| over every completed session in the window\n \"sessions\": 21, \"postingSessions\": 19,\n \"latestSession\": \"2026-08-14\",\n \"topPosts\": [\n { \"id\": \"...\", \"created_at\": \"...\", \"headline\": \"...\", \"headline_en\": \"...\", \"url\": \"...\",\n \"session\": \"2026-08-14\", \"spyPct\": -2.31, \"sessionPosts\": 4 }\n ],\n \"generatedAt\": \"2026-08-15T12:00:00.000Z\"\n}"}}},"400":{"description":"Neither `ids` nor `summary` given; `ids` not 1–60 numeric ids; or `summary` not an integer 1–365"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Internal error"}},"parameters":[{"name":"ids","in":"query","required":false,"description":"1–60 comma-separated numeric Truth Social post ids (duplicates removed) → `{ reactions: { [id]: PostReaction } }`.","schema":{"type":"string","description":"Comma-separated string values","example":"114090816417968547,114090900000000000"}},{"name":"summary","in":"query","required":false,"description":"Look-back window in days → `ImpactSummary`. An empty value (`?summary=`) means 30.","schema":{"type":"integer","default":30,"example":30,"minimum":1,"maximum":365}}]}},"/api/trump-intraday":{"get":{"operationId":"trumpIntraday","tags":["Trump Truth Social"],"summary":"15- and 60-minute market moves after each Trump post (SPY, QQQ, mentioned tickers)","description":"Exactly one of `ids` or `summary` is required; `ids` takes precedence. Posts inside 09:30–15:45 ET on a session are measured from the last 1-minute bar before the post (`mode: rth`); anything else is measured from the next session's 09:30 open (`mode: session_open`).\n\nPre-computed on the AWS market database from 1-minute bars (`trump_intraday.json`, twice daily). Posts outside regular hours are measured from the next session open and flagged `session_open`. `available: false` until the job has delivered a file.\n\nIds the job has not seen yet are `pending` when the post is newer than the snapshot it consumed, `no_data` otherwise. `moves` holds SPY, QQQ and up to three of the post's own symbols.\n\n```bash\ncurl \"https://news.all-vista.org/api/trump-intraday?summary=1\"\n\ncurl \"https://news.all-vista.org/api/trump-intraday?ids=115123456789012345\"\n```","responses":{"200":{"description":"IntradayReaction / IntradaySummaryResponse\n\n```json\n// ?ids=115123456789012345\n{\n \"reactions\": {\n \"115123456789012345\": {\n \"status\": \"done\", // done | pending | no_data\n \"mode\": \"rth\", // rth | session_open (null while pending / no_data)\n \"session\": \"2026-09-01\",\n \"anchor_ts\": \"2026-09-01T14:42:00Z\", // last 1-minute bar before the post (UTC)\n \"truncated\": false, // session closed before the +60 mark; its last bar was used\n \"moves\": { \"SPY\": { \"m15\": 0.21, \"m60\": -0.05 }, \"QQQ\": { ... }, \"TSLA\": { ... } },\n \"spy15_pct_rank\": 62 // |SPY 15m| percentile vs every 15-minute SPY window of the period\n }\n }\n}\n\n// ?summary=1\n{\n \"available\": true, // false (other fields null / 0) until the AWS job has delivered a file\n \"generated_at\": \"2026-09-02T13:57:00+00:00\",\n \"days\": 90,\n \"window\": { \"start\": \"2026-06-04\", \"end\": \"2026-09-01\" },\n \"last_session\": \"2026-09-01\",\n \"baseline\": { \"symbol\": \"SPY\", \"sessions\": 62, \"n15\": 24180, \"n60\": 22940,\n \"abs15\": { \"mean\": 0.080, \"p50\": 0.05, \"p75\": 0.09, \"p90\": 0.16, \"p95\": 0.22, \"p99\": 0.41 },\n \"abs60\": { ... } },\n \"summary\": {\n \"posts\": 812, \"done\": 790, \"pending\": 12, \"no_data\": 10,\n \"rth\": 310, \"session_open\": 480, \"truncated\": 6,\n \"big_move_pct\": 0.5, \"spy15_big\": 14, \"spy15_big_share\": 0.018,\n \"rth_mean_abs_spy15\": 0.074, \"rth_mean_abs_spy60\": 0.15, \"session_open_mean_abs_spy15\": 0.12,\n \"baseline_mean_abs15\": 0.080, \"baseline_mean_abs60\": 0.17,\n \"top\": [ { \"id\": \"...\", \"created_at\": \"...\", \"mode\": \"rth\", \"session\": \"...\", \"anchor_ts\": \"...\",\n \"spy15\": -0.62, \"spy60\": -0.9, \"spy15_pct_rank\": 99, \"truncated\": false, \"anchor_posts\": 1,\n \"moves\": { ... }, \"headline\": \"...\", \"headline_en\": \"...\", \"url\": \"...\" } ]\n }\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"x-example-text":"// ?ids=115123456789012345\n{\n \"reactions\": {\n \"115123456789012345\": {\n \"status\": \"done\", // done | pending | no_data\n \"mode\": \"rth\", // rth | session_open (null while pending / no_data)\n \"session\": \"2026-09-01\",\n \"anchor_ts\": \"2026-09-01T14:42:00Z\", // last 1-minute bar before the post (UTC)\n \"truncated\": false, // session closed before the +60 mark; its last bar was used\n \"moves\": { \"SPY\": { \"m15\": 0.21, \"m60\": -0.05 }, \"QQQ\": { ... }, \"TSLA\": { ... } },\n \"spy15_pct_rank\": 62 // |SPY 15m| percentile vs every 15-minute SPY window of the period\n }\n }\n}\n\n// ?summary=1\n{\n \"available\": true, // false (other fields null / 0) until the AWS job has delivered a file\n \"generated_at\": \"2026-09-02T13:57:00+00:00\",\n \"days\": 90,\n \"window\": { \"start\": \"2026-06-04\", \"end\": \"2026-09-01\" },\n \"last_session\": \"2026-09-01\",\n \"baseline\": { \"symbol\": \"SPY\", \"sessions\": 62, \"n15\": 24180, \"n60\": 22940,\n \"abs15\": { \"mean\": 0.080, \"p50\": 0.05, \"p75\": 0.09, \"p90\": 0.16, \"p95\": 0.22, \"p99\": 0.41 },\n \"abs60\": { ... } },\n \"summary\": {\n \"posts\": 812, \"done\": 790, \"pending\": 12, \"no_data\": 10,\n \"rth\": 310, \"session_open\": 480, \"truncated\": 6,\n \"big_move_pct\": 0.5, \"spy15_big\": 14, \"spy15_big_share\": 0.018,\n \"rth_mean_abs_spy15\": 0.074, \"rth_mean_abs_spy60\": 0.15, \"session_open_mean_abs_spy15\": 0.12,\n \"baseline_mean_abs15\": 0.080, \"baseline_mean_abs60\": 0.17,\n \"top\": [ { \"id\": \"...\", \"created_at\": \"...\", \"mode\": \"rth\", \"session\": \"...\", \"anchor_ts\": \"...\",\n \"spy15\": -0.62, \"spy60\": -0.9, \"spy15_pct_rank\": 99, \"truncated\": false, \"anchor_posts\": 1,\n \"moves\": { ... }, \"headline\": \"...\", \"headline_en\": \"...\", \"url\": \"...\" } ]\n }\n}"}}},"400":{"description":"Neither `ids` nor `summary` given, or `ids` not 1–60 numeric ids"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Internal error"}},"parameters":[{"name":"ids","in":"query","required":false,"description":"1–60 comma-separated numeric post ids (duplicates removed) → `{ reactions: { [id]: IntradayReaction } }`.","schema":{"type":"string","description":"Comma-separated string values","example":"115123456789012345"}},{"name":"summary","in":"query","required":false,"description":"Any value (conventionally `1`) returns the period summary instead of per-post rows.","schema":{"type":"string","example":"1"}}]}},"/api/x-posts":{"get":{"operationId":"xPosts","tags":["X Financial News"],"summary":"Paginated feed of curated financial news from X/Twitter","description":"Newest first. Each post carries `_analysis` (the cached `XAnalysisResult` from `POST /api/x-analyze` or `POST /api/x-analyze-batch`, or `null`).\n\n```bash\ncurl \"https://news.all-vista.org/api/x-posts?limit=10\"\n\ncurl \"https://news.all-vista.org/api/x-posts?author=Reuters&page=1&limit=20\"\n```","responses":{"200":{"description":"XPostPage\n\n```json\n{\n \"posts\": [\n {\n \"id\": \"x_2032098083790561289\",\n \"timestamp\": \"2026-03-17T08:32:00.000Z\",\n \"raw_text\": \"BREAKING: Fed holds rates steady...\",\n \"author\": \"Reuters\",\n \"_analysis\": { \"direction\": \"neutral\", \"translation\": \"...\", \"one_liner\": \"...\", \"one_liner_en\": \"...\" } // or null\n }\n ],\n \"total\": 915,\n \"page\": 1,\n \"limit\": 50,\n \"hasMore\": true\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"posts":[{"id":"x_2032098083790561289","timestamp":"2026-03-17T08:32:00.000Z","raw_text":"BREAKING: Fed holds rates steady...","author":"Reuters","_analysis":{"direction":"neutral","translation":"...","one_liner":"...","one_liner_en":"..."}}],"total":915,"page":1,"limit":50,"hasMore":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"page","in":"query","required":false,"description":"Page number (1-based).","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","required":false,"description":"Posts per page.","schema":{"type":"integer","default":50}},{"name":"before","in":"query","required":false,"description":"Cursor: only posts strictly older than this ISO 8601 timestamp (page then counts from there). Invalid → 400. Added 2026-10-20; the feed pages use it instead of offsets.","schema":{"type":"string","example":"2026-10-18T12:00:00Z"}},{"name":"author","in":"query","required":false,"description":"Filter by author handle, exact match (e.g. \"WSJ\", \"zerohedge\").","schema":{"type":"string","example":"Reuters"}}]}},"/api/x-analyze":{"post":{"operationId":"xAnalyze","tags":["X Financial News"],"summary":"AI sentiment analysis of an X financial news post","description":"Returns the cached result when one exists (with `X-AI-Provider: cache`); otherwise classifies the headline with the LLM, stores it, and returns it with `X-AI-Provider` / `X-AI-Model` headers.\n\n⚠ Triggers an LLM call (~60 s). Returns `202` if in progress.\n\nLLM-backed: counts against the `llm` rate limit and returns `X-AI-Provider` / `X-AI-Model` headers.\n\n```bash\ncurl -X POST https://news.all-vista.org/api/x-analyze -H \"Content-Type: application/json\" -d '{\"message_id\": \"x_2032098083790561289\"}'\n```","responses":{"200":{"description":"XAnalysisResult\n\n```json\n{\n \"direction\": \"bearish\", // bullish|bearish|neutral|uncertain\n \"translation\": \"...\", // Chinese translation\n \"one_liner\": \"...\", // Chinese market commentary\n \"one_liner_en\": \"...\" // English market commentary\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"direction":"bearish","translation":"...","one_liner":"...","one_liner_en":"..."}}}},"202":{"description":"Analysis already in progress for this post — retry later"},"400":{"description":"Missing `message_id`"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Message not found"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Analysis failed (all LLM providers errored)"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","example":"x_2032098083790561289","description":"X post ID as returned by `/api/x-posts`."}},"required":["message_id"]}}}},"x-llm":true}},"/api/x-analyze-batch":{"post":{"operationId":"xAnalyzeBatch","tags":["X Financial News"],"summary":"Classify up to 25 X headlines in one LLM call","description":"Fills the same cache as `POST /api/x-analyze` for many posts at once. Ids that are already cached or unknown are dropped before the call; only the remaining headlines are sent, in a single prompt. The body reports counts only — read the results back through `/api/x-posts` (`_analysis`).\n\n⚠ One LLM call per request, with a 240 s timeout (route `maxDuration` is 300 s). Use a client timeout of about 290 s.\n\nWhen every id is cached or unknown the route answers `200` with `analyzed: 0` and `provider: null` without calling the LLM. Otherwise `X-AI-Provider` / `X-AI-Model` headers name the provider that ran. Headlines are truncated to 600 characters in the prompt.\n\nDriven hourly by `scripts/analyze_trending.py`, which sends the last 24 h of posts for the trending tickers in chunks of 20 (route limit is 25) and counts a `500` as a spent LLM call.\n\nLLM-backed: counts against the `llm` rate limit and returns `X-AI-Provider` / `X-AI-Model` headers.\n\n```bash\ncurl -X POST https://news.all-vista.org/api/x-analyze-batch -H \"Content-Type: application/json\" -d '{\"ids\": [\"x_2032098083790561289\", \"x_2032098083790561290\"]}'\n```","responses":{"200":{"description":"BatchAnalysisReport\n\n```json\n{\n \"requested\": 20, // distinct ids in the request\n \"analyzed\": 17, // items the model returned well-formed; written to the cache\n \"skipped_cached\": 2, // ids that already had an analysis (not sent)\n \"skipped_unknown\": 0, // ids not present in the X archive (not sent)\n \"failed\": 1, // sent ids the model skipped or returned malformed\n \"provider\": \"anthropic\", // null when nothing was sent (no LLM call)\n \"model\": \"claude-sonnet-4-6\"\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"requested":20,"analyzed":17,"skipped_cached":2,"skipped_unknown":0,"failed":1,"provider":"anthropic","model":"claude-sonnet-4-6"}}}},"202":{"description":"The same set of uncached ids is already being analysed — retry later"},"400":{"description":"Body is not JSON, or `ids` is not an array of 1–25 non-empty strings (each ≤ 64 chars)"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Batch analysis failed (the LLM call errored; nothing was cached)"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"example":"[\"x_2032098083790561289\", \"x_2032098083790561290\"]","description":"1–25 X post ids (non-empty strings of at most 64 characters; duplicates removed)."}},"required":["ids"]}}}},"x-llm":true}},"/api/x-digest":{"post":{"operationId":"xDigest","tags":["X Financial News"],"summary":"AI-generated summary of X news over a time window","description":"Cached per `{window}_{start}`: a repeat call with the same `window` and the identical `start` string returns the stored digest (with `X-AI-Provider: cache`). Posts with `start <= timestamp < end` are summarised.\n\n⚠ Triggers an LLM call (~120 s; the route allows up to 300 s). Returns `202` if in progress. Max 300 headlines per digest (the newest 300 in the window).\n\n`window` must be one of the four listed values and `start` / `end` must parse as timestamps (Date.parse); all three are checked before the cache lookup. The cache key still uses the raw `start` string, so send the canonical YYYY-MM-DDTHH:MM:SS.000Z form to hit the same digest as `GET /api/digests`.\n\nLLM-backed: counts against the `llm` rate limit and returns `X-AI-Provider` / `X-AI-Model` headers.\n\n```bash\ncurl -X POST https://news.all-vista.org/api/x-digest -H \"Content-Type: application/json\" -d '{\"window\": \"1d\", \"start\": \"2026-04-01T00:00:00.000Z\", \"end\": \"2026-04-02T00:00:00.000Z\"}'\n```","responses":{"200":{"description":"DigestResult\n\n```json\n{\n \"sentiment\": \"bearish\", // bullish|bearish|neutral|mixed\n \"title\": \"...\", // Chinese one-line title\n \"title_en\": \"...\", // English one-line title\n \"summary\": \"...\", // Chinese 2-3 paragraph analysis\n \"summary_en\": \"...\", // English 2-3 paragraph analysis\n \"key_themes\": [\"tariffs\", \"fed policy\", \"tech earnings\"],\n \"notable_tickers\": [\"NVDA\", \"TSLA\", \"SPY\"]\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sentiment":"bearish","title":"...","title_en":"...","summary":"...","summary_en":"...","key_themes":["tariffs","fed policy","tech earnings"],"notable_tickers":["NVDA","TSLA","SPY"]}}}},"202":{"description":"Digest for this window/start is already being generated — retry later"},"400":{"description":"Missing `window`, `start` or `end`; `window` not one of 4h, 12h, 1d, 1w (`window must be one of 4h, 12h, 1d, 1w`); or `start` / `end` not parseable as ISO-8601 timestamps"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No posts in range"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Digest failed (all LLM providers errored)"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"window":{"type":"string","enum":["4h","12h","1d","1w"],"example":"1d","description":"Time window label; becomes the prefix of the cache key."},"start":{"type":"string","example":"2026-04-01T00:00:00.000Z","description":"Window start, ISO 8601 (inclusive). Use the exact form YYYY-MM-DDTHH:MM:SS.000Z so the key matches `GET /api/digests`."},"end":{"type":"string","example":"2026-04-02T00:00:00.000Z","description":"Window end, ISO 8601 (exclusive)."}},"required":["window","start","end"]}}}},"x-llm":true}},"/api/bwe-posts":{"get":{"operationId":"bwePosts","tags":["BWE Crypto News"],"summary":"Paginated feed of BWE crypto/blockchain news with AI analysis","description":"Newest first. `source` and `headline` are parsed from `raw_text` (format `**SOURCE: headline**`). Each post carries `_analysis` (the cached `BWEAnalysisResult` from `POST /api/bwe-analyze`, or `null`).\n\n```bash\ncurl \"https://news.all-vista.org/api/bwe-posts?limit=10\"\n\ncurl \"https://news.all-vista.org/api/bwe-posts?source=Binance%20EN&limit=20\"\n```","responses":{"200":{"description":"BWEPostPage\n\n```json\n{\n \"posts\": [\n {\n \"id\": \"bwe_20260401_001\",\n \"timestamp\": \"2026-04-01T08:00:00.000Z\",\n \"raw_text\": \"**Binance EN: BTC breaks $90K...**\\n...\",\n \"source\": \"Binance EN\",\n \"headline\": \"BTC breaks $90K resistance\",\n \"_analysis\": {\n \"direction\": \"bullish\",\n \"translation\": \"...\",\n \"one_liner\": \"...\",\n \"one_liner_en\": \"...\"\n }\n }\n ],\n \"total\": 61,\n \"page\": 1,\n \"limit\": 50,\n \"hasMore\": true\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"posts":[{"id":"bwe_20260401_001","timestamp":"2026-04-01T08:00:00.000Z","raw_text":"**Binance EN: BTC breaks $90K...**\n...","source":"Binance EN","headline":"BTC breaks $90K resistance","_analysis":{"direction":"bullish","translation":"...","one_liner":"...","one_liner_en":"..."}}],"total":61,"page":1,"limit":50,"hasMore":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"page","in":"query","required":false,"description":"Page number (1-based).","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","required":false,"description":"Posts per page.","schema":{"type":"integer","default":50}},{"name":"before","in":"query","required":false,"description":"Cursor: only posts strictly older than this ISO 8601 timestamp (page then counts from there). Invalid → 400. Added 2026-10-20; the feed pages use it instead of offsets.","schema":{"type":"string","example":"2026-10-18T12:00:00Z"}},{"name":"source","in":"query","required":false,"description":"Filter by source, exact match (e.g. \"DB\", \"AggrNews\", \"Binance EN\").","schema":{"type":"string","example":"Binance EN"}}]}},"/api/bwe-analyze":{"post":{"operationId":"bweAnalyze","tags":["BWE Crypto News"],"summary":"AI sentiment analysis of a BWE crypto/blockchain headline","description":"Returns the cached result when one exists (with `X-AI-Provider: cache`); otherwise classifies the parsed `headline` with the LLM, stores it, and returns it with `X-AI-Provider` / `X-AI-Model` headers.\n\n⚠ Triggers an LLM call (~60 s). Returns `202` if in progress.\n\nLLM-backed: counts against the `llm` rate limit and returns `X-AI-Provider` / `X-AI-Model` headers.\n\n```bash\ncurl -X POST https://news.all-vista.org/api/bwe-analyze -H \"Content-Type: application/json\" -d '{\"message_id\": \"bwe_20260312_001\"}'\n```","responses":{"200":{"description":"BWEAnalysisResult\n\n```json\n{\n \"direction\": \"bullish\", // bullish|bearish|neutral|uncertain\n \"translation\": \"...\", // Chinese translation\n \"one_liner\": \"...\", // Chinese market commentary\n \"one_liner_en\": \"...\" // English market commentary\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"direction":"bullish","translation":"...","one_liner":"...","one_liner_en":"..."}}}},"202":{"description":"Analysis already in progress for this post — retry later"},"400":{"description":"Missing `message_id`"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Message not found"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Analysis failed (all LLM providers errored)"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","example":"bwe_20260312_001","description":"BWE post ID as returned by `/api/bwe-posts`."}},"required":["message_id"]}}}},"x-llm":true}},"/api/bwe-digest":{"post":{"operationId":"bweDigest","tags":["BWE Crypto News"],"summary":"AI-generated summary of BWE crypto news over a time window","description":"Cached per `{window}_{start}`: a repeat call with the same `window` and the identical `start` string returns the stored digest (with `X-AI-Provider: cache`). Every post with `start <= timestamp < end` is sent to the model (no headline cap).\n\n⚠ Triggers an LLM call (~120 s; the route allows up to 300 s). Returns `202` if in progress.\n\n`window` must be one of the four listed values and `start` / `end` must parse as timestamps (Date.parse); all three are checked before the cache lookup. The cache key still uses the raw `start` string, so send the canonical YYYY-MM-DDTHH:MM:SS.000Z form to hit the same digest as `GET /api/digests`.\n\nLLM-backed: counts against the `llm` rate limit and returns `X-AI-Provider` / `X-AI-Model` headers.\n\n```bash\ncurl -X POST https://news.all-vista.org/api/bwe-digest -H \"Content-Type: application/json\" -d '{\"window\": \"1d\", \"start\": \"2026-04-01T00:00:00.000Z\", \"end\": \"2026-04-02T00:00:00.000Z\"}'\n```","responses":{"200":{"description":"DigestResult\n\n```json\n{\n \"sentiment\": \"mixed\", // bullish|bearish|neutral|mixed\n \"title\": \"...\", // Chinese one-line title\n \"title_en\": \"...\", // English one-line title\n \"summary\": \"...\", // Chinese 2-3 paragraph analysis\n \"summary_en\": \"...\", // English 2-3 paragraph analysis\n \"key_themes\": [\"BTC ETF\", \"DeFi regulation\"],\n \"notable_tickers\": [\"BTC\", \"ETH\", \"SOL\"]\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"sentiment":"mixed","title":"...","title_en":"...","summary":"...","summary_en":"...","key_themes":["BTC ETF","DeFi regulation"],"notable_tickers":["BTC","ETH","SOL"]}}}},"202":{"description":"Digest for this window/start is already being generated — retry later"},"400":{"description":"Missing `window`, `start` or `end`; `window` not one of 4h, 12h, 1d, 1w (`window must be one of 4h, 12h, 1d, 1w`); or `start` / `end` not parseable as ISO-8601 timestamps"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No posts in range"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Digest failed (all LLM providers errored)"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"window":{"type":"string","enum":["4h","12h","1d","1w"],"example":"1d","description":"Time window label; becomes the prefix of the cache key."},"start":{"type":"string","example":"2026-04-01T00:00:00.000Z","description":"Window start, ISO 8601 (inclusive). Use the exact form YYYY-MM-DDTHH:MM:SS.000Z so the key matches `GET /api/digests`."},"end":{"type":"string","example":"2026-04-02T00:00:00.000Z","description":"Window end, ISO 8601 (exclusive)."}},"required":["window","start","end"]}}}},"x-llm":true}},"/api/digests":{"get":{"operationId":"digests","tags":["Digests"],"summary":"Read cached AI digests — no LLM call, returns pre-computed summaries","description":"Lists every digest stored for a source, optionally narrowed to one window. Entries are sorted by cache key descending, i.e. newest first within each window.\n\nThis endpoint only reads from cache — it never triggers an LLM call. Use `POST /api/x-digest` or `POST /api/bwe-digest` to generate new digests.\n\n⚠ There is no `limit` or `since` parameter: the response is the whole store for the selected window (over a thousand 4h digests, several MB). Always pass `window` and slice `digests[]` client-side for the newest N; they are sorted newest first.\n\n`window`, when given, is validated against the same four values as the digest POST routes and then matched as the key prefix `{window}_`.\n\n```bash\ncurl \"https://news.all-vista.org/api/digests?source=x&window=1d\"\n\ncurl \"https://news.all-vista.org/api/digests?source=bwe\"\n```","responses":{"200":{"description":"DigestList\n\n```json\n{\n \"source\": \"x\",\n \"window\": \"1d\", // \"all\" when the query had no window\n \"total\": 42,\n \"digests\": [\n {\n \"key\": \"1d_2026-04-01T00:00:00.000Z\", // \"{window}_{start}\"\n \"window\": \"1d\",\n \"start\": \"2026-04-01T00:00:00.000Z\",\n \"sentiment\": \"bearish\",\n \"title\": \"...\",\n \"title_en\": \"Tariff fears dominate as markets sell off\",\n \"summary\": \"...\",\n \"summary_en\": \"...\",\n \"key_themes\": [\"tariffs\", \"fed policy\"],\n \"notable_tickers\": [\"SPY\", \"QQQ\", \"NVDA\"]\n }\n ]\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"source":"x","window":"1d","total":42,"digests":[{"key":"1d_2026-04-01T00:00:00.000Z","window":"1d","start":"2026-04-01T00:00:00.000Z","sentiment":"bearish","title":"...","title_en":"Tariff fears dominate as markets sell off","summary":"...","summary_en":"...","key_themes":["tariffs","fed policy"],"notable_tickers":["SPY","QQQ","NVDA"]}]}}}},"400":{"description":"Missing or invalid `source` (must be `x` or `bwe`), or `window` given but not one of 4h, 12h, 1d, 1w (`window must be one of 4h, 12h, 1d, 1w`)"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"source","in":"query","required":true,"description":"Which digest store to read.","schema":{"type":"string","enum":["x","bwe"],"example":"x"}},{"name":"window","in":"query","required":false,"description":"Only digests whose key starts with this window; must be one of the four values when given, omit for all windows (`window: \"all\"` in the response).","schema":{"type":"string","enum":["4h","12h","1d","1w"],"example":"1d"}},{"name":"from","in":"query","required":false,"description":"ISO 8601 lower bound (inclusive) on the digest window start. The feed pages use from/to to fetch digests for older posts as they page in (since 2026-10-20).","schema":{"type":"string","example":"2026-10-01T00:00:00Z"}},{"name":"to","in":"query","required":false,"description":"ISO 8601 upper bound (exclusive) on the digest window start. Invalid from/to → 400.","schema":{"type":"string","example":"2026-10-08T00:00:00Z"}}]}},"/api/macro-analysis":{"get":{"operationId":"macroAnalysis","tags":["Macro"],"summary":"AI-generated daily macro market brief with live data","description":"Formats the latest macro snapshot (live Polygon overlay for equities/ETFs) into a prompt and asks the LLM for a ~350-word institutional-style macro brief. The result is cached in memory per snapshot id and locale, so repeat calls are instant until a new snapshot lands.\n\nResponse headers `X-AI-Provider` and `X-AI-Model` indicate which LLM generated the analysis. Cached replays report `X-AI-Provider: cache` / `X-AI-Model: cached`.\n\nReturns `text/plain` (~350 words). The prompt includes live S&P 500, Nasdaq, 10Y yield, oil, VIX, BTC, gold, and 20+ macro indicators; indicators without a reading are passed to the model as n/a.\n\nGeneration order: remote Claude (when enabled) first, then the API provider fallback chain (`ANTHROPIC_MODEL_MACRO`, Codex, Qwen). Up to 20 snapshot/locale pairs are kept in the in-memory cache.\n\nLLM-backed: counts against the `llm` rate limit and returns `X-AI-Provider` / `X-AI-Model` headers.\n\n```bash\ncurl \"https://news.all-vista.org/api/macro-analysis?locale=zh\"\n```","responses":{"200":{"description":"text/plain\n\n```json\nContent-Type: text/plain; charset=utf-8\nX-AI-Provider: anthropic // or \"cache\" when served from the in-memory cache\nX-AI-Model: claude-opus-4-6 // or \"cached\"\n\nGrowth is cooling but not collapsing: payrolls printed +142K against a 4.2% unemployment\nrate while real GDP held at 2.1% QoQ ... (~350 words, no title)\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"x-example-text":"Content-Type: text/plain; charset=utf-8\nX-AI-Provider: anthropic // or \"cache\" when served from the in-memory cache\nX-AI-Model: claude-opus-4-6 // or \"cached\"\n\nGrowth is cooling but not collapsing: payrolls printed +142K against a 4.2% unemployment\nrate while real GDP held at 2.1% QoQ ... (~350 words, no title)"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No snapshot data available (plain-text body) — macro.json has no valid snapshot yet"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"locale","in":"query","required":false,"description":"Language of the brief; any value other than zh falls back to en.","schema":{"type":"string","enum":["en","zh"],"default":"en"}}],"x-llm":true,"x-cache":"no-cache"}},"/api/macro-indicators":{"get":{"operationId":"macroIndicators","tags":["Macro"],"summary":"Raw macro indicator values across all eight factor groups — no LLM call","description":"Returns the latest macro snapshot as JSON. Each indicator is either a price item { close, change_pct } or an economic indicator { value, date }. Categories: market, growth, inflation, risk_appetite, liquidity, fiat_credit, ai_tech, global_markets.\n\nPure data endpoint — no LLM, no AI provider headers. Use `/api/macro-analysis` when you want a written brief.\n\n`live` and `history` are checked before the snapshot is read, so a bad flag value is a 400 even when no snapshot exists; the response echoes the effective `live` as a JSON boolean.\n\n`close` and `value` are `null` when a series has no reading yet (e.g. `mag7_avg` before the live overlay); render a dash rather than zero.\n\n```bash\ncurl \"https://news.all-vista.org/api/macro-indicators?category=inflation\"\n\ncurl \"https://news.all-vista.org/api/macro-indicators?keys=cpi,unemployment_rate,vix,btc\"\n\ncurl \"https://news.all-vista.org/api/macro-indicators?live=false&history=true\"\n```","responses":{"200":{"description":"MacroIndicators\n\n```json\n{\n \"snapshot_id\": \"macro_20260511_080005\",\n \"timestamp\": \"2026-05-11T08:00:05Z\",\n \"live\": true,\n \"indicators\": {\n \"market\": {\n \"sp500\": { \"close\": 7399.2, \"change_pct\": 0.81 },\n \"nasdaq\": { \"close\": 26247.1, \"change_pct\": 1.72 },\n \"treasury_10y\": { \"close\": 4.36, \"change_pct\": -0.45 },\n \"oil\": { \"close\": 99.1, \"change_pct\": 0.55 }\n },\n \"inflation\": {\n \"cpi\": { \"value\": 3.3, \"date\": \"2026-04-01\" },\n \"core_pce\": { \"value\": 3.2, \"date\": \"2026-03-01\" }\n }\n // ... growth, risk_appetite, liquidity, fiat_credit, ai_tech, global_markets\n },\n \"history\": { // only with history=true\n \"total_pc_ratio\": [ { \"date\": \"2026-01-02\", \"value\": 0.91 }, ... ],\n \"equity_pc_ratio\": [ ... ], \"us_debt_gdp\": [ ... ], \"fiscal_deficit_gdp\": [ ... ]\n }\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"snapshot_id":"macro_20260511_080005","timestamp":"2026-05-11T08:00:05Z","live":true,"indicators":{"market":{"sp500":{"close":7399.2,"change_pct":0.81},"nasdaq":{"close":26247.1,"change_pct":1.72},"treasury_10y":{"close":4.36,"change_pct":-0.45},"oil":{"close":99.1,"change_pct":0.55}},"inflation":{"cpi":{"value":3.3,"date":"2026-04-01"},"core_pce":{"value":3.2,"date":"2026-03-01"}}},"history":{"total_pc_ratio":[{"date":"2026-01-02","value":0.91}],"equity_pc_ratio":[],"us_debt_gdp":[],"fiscal_deficit_gdp":[]}}}}},"400":{"description":"`live` or `history` not one of true, false, 1, 0 (`live and history accept true|false|1|0`); invalid category (body lists valid_categories); or an empty keys parameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No snapshot data available"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"category","in":"query","required":false,"description":"Restrict to one factor group.","schema":{"type":"string","enum":["market","growth","inflation","risk_appetite","liquidity","fiat_credit","ai_tech","global_markets"]}},{"name":"keys","in":"query","required":false,"description":"Comma-separated indicator keys, e.g. cpi,unemployment_rate,vix; matches are returned grouped by their category (categories with no match are omitted).","schema":{"type":"string","description":"Comma-separated string values","example":"cpi,unemployment_rate,vix"}},{"name":"live","in":"query","required":false,"description":"Overlay equity/ETF prices with live Polygon.io quotes (indices, crypto and economic indicators stay from the snapshot). Accepts exactly true, false, 1 or 0; any other value is a 400.","schema":{"type":"string","enum":["true","false","1","0"],"default":"true"}},{"name":"history","in":"query","required":false,"description":"Append a history map (~120 daily points each) for indicators without a public ticker: total_pc_ratio, equity_pc_ratio, us_debt_gdp, fiscal_deficit_gdp. Accepts exactly true, false, 1 or 0; any other value is a 400.","schema":{"type":"string","enum":["true","false","1","0"],"default":"false"}}],"x-cache":"no-cache"}},"/api/events":{"get":{"operationId":"events","tags":["Macro"],"summary":"Merged economic-events calendar: US/CN/HK macro releases, central-bank decisions, mega-cap US and HK earnings","description":"Builds a day-bucketed calendar from today (UTC) through today plus days (inclusive). Macro and central-bank releases come from events.json (Unusual Whales for the US, TuShare for CN/HK/GLOBAL), HK results dates from hk_earnings.json, and US earnings from the Finnhub calendar file restricted to revenue estimates of at least $10B. US earnings are tagged with the options-implied move.\n\n`importance` is `high` for every earnings and central-bank row; macro releases are `high` only when the title matches a market-moving keyword list (CPI, PPI, PCE, GDP, PMI, ISM, payrolls, FOMC, retail sales, jobless claims, LPR/MLF, ...) and `normal` otherwise.\n\n`meta.impliedMovePct` (percent, one decimal) is added to at most the first 40 US earnings rows from the Unusual Whales IV term structure (first expiry on/after the report date, cached 12 h); it is absent when no usable term structure exists. `meta.hkCode` is present only for US tickers that are also listed in Hong Kong.\n\nThe response is memoised in memory for 10 minutes per `days` value. Missing source files are not an error — the affected rows are simply absent and `fetched_at` / `hk_checked_at` are `null`.\n\n```bash\ncurl \"https://news.all-vista.org/api/events\"\n\ncurl \"https://news.all-vista.org/api/events?days=7\"\n```","responses":{"200":{"description":"CalendarPayload\n\n```json\n{\n \"fetched_at\": \"2026-09-07T05:05:12+00:00\", // events.json fetch time; null when the file is missing\n \"hk_checked_at\": \"2026-09-06T02:10:00+00:00\", // hk_earnings.json check time; null when missing\n \"days\": [\n {\n \"date\": \"2026-09-10\",\n \"events\": [ // sorted by time_utc, untimed events last\n {\n \"id\": \"3f9c1a2b7d4e\", // sha1(source|date|title)[:12] for macro rows\n \"date\": \"2026-09-10\",\n \"time_utc\": \"12:30\", \"time_et\": \"08:30\", \"time_hkt\": \"20:30\", // null when the release has no time\n \"region\": \"US\", // US | CN | HK | GLOBAL\n \"type\": \"macro\", // macro | central_bank | earnings\n \"importance\": \"high\", // high | normal\n \"title_zh\": \"美国CPI同比\", \"title_en\": \"CPI YoY\",\n \"prev\": \"2.9%\", \"forecast\": \"3.0%\", // as published (strings); null when unknown\n \"source\": \"uw\", // uw | tushare | hk_list | finnhub\n \"meta\": {}\n },\n {\n \"id\": \"us-BABA-2026-09-10\", \"date\": \"2026-09-10\",\n \"time_utc\": null, \"time_et\": null, \"time_hkt\": null,\n \"region\": \"US\", \"type\": \"earnings\", \"importance\": \"high\",\n \"title_zh\": \"BABA 财报\", \"title_en\": \"BABA earnings\",\n \"prev\": null, \"forecast\": null, \"source\": \"finnhub\",\n \"meta\": { \"symbol\": \"BABA\", \"hour\": \"bmo\", \"hkCode\": \"09988.HK\", \"impliedMovePct\": 6.8 }\n },\n {\n \"id\": \"hk-00700-2026-09-10\", \"date\": \"2026-09-10\",\n \"time_utc\": null, \"time_et\": null, \"time_hkt\": null,\n \"region\": \"HK\", \"type\": \"earnings\", \"importance\": \"high\",\n \"title_zh\": \"腾讯控股 业绩\", \"title_en\": \"Tencent results\",\n \"prev\": null, \"forecast\": null, \"source\": \"hk_list\",\n \"meta\": { \"symbol\": \"00700\", \"confirmed\": true }\n }\n ]\n }\n ]\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"fetched_at":"2026-09-07T05:05:12+00:00","hk_checked_at":"2026-09-06T02:10:00+00:00","days":[{"date":"2026-09-10","events":[{"id":"3f9c1a2b7d4e","date":"2026-09-10","time_utc":"12:30","time_et":"08:30","time_hkt":"20:30","region":"US","type":"macro","importance":"high","title_zh":"美国CPI同比","title_en":"CPI YoY","prev":"2.9%","forecast":"3.0%","source":"uw","meta":{}},{"id":"us-BABA-2026-09-10","date":"2026-09-10","time_utc":null,"time_et":null,"time_hkt":null,"region":"US","type":"earnings","importance":"high","title_zh":"BABA 财报","title_en":"BABA earnings","prev":null,"forecast":null,"source":"finnhub","meta":{"symbol":"BABA","hour":"bmo","hkCode":"09988.HK","impliedMovePct":6.8}},{"id":"hk-00700-2026-09-10","date":"2026-09-10","time_utc":null,"time_et":null,"time_hkt":null,"region":"HK","type":"earnings","importance":"high","title_zh":"腾讯控股 业绩","title_en":"Tencent results","prev":null,"forecast":null,"source":"hk_list","meta":{"symbol":"00700","confirmed":true}}]}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"days","in":"query","required":false,"description":"Number of days ahead to include (window is today through today+days, inclusive); non-numeric values fall back to 14.","schema":{"type":"integer","default":14,"minimum":1,"maximum":30}}]}},"/api/earnings":{"get":{"operationId":"earnings","tags":["Earnings"],"summary":"US-equity earnings calendar (stored window: ~7 days back to ~30 days ahead, refreshed daily 05:15 UTC)","description":"Filters the Finnhub earnings calendar file. Without an explicit date or from the response is forward-looking from today (ET); past results with surprises and price reactions live at /api/earnings/results.\n\n`hour` values: `bmo` = before market open, `amc` = after market close, `dmh` = during market hours, empty string = unannounced. `*Actual` fields are `null` until the company reports.\n\n`filters.from` echoes the effective lower bound, i.e. today (ET) when it was defaulted; `filters.tier` echoes the lower-cased tier. Items keep the file order (by date); within a day they are not re-sorted.\n\n`tier` is lower-cased before the check, so MEGA works, but anything outside all / big / mega is a 400 (`valid_tiers` in the body) rather than being treated as all.\n\n```bash\ncurl \"https://news.all-vista.org/api/earnings?symbol=AAPL,MSFT,GOOGL,META,AMZN,NVDA,TSLA&from=2026-04-27&to=2026-05-11\"\n\ncurl \"https://news.all-vista.org/api/earnings?tier=mega&group_by=date\"\n\ncurl \"https://news.all-vista.org/api/earnings?date=2026-04-29&hour=amc\"\n```","responses":{"200":{"description":"EarningsCalendar\n\n```json\n{\n \"source\": \"finnhub\",\n \"fetched_at\": \"2026-04-27T05:15:08Z\",\n \"from_date\": \"2026-04-20\", // stored window (file), not the filtered range\n \"to_date\": \"2026-05-27\",\n \"total\": 7, // matches before limit\n \"returned\": 7,\n \"filters\": { \"tier\": \"mega\", \"date\": null, \"from\": \"2026-04-27\", \"to\": null, \"symbol\": null, \"hour\": null },\n \"items\": [\n {\n \"date\": \"2026-04-29\",\n \"symbol\": \"AMZN\",\n \"hour\": \"amc\",\n \"quarter\": 1,\n \"year\": 2026,\n \"epsActual\": null,\n \"epsEstimate\": 1.667,\n \"revenueActual\": null,\n \"revenueEstimate\": 180846456490\n }\n ]\n // with group_by=date: \"days\": [ { \"date\": \"2026-04-29\", \"count\": 3, \"entries\": [ ... ] } ] replaces \"items\"\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"source":"finnhub","fetched_at":"2026-04-27T05:15:08Z","from_date":"2026-04-20","to_date":"2026-05-27","total":7,"returned":7,"filters":{"tier":"mega","date":null,"from":"2026-04-27","to":null,"symbol":null,"hour":null},"items":[{"date":"2026-04-29","symbol":"AMZN","hour":"amc","quarter":1,"year":2026,"epsActual":null,"epsEstimate":1.667,"revenueActual":null,"revenueEstimate":180846456490}]}}}},"400":{"description":"Unknown `tier` — body is { \"error\": \"invalid tier\", \"valid_tiers\": [\"all\", \"big\", \"mega\"] }"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"tier","in":"query","required":false,"description":"Revenue-estimate filter: big = at least $100M, mega = at least $10B; case-insensitive, any other value is rejected with 400.","schema":{"type":"string","enum":["all","big","mega"],"default":"all"}},{"name":"date","in":"query","required":false,"description":"Exact-day filter (YYYY-MM-DD); when set, from no longer defaults to today.","schema":{"type":"string","example":"2026-04-29"}},{"name":"from","in":"query","required":false,"description":"Inclusive lower bound (YYYY-MM-DD). When neither date nor from is given the response starts at today (ET); pass from explicitly to reach the past week.","schema":{"type":"string","default":"today (ET)"}},{"name":"to","in":"query","required":false,"description":"Inclusive upper bound (YYYY-MM-DD).","schema":{"type":"string","example":"2026-05-11"}},{"name":"symbol","in":"query","required":false,"description":"One or more comma-separated tickers (case-insensitive), e.g. AAPL,MSFT.","schema":{"type":"string","description":"Comma-separated string values","example":"AAPL,MSFT"}},{"name":"hour","in":"query","required":false,"description":"Reporting time, exact match on the stored value: bmo = before market open, amc = after market close, dmh = during market hours.","schema":{"type":"string","enum":["bmo","amc","dmh"]}},{"name":"limit","in":"query","required":false,"description":"Cap on returned items (total still reports the unfiltered count).","schema":{"type":"integer","default":5000,"maximum":10000}},{"name":"group_by","in":"query","required":false,"description":"Set to date to receive days[] (each { date, count, entries[] }, ascending by date) instead of a flat items[].","schema":{"type":"string","enum":["date"]}}]}},"/api/earnings/results":{"get":{"operationId":"earningsResults","tags":["Earnings"],"summary":"Recent reports (revenue est ≥ $1B): EPS / revenue surprise and price reaction","description":"Companies with a revenue estimate of at least $1B that reported in the last days ET calendar days (inclusive of today), with surprise percentages, a beat/miss/mixed verdict and the close-to-close move of the session that priced the report.\n\nSorted by date desc, then revenue estimate desc, then symbol. `reactionPct` is `null` while the pricing session is still open (sessions count as closed at 16:15 ET) or when a bar is missing.\n\n`verdict` is `beat` when every available surprise is ≥ 0, `miss` when every one is < 0, `mixed` when EPS and revenue disagree in sign. Results are memoised for 5 minutes on the source file's mtime.\n\n```bash\ncurl \"https://news.all-vista.org/api/earnings/results?days=14\"\n```","responses":{"200":{"description":"ResultsPayload\n\n```json\n{\n \"generated_at\": \"2026-09-02T12:00:03Z\",\n \"from\": \"2026-08-26\", \"to\": \"2026-09-02\", \"days\": 7,\n \"source_fetched_at\": \"2026-09-02T05:15:08Z\",\n \"summary\": { \"reported\": 38, \"beats\": 27, \"mixed\": 2, \"misses\": 9, \"withReaction\": 35, \"avgReactionPct\": 1.12 },\n \"items\": [\n {\n \"date\": \"2026-08-27\", \"symbol\": \"NVDA\", \"hour\": \"amc\", \"quarter\": 2, \"year\": 2027,\n \"epsActual\": 1.05, \"epsEstimate\": 1.01, \"revenueActual\": 46743000000, \"revenueEstimate\": 46020000000,\n \"epsSurprisePct\": 3.96, \"revenueSurprisePct\": 1.57,\n \"verdict\": \"beat\", // beat | miss | mixed | null (no surprise computable)\n \"beat\": true, // compatibility flag: true = beat, false = miss or mixed, null = no verdict\n \"reactionPct\": -0.82, // close-to-close move of the session that priced the report\n \"reactionBasis\": \"amc\", // amc → next session (also used for dmh / unknown); bmo → same session\n \"reactionSession\": \"2026-08-28\"\n }\n ]\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"generated_at":"2026-09-02T12:00:03Z","from":"2026-08-26","to":"2026-09-02","days":7,"source_fetched_at":"2026-09-02T05:15:08Z","summary":{"reported":38,"beats":27,"mixed":2,"misses":9,"withReaction":35,"avgReactionPct":1.12},"items":[{"date":"2026-08-27","symbol":"NVDA","hour":"amc","quarter":2,"year":2027,"epsActual":1.05,"epsEstimate":1.01,"revenueActual":46743000000,"revenueEstimate":46020000000,"epsSurprisePct":3.96,"revenueSurprisePct":1.57,"verdict":"beat","beat":true,"reactionPct":-0.82,"reactionBasis":"amc","reactionSession":"2026-08-28"}]}}}},"400":{"description":"days must be an integer between 1 and 30"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"failed to build earnings results"}},"parameters":[{"name":"days","in":"query","required":false,"description":"Look-back window in ET calendar days; must be an integer within range (out-of-range or non-integer values are rejected, not clamped).","schema":{"type":"integer","default":7,"minimum":1,"maximum":30}}]}},"/api/earnings-vol":{"get":{"operationId":"earningsVol","tags":["Earnings"],"summary":"Realised vs options-implied move for a symbol's last eight earnings reports","description":"Per-symbol record of how the stock actually moved across each of its recent reports versus what the ATM straddle implied the day before. Either ticker or top=1 is required.\n\nBuilt on the AWS market database from daily stock and option bars (`earnings_vol.json`, ~1.1k symbols: market cap ≥ $10B plus anything reporting within ±30 days). `503` while the file is missing; `record: null` for an uncovered symbol. Powers the card on `/stocks` and the calendar detail pane.\n\n`hour` can also be `dmh` (during market hours) or empty; both use the AMC rule for the realised move. `events` are oldest first, at most 8.\n\n```bash\ncurl \"https://news.all-vista.org/api/earnings-vol?ticker=NVDA\"\n\ncurl \"https://news.all-vista.org/api/earnings-vol?top=1&limit=10\"\n```","responses":{"200":{"description":"EarningsVolResponse (ticker=NVDA)\n\n```json\n{\n \"symbol\": \"NVDA\",\n \"generated_at\": \"2026-09-02T18:15:00+00:00\",\n \"as_of\": \"2026-09-01\",\n \"record\": {\n \"n\": 8, \"n_implied\": 8,\n \"avg_abs_realised\": 6.1, // % close-to-close across the report (BMO: day vs prior; AMC: next vs day)\n \"avg_implied\": 7.4, // % ATM straddle / spot at T-1, nearest expiry after the report\n \"ratio\": 0.82, // realised ÷ implied\n \"hit_rate\": 0.25, // share of reports where |realised| > implied\n \"next\": { \"date\": \"2026-11-19\", \"hour\": \"amc\" } | null,\n \"events\": [ { \"date\": \"2026-08-27\", \"hour\": \"amc\", \"period\": \"Q2 FY27\", \"session\": \"2026-08-28\", \"spot\": 181.2, \"realised_pct\": -3.4, \"implied_pct\": 6.8, \"expiry\": \"2026-08-29\" }, ... ]\n } | null\n}\n\n// top=1\n{\n \"generated_at\": \"...\", \"as_of\": \"2026-09-01\",\n \"coverage\": { \"symbols\": 1120, \"symbols_with_implied\": 980, \"events\": 8400, \"events_with_realised\": 8100, \"events_with_implied\": 6900 },\n \"items\": [ { \"symbol\": \"SMCI\", \"avg_abs_realised\": 14.2, \"avg_implied\": 9.1, \"gap\": 5.1, \"ratio\": 1.56, \"hit_rate\": 0.75, \"n_implied\": 8, \"next\": { ... } | null }, ... ] // sorted by |gap| desc\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"x-example-text":"{\n \"symbol\": \"NVDA\",\n \"generated_at\": \"2026-09-02T18:15:00+00:00\",\n \"as_of\": \"2026-09-01\",\n \"record\": {\n \"n\": 8, \"n_implied\": 8,\n \"avg_abs_realised\": 6.1, // % close-to-close across the report (BMO: day vs prior; AMC: next vs day)\n \"avg_implied\": 7.4, // % ATM straddle / spot at T-1, nearest expiry after the report\n \"ratio\": 0.82, // realised ÷ implied\n \"hit_rate\": 0.25, // share of reports where |realised| > implied\n \"next\": { \"date\": \"2026-11-19\", \"hour\": \"amc\" } | null,\n \"events\": [ { \"date\": \"2026-08-27\", \"hour\": \"amc\", \"period\": \"Q2 FY27\", \"session\": \"2026-08-28\", \"spot\": 181.2, \"realised_pct\": -3.4, \"implied_pct\": 6.8, \"expiry\": \"2026-08-29\" }, ... ]\n } | null\n}\n\n// top=1\n{\n \"generated_at\": \"...\", \"as_of\": \"2026-09-01\",\n \"coverage\": { \"symbols\": 1120, \"symbols_with_implied\": 980, \"events\": 8400, \"events_with_realised\": 8100, \"events_with_implied\": 6900 },\n \"items\": [ { \"symbol\": \"SMCI\", \"avg_abs_realised\": 14.2, \"avg_implied\": 9.1, \"gap\": 5.1, \"ratio\": 1.56, \"hit_rate\": 0.75, \"n_implied\": 8, \"next\": { ... } | null }, ... ] // sorted by |gap| desc\n}"}}},"400":{"description":"ticker missing or not matching ^[A-Z][A-Z0-9.-]{0,9}$ (only when top is not 1)"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"earnings vol unavailable (unexpected read error)"},"503":{"description":"earnings vol data unavailable — earnings_vol.json has not been pulled yet"}},"parameters":[{"name":"ticker","in":"query","required":false,"description":"Symbol (case-insensitive, a leading $ is stripped) that must match ^[A-Z][A-Z0-9.-]{0,9}$ after normalisation → { symbol, generated_at, as_of, record | null }.","schema":{"type":"string","example":"NVDA"}},{"name":"top","in":"query","required":false,"description":"Set to 1 to instead list the symbols with the largest |avg realised − avg implied| gap (needs at least 4 paired events) → { generated_at, as_of, coverage, items[] }; takes precedence over ticker.","schema":{"type":"string","enum":["1"]}},{"name":"limit","in":"query","required":false,"description":"Row cap for the top=1 board; non-numeric values fall back to the default.","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}}]}},"/api/brief":{"get":{"operationId":"brief","tags":["Daily Brief"],"summary":"The aggregated Daily Brief behind /brief — markets, calendar, AI digests, smart money, Trump","description":"Read-only aggregation of caches the site already maintains (macro snapshot, today's calendar, latest X and BWE digests, flow recap, Trump impact). No query parameters; the brief is memoised server-side for 60 s and shared across concurrent callers.\n\nRead-only aggregation of existing caches — no LLM call. Each section is `null` when its source is unavailable, so consumers should treat every block as optional (`trump` is always present, possibly with empty `items`). `scripts/push_brief.py` posts this payload to a webhook at 07:30 ET.\n\n```bash\ncurl \"https://news.all-vista.org/api/brief\"\n```","responses":{"200":{"description":"Brief\n\n```json\n{\n \"generated_at\": \"2026-09-02T11:30:00.000Z\",\n \"date_et\": \"2026-09-02\",\n \"glance\": { \"zh\": \"...\", \"en\": \"...\" } | null, // one-line header\n \"markets\": { \"source_updated_at\": \"...\", \"headline\": [ { \"key\": \"sp500\", \"label\": \"S&P 500\", \"close\": 6512.3, \"change_pct\": -0.42 } ], \"movers\": [ ... ] } | null,\n \"calendar\": { \"date\": \"2026-09-02\", \"items\": [ ... ] } | null, // high-importance events + mega-cap earnings today\n \"x_digest\": { \"window\": \"1d\", \"sentiment\": \"bearish\", \"title_en\": \"...\", \"summary_en\": \"...\", \"key_themes\": [...], \"notable_tickers\": [...] } | null,\n \"bwe_digest\": { ... } | null,\n \"flow_recap\": { \"date\": \"2026-09-01\", \"title_en\": \"...\", \"summary_en\": \"...\", \"key_tickers\": [\"NVDA\", \"TSLA\"] } | null,\n \"trump\": { \"since\": \"2026-09-01T11:30:00.000Z\", \"total_posts\": 14, \"analyzed_posts\": 11, \"items\": [ { \"id\": \"...\", \"headline_en\": \"...\", \"impact_direction\": \"bearish\", \"impact_magnitude\": 2, \"suggested_symbols\": [\"SPY\"] } ] }\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"x-example-text":"{\n \"generated_at\": \"2026-09-02T11:30:00.000Z\",\n \"date_et\": \"2026-09-02\",\n \"glance\": { \"zh\": \"...\", \"en\": \"...\" } | null, // one-line header\n \"markets\": { \"source_updated_at\": \"...\", \"headline\": [ { \"key\": \"sp500\", \"label\": \"S&P 500\", \"close\": 6512.3, \"change_pct\": -0.42 } ], \"movers\": [ ... ] } | null,\n \"calendar\": { \"date\": \"2026-09-02\", \"items\": [ ... ] } | null, // high-importance events + mega-cap earnings today\n \"x_digest\": { \"window\": \"1d\", \"sentiment\": \"bearish\", \"title_en\": \"...\", \"summary_en\": \"...\", \"key_themes\": [...], \"notable_tickers\": [...] } | null,\n \"bwe_digest\": { ... } | null,\n \"flow_recap\": { \"date\": \"2026-09-01\", \"title_en\": \"...\", \"summary_en\": \"...\", \"key_tickers\": [\"NVDA\", \"TSLA\"] } | null,\n \"trump\": { \"since\": \"2026-09-01T11:30:00.000Z\", \"total_posts\": 14, \"analyzed_posts\": 11, \"items\": [ { \"id\": \"...\", \"headline_en\": \"...\", \"impact_direction\": \"bearish\", \"impact_magnitude\": 2, \"suggested_symbols\": [\"SPY\"] } ] }\n}"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Brief unavailable"}},"x-cache":"no-store"}},"/api/china/market":{"get":{"operationId":"chinaMarket","tags":["China"],"summary":"A-share indices, industry performance, market breadth, top movers and Stock Connect turnover","description":"Both payloads are pre-computed files (china_market.json from the AWS job, hsgt.json from the Finland TuShare fetch); nothing is queried per request. No query parameters.\n\nPrices in CNY. Northbound figures are gross turnover — HKEX stopped publishing daily net buying in Aug 2024. `503` only while neither file exists yet; when just one is missing its block is `null` and the response is still `200`.\n\n```bash\ncurl \"https://news.all-vista.org/api/china/market\"\n```","responses":{"200":{"description":"ChinaMarketBundle\n\n```json\n{\n \"market\": {\n \"session_date\": \"2026-09-01\",\n \"indices\": [ { \"code\": \"000001.SH\", \"name_en\": \"SSE Composite\", \"close\": 3851.2, \"pct\": 0.42, \"amount_bn\": 944.1, \"spark\": [ ... 60 ] } ],\n \"industries\": [ { \"industry\": \"半导体\", \"name_en\": \"Semiconductors\", \"count\": 162, \"med_pct\": 1.8, \"adv\": 120, \"dec\": 40, \"amount_bn\": 210.3, \"top\": { ... } } ],\n \"breadth\": { \"total\": 5312, \"advancers\": 3105, \"decliners\": 1980, \"limit_up\": 61, \"limit_down\": 7, \"st_count\": 168, \"turnover_bn\": 2054.0, \"buckets\": [ ... ], \"by_board\": [ ... ] } | null,\n \"movers\": { \"by_amount\": [ ... ], \"gainers\": [ ... ], \"losers\": [ ... ] },\n \"generated_at\": \"2026-09-02T13:49:00+00:00\"\n } | null,\n \"hsgt\": {\n \"session_date\": \"2026-09-01\",\n \"flows\": [ { \"date\": \"2026-09-01\", \"north\": 1350.2, \"hgt\": 640.1, \"sgt\": 710.1, \"south\": 480.3 } ], // CNY 100m, 60 sessions\n \"top10\": { \"sh\": [ { \"symbol\": \"600519.SH\", \"name\": \"贵州茅台\", \"close\": 1480.0, \"pct\": 0.9, \"amount_m\": 2130.5 } ], \"sz\": [ ... ] },\n \"generated_at\": \"...\"\n } | null,\n \"ages\": { \"market_hours\": 4.5, \"hsgt_hours\": 4.6 } // hours since each file's generated_at; null when that file is missing\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"x-example-text":"{\n \"market\": {\n \"session_date\": \"2026-09-01\",\n \"indices\": [ { \"code\": \"000001.SH\", \"name_en\": \"SSE Composite\", \"close\": 3851.2, \"pct\": 0.42, \"amount_bn\": 944.1, \"spark\": [ ... 60 ] } ],\n \"industries\": [ { \"industry\": \"半导体\", \"name_en\": \"Semiconductors\", \"count\": 162, \"med_pct\": 1.8, \"adv\": 120, \"dec\": 40, \"amount_bn\": 210.3, \"top\": { ... } } ],\n \"breadth\": { \"total\": 5312, \"advancers\": 3105, \"decliners\": 1980, \"limit_up\": 61, \"limit_down\": 7, \"st_count\": 168, \"turnover_bn\": 2054.0, \"buckets\": [ ... ], \"by_board\": [ ... ] } | null,\n \"movers\": { \"by_amount\": [ ... ], \"gainers\": [ ... ], \"losers\": [ ... ] },\n \"generated_at\": \"2026-09-02T13:49:00+00:00\"\n } | null,\n \"hsgt\": {\n \"session_date\": \"2026-09-01\",\n \"flows\": [ { \"date\": \"2026-09-01\", \"north\": 1350.2, \"hgt\": 640.1, \"sgt\": 710.1, \"south\": 480.3 } ], // CNY 100m, 60 sessions\n \"top10\": { \"sh\": [ { \"symbol\": \"600519.SH\", \"name\": \"贵州茅台\", \"close\": 1480.0, \"pct\": 0.9, \"amount_m\": 2130.5 } ], \"sz\": [ ... ] },\n \"generated_at\": \"...\"\n } | null,\n \"ages\": { \"market_hours\": 4.5, \"hsgt_hours\": 4.6 } // hours since each file's generated_at; null when that file is missing\n}"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Failed to read China market data"},"503":{"description":"China market data not available yet — neither china_market.json nor hsgt.json exists (body also carries the empty bundle)"}},"x-cache":"public, max-age=300, stale-while-revalidate=600"}},"/api/china/ah":{"get":{"operationId":"chinaAh","tags":["China"],"summary":"A/H premium for ~40 dual listings and ADR/H premium for ~15 US-listed Chinese names","description":"Joins the two AWS job files (A + H closes, ADR closes + FRED DEXCHUS) into one snapshot with an equal-weight premium index, sector medians and per-pair rows. Memoised until one of the files changes on disk. No query parameters.\n\nPremium = A price in HKD ÷ H price − 1 (CNY→HKD via FRED DEXCHUS and the 7.80 peg); ADR premium uses the ADS ratio. Joined from the CN/HK and US job files (`ah_pairs_cnhk.json`, `ah_pairs_us.json`); `available: false` with a `reason` (`no_cnhk`, `no_us`, `no_fx`, `no_sessions`) until both exist.\n\nMissing data never yields a non-200 status — check `available` and `stale` instead. `fx` and `index` are `null` in the unavailable case; `sectors`, `pairs` and `adr` are empty arrays.\n\n```bash\ncurl \"https://news.all-vista.org/api/china/ah\"\n```","responses":{"200":{"description":"AhSnapshot\n\n```json\n{\n \"available\": true, // false (with \"reason\") until both job files and an FX rate exist\n \"generated_at\": \"2026-09-02T13:57:00+00:00\",\n \"stale\": false, // true when either source file is older than 72 h\n \"as_of\": \"2026-09-01\",\n \"fx\": { \"cny_per_usd\": 7.12, \"cny_per_hkd\": 0.913, \"hkd_per_usd\": 7.80, \"date\": \"2026-08-29\" },\n \"index\": { \"latest\": 41.9, \"date\": \"2026-09-01\", \"chg1d\": -0.3, \"chg20d\": 1.8, \"min\": 35.1, \"max\": 47.8, \"median\": 40.2, \"pairs_used\": 38,\n \"series\": [ { \"d\": \"2026-03-10\", \"v\": 38.2 }, ... 120 ] }, // equal-weight A/H premium, %\n \"sectors\": [ { \"sector\": \"Banks\", \"count\": 9, \"median\": 27.4 } ],\n \"pairs\": [ { \"a\": \"601398.SH\", \"h\": \"01398.HK\", \"name_en\": \"ICBC\", \"sector\": \"Banks\", \"date\": \"2026-09-01\", \"a_cny\": 7.21, \"h_hkd\": 5.90, \"a_hkd\": 7.89, \"premium\": 33.8, \"chg1d\": ..., \"chg20d\": ..., \"spark\": [ ... ] } ],\n \"adr\": [ { \"adr\": \"BABA\", \"h\": \"09988.HK\", \"ratio\": 8, \"adr_usd\": 132.1, \"h_hkd\": 128.9, \"adr_hkd\": 128.8, \"premium\": -0.34, ... } ],\n \"adr_skipped\": [ { \"adr\": \"...\", \"h\": \"...\", \"reason\": \"ratio_unverified\" } ], // ratio_unverified | no_adr_bars | no_h_bars | no_overlap\n \"dropped\": []\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"x-example-text":"{\n \"available\": true, // false (with \"reason\") until both job files and an FX rate exist\n \"generated_at\": \"2026-09-02T13:57:00+00:00\",\n \"stale\": false, // true when either source file is older than 72 h\n \"as_of\": \"2026-09-01\",\n \"fx\": { \"cny_per_usd\": 7.12, \"cny_per_hkd\": 0.913, \"hkd_per_usd\": 7.80, \"date\": \"2026-08-29\" },\n \"index\": { \"latest\": 41.9, \"date\": \"2026-09-01\", \"chg1d\": -0.3, \"chg20d\": 1.8, \"min\": 35.1, \"max\": 47.8, \"median\": 40.2, \"pairs_used\": 38,\n \"series\": [ { \"d\": \"2026-03-10\", \"v\": 38.2 }, ... 120 ] }, // equal-weight A/H premium, %\n \"sectors\": [ { \"sector\": \"Banks\", \"count\": 9, \"median\": 27.4 } ],\n \"pairs\": [ { \"a\": \"601398.SH\", \"h\": \"01398.HK\", \"name_en\": \"ICBC\", \"sector\": \"Banks\", \"date\": \"2026-09-01\", \"a_cny\": 7.21, \"h_hkd\": 5.90, \"a_hkd\": 7.89, \"premium\": 33.8, \"chg1d\": ..., \"chg20d\": ..., \"spark\": [ ... ] } ],\n \"adr\": [ { \"adr\": \"BABA\", \"h\": \"09988.HK\", \"ratio\": 8, \"adr_usd\": 132.1, \"h_hkd\": 128.9, \"adr_hkd\": 128.8, \"premium\": -0.34, ... } ],\n \"adr_skipped\": [ { \"adr\": \"...\", \"h\": \"...\", \"reason\": \"ratio_unverified\" } ], // ratio_unverified | no_adr_bars | no_h_bars | no_overlap\n \"dropped\": []\n}"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"A/H premium unavailable (unexpected read error)"}}}},"/api/china/pro":{"get":{"operationId":"chinaPro","tags":["China"],"summary":"Public-fund heavy holdings (latest two report periods) and convertible bonds","description":"Serves cn_pro.json produced by the AWS CN/HK job. Both sections are returned by default; section restricts the payload to one of them.\n\nMoney in 亿元 (CNY 100m), shares in 万股; premiums and returns are fractions. `503` while `cn_pro.json` has not been produced; `400` for an unknown `section`.\n\n```bash\ncurl \"https://news.all-vista.org/api/china/pro\"\n\ncurl \"https://news.all-vista.org/api/china/pro?section=cbs\"\n```","responses":{"200":{"description":"CnProResponse\n\n```json\n{\n \"generated_at\": \"2026-09-02T14:07:00+00:00\",\n \"age_hours\": 4.2,\n \"dates\": { \"trade_date\": \"2026-09-01\", \"fund_period\": \"2026-06-30\", \"fund_prev_period\": \"2026-03-31\" },\n \"funds\": { // omitted when section=cbs\n \"period\": \"2026-06-30\", \"prev_period\": \"2026-03-31\",\n \"universes\": { \"all\": { \"top\": [ { \"code\": \"600519.SH\", \"name\": \"贵州茅台\", \"industry\": \"白酒\", \"funds\": 1412, \"mkv\": 1580.2, \"d_funds\": -38, \"d_mkv\": -92.1 } ], \"increases\": [ ... ], \"decreases\": [ ... ], \"n_funds\": 8123, \"total_mkv\": 27110.5 }, \"active\": { ... } },\n \"top_funds\": [ { \"code\": \"005827.OF\", \"name\": \"...\", \"top10_mkv\": 210.4, \"ret_1m\": 3.1, \"ret_3m\": 9.8 } ]\n },\n \"cbs\": { // omitted when section=funds\n \"session_date\": \"2026-09-01\",\n \"rows\": [ { \"code\": \"113050.SH\", \"name\": \"南银转债\", \"stk_code\": \"601009.SH\", \"close\": 121.3, \"pct_chg\": 0.4, \"conv_price\": 8.02, \"stk_close\": 9.10, \"premium\": 6.9, \"ytm\": -1.2, \"call\": { \"type\": \"公告提示强赎\", \"call_date\": \"2026-09-20\" } | null, ... } ],\n ...\n }\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"x-example-text":"{\n \"generated_at\": \"2026-09-02T14:07:00+00:00\",\n \"age_hours\": 4.2,\n \"dates\": { \"trade_date\": \"2026-09-01\", \"fund_period\": \"2026-06-30\", \"fund_prev_period\": \"2026-03-31\" },\n \"funds\": { // omitted when section=cbs\n \"period\": \"2026-06-30\", \"prev_period\": \"2026-03-31\",\n \"universes\": { \"all\": { \"top\": [ { \"code\": \"600519.SH\", \"name\": \"贵州茅台\", \"industry\": \"白酒\", \"funds\": 1412, \"mkv\": 1580.2, \"d_funds\": -38, \"d_mkv\": -92.1 } ], \"increases\": [ ... ], \"decreases\": [ ... ], \"n_funds\": 8123, \"total_mkv\": 27110.5 }, \"active\": { ... } },\n \"top_funds\": [ { \"code\": \"005827.OF\", \"name\": \"...\", \"top10_mkv\": 210.4, \"ret_1m\": 3.1, \"ret_3m\": 9.8 } ]\n },\n \"cbs\": { // omitted when section=funds\n \"session_date\": \"2026-09-01\",\n \"rows\": [ { \"code\": \"113050.SH\", \"name\": \"南银转债\", \"stk_code\": \"601009.SH\", \"close\": 121.3, \"pct_chg\": 0.4, \"conv_price\": 8.02, \"stk_close\": 9.10, \"premium\": 6.9, \"ytm\": -1.2, \"call\": { \"type\": \"公告提示强赎\", \"call_date\": \"2026-09-20\" } | null, ... } ],\n ...\n }\n}"}}},"400":{"description":"section must be 'funds' or 'cbs'"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"cn_pro unavailable (unexpected read error)"},"503":{"description":"cn_pro data not available yet — the AWS job has not produced cn_pro.json"}},"parameters":[{"name":"section","in":"query","required":false,"description":"Return one section only; an empty value is treated as no filter.","schema":{"type":"string","enum":["funds","cbs"]}}]}},"/api/stock-search":{"get":{"operationId":"stockSearch","tags":["Stocks"],"summary":"Search US stocks & ETFs by ticker or name","description":"Matches the query against the ticker universe: exact ticker first, then ticker prefixes, then company names containing the query. Within each tier larger market caps come first.\n\nA missing or empty `q` returns `200` with `results: []` rather than an error.\n\n```bash\ncurl \"https://news.all-vista.org/api/stock-search?q=nvidia&limit=5\"\n```","responses":{"200":{"description":"SearchResults\n\n```json\n{\n \"results\": [\n {\n \"ticker\": \"NVDA\",\n \"name\": \"NVIDIA Corp\",\n \"market_cap\": 2800000000000, // null when unknown\n \"primary_exchange\": \"XNAS\",\n \"type\": \"CS\", // CS, ETF, ...\n \"sic_description\": \"Semiconductors\",\n \"market_cap_tier\": \"mega\"\n }\n ]\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"results":[{"ticker":"NVDA","name":"NVIDIA Corp","market_cap":2800000000000,"primary_exchange":"XNAS","type":"CS","sic_description":"Semiconductors","market_cap_tier":"mega"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"q","in":"query","required":true,"description":"Search query (min 1 character); case-insensitive.","schema":{"type":"string","example":"nvidia"}},{"name":"limit","in":"query","required":false,"description":"Max results, clamped to 1–20; 0 or a non-numeric value falls back to 10.","schema":{"type":"integer","default":10,"minimum":1,"maximum":20}}]}},"/api/stock-ohlc":{"get":{"operationId":"stockOhlc","tags":["Stocks"],"summary":"Daily OHLCV candlestick bars for a ticker","description":"Reads the local daily aggregates for every weekday in the range (both ends inclusive); weekends and days without a bar are skipped.\n\nAn unknown ticker or a range with no data returns `200` with an empty `bars` array (no `404`).\n\n```bash\ncurl \"https://news.all-vista.org/api/stock-ohlc?ticker=AAPL&start=2026-01-01\"\n```","responses":{"200":{"description":"OHLCResponse\n\n```json\n{\n \"ticker\": \"NVDA\",\n \"bars\": [\n {\n \"date\": \"2026-03-17\",\n \"open\": 142.50,\n \"high\": 145.20,\n \"low\": 141.80,\n \"close\": 144.90,\n \"volume\": 38500000\n }\n ]\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"ticker":"NVDA","bars":[{"date":"2026-03-17","open":142.5,"high":145.2,"low":141.8,"close":144.9,"volume":38500000}]}}}},"400":{"description":"ticker missing"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"ticker","in":"query","required":true,"description":"Stock/ETF ticker symbol (case-insensitive; echoed back upper-cased).","schema":{"type":"string","example":"AAPL"}},{"name":"start","in":"query","required":false,"description":"Start date, YYYY-MM-DD (inclusive).","schema":{"type":"string","default":"180 days ago"}},{"name":"end","in":"query","required":false,"description":"End date, YYYY-MM-DD (inclusive).","schema":{"type":"string","default":"today (UTC)"}}]}},"/api/stock-news":{"get":{"operationId":"stockNews","tags":["Stocks"],"summary":"X/Twitter posts mentioning a stock (matched by ticker, $tag, or company name)","description":"Looks the ticker up in the server-side news index built from every X post (cashtag, then bare symbol, then company name, with false-positive guards). Posts are newest first with exact-duplicate texts removed.\n\nThe full match list is returned (no paging). An unknown ticker returns `200` with an empty `news` array.\n\n```bash\ncurl \"https://news.all-vista.org/api/stock-news?ticker=TSLA\"\n```","responses":{"200":{"description":"StockNews\n\n```json\n{\n \"ticker\": \"TSLA\",\n \"news\": [\n {\n \"id\": \"x_20320980...\",\n \"timestamp\": \"2026-03-15T12:00:00.000Z\",\n \"raw_text\": \"$TSLA deliveries beat expectations...\",\n \"author\": \"CNBC\",\n \"matchScore\": 1.0, // 1.0 = cashtag, 0.9 = bare symbol, 0.8 = company name\n \"matchReason\": \"$TSLA\",\n \"matchTier\": \"cashtag\" // \"cashtag\" | \"symbol\" | \"name\"\n }\n ]\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"ticker":"TSLA","news":[{"id":"x_20320980...","timestamp":"2026-03-15T12:00:00.000Z","raw_text":"$TSLA deliveries beat expectations...","author":"CNBC","matchScore":1,"matchReason":"$TSLA","matchTier":"cashtag"}]}}}},"400":{"description":"ticker missing"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"ticker","in":"query","required":true,"description":"Stock ticker symbol; dual share classes share one list (GOOGL resolves to GOOG).","schema":{"type":"string","example":"TSLA"}}]}},"/api/stock-returns":{"get":{"operationId":"stockReturns","tags":["Stocks"],"summary":"Forward returns (T+1, T+3, T+5 trading days) from an event date","description":"Closes on the next 1, 3 and 5 trading days after the event date, expressed as percentage change from the event-day close.\n\nWhen `date` is not a trading day (or the ticker has no bar that day) the route still answers `200` with `eventClose: null` and `t1`/`t3`/`t5` all `null`.\n\n`returnPct` is a percentage (0.90 = +0.90%). A horizon is `null` while fewer than that many trading days have elapsed since the event.\n\n```bash\ncurl \"https://news.all-vista.org/api/stock-returns?ticker=NVDA&date=2026-03-17\"\n```","responses":{"200":{"description":"ForwardReturns\n\n```json\n{\n \"eventDate\": \"2026-03-17\",\n \"eventClose\": 144.90,\n \"t1\": { \"date\": \"2026-03-18\", \"close\": 146.20, \"returnPct\": 0.90 },\n \"t3\": { \"date\": \"2026-03-20\", \"close\": 143.50, \"returnPct\": -0.97 },\n \"t5\": { \"date\": \"2026-03-24\", \"close\": 148.00, \"returnPct\": 2.14 } // null until 5 trading days have elapsed\n}\n```","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"eventDate":"2026-03-17","eventClose":144.9,"t1":{"date":"2026-03-18","close":146.2,"returnPct":0.9},"t3":{"date":"2026-03-20","close":143.5,"returnPct":-0.97},"t5":{"date":"2026-03-24","close":148,"returnPct":2.14}}}}},"400":{"description":"ticker or date missing"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"ticker","in":"query","required":true,"description":"Stock ticker symbol (case-insensitive).","schema":{"type":"string","example":"NVDA"}},{"name":"date","in":"query","required":true,"description":"Event date, YYYY-MM-DD (must be a trading day with a bar for the ticker).","schema":{"type":"string","example":"2026-03-17"}}]}},"/api/stock-analysis":{"post":{"operationId":"stockAnalysis","tags":["Stocks"],"summary":"AI-generated equity analysis with technicals + news synthesis","description":"Builds a prompt from the ticker's OHLC summary, the X posts matched inside the window and (when on file) the SEC fundamentals brief, then returns the model's ~400-word write-up as plain text.\n\n⚠ Triggers an LLM call (~120s; the route allows up to 300s).\n\nResults are memoised in process memory per `ticker`/`startDate`/`endDate`/`locale` (last 50 keys); a hit returns immediately with `X-AI-Provider: cache`.\n\nLLM-backed: counts against the `llm` rate limit and returns `X-AI-Provider` / `X-AI-Model` headers.\n\n```bash\ncurl -X POST https://news.all-vista.org/api/stock-analysis -H \"Content-Type: application/json\" -d '{\"ticker\":\"NVDA\",\"locale\":\"zh\"}'\n```","responses":{"200":{"description":"text/plain\n\n```json\n// Content-Type: text/plain; charset=utf-8\n// X-AI-Provider: