Agentic Rewards Discovery Suite

Fetch one program's FULL detail via GET /api/v1/programs/{code} on the CN PRODUCTION host https://vsra.offerpluscn.com (fixed apiUrlTemplate — host parameter REMOVED 2026-07-08 to restore CN retrieval; HK/TW routing temporarily suspended). Anonymous (no auth). {code} is a PATH parameter — the program code (e.g. P2026040009) taken verbatim from a VisaXB_Recommend item's 'code' field. Pass 'lang' (maps to X-Locale) matching the Steward's message; keep 'market' (informational) as the market of the recommend call the code came from (codes are catalog-specific). DO NOT pass 'host' (no such param anymore). RESPONSE SHAPE: returns {success:true, data:{...}} carrying all the recommend item fields plus three detail-only fields. The full field set is: 'code', 'type' (benefit|reward), 'title', 'short_title', 'subtitle', 'brief_description', 'detail_description' (claim method), 'terms' (eligibility, spending thresholds, per-period limits, count caps), 'merchant_description', 'tags', 'level_match', 'level_exclusive', 'reasons', 'relevance', 'url' (user-facing short link to click), 'link_h5', 'link_miniapp', 'tile_image_url', 'banner_image_url', 'starts_at' and 'ends_at'. INTERNAL-ONLY, never shown to the Steward: 'reasons', 'relevance', 'level_match'. Call this whenever the Steward asks how to claim a program, what its conditions are, or for activity details. Distill the core gates concisely (spending threshold, eligibility, key limits, count caps). An UNKNOWN/invalid code returns HTTP 404 {message:'The route ... could not be found.'} — so only ever call with a code returned by a real recommend response this turn. Read-only. Never expose codes/params/axis names in the user-facing reply.

Fetch the current canonical taxonomy code lists via GET /api/v1/taxonomy on the CN PRODUCTION host https://vsra.offerpluscn.com (fixed apiUrlTemplate — host parameter REMOVED 2026-07-08; HK/TW routing temporarily suspended). Anonymous (no auth). Pass 'lang' (maps to X-Locale) so the code labels come back in the Steward's language when the backend supports it. DO NOT pass 'host' (no such param anymore). RESPONSE SHAPE: returns a TOP-LEVEL object (NOT wrapped in success/data) with 'version' (taxonomy v1), 'prompt_version' (prompt v9), an 'axes' metadata block followed by one top-level key per axis holding the code lists, each code carrying {zh,en} labels: 'purpose' (flat), 'region' (split into 'groups' = macro-areas and 'countries' = ISO codes), 'category' (parent code with 'children' for second-level codes), 'reward_type', 'attribute', 'card_level', and 'card_type'. This is the live source of truth for those axes. Call this ONLY when a Steward's wording does not map cleanly to the representative samples documented on VisaXB_Recommend's parameter descriptions. IMPORTANT: this endpoint does NOT return card_issuer codes (the issuer axis is marked external and is sourced separately from issuers.code). Also note 'card_type' is INFORMATIONAL only — it is NOT a working recommend filter (passing card_type[] is ignored). Hierarchy still auto-expands server-side. Read-only.

Recommend Visa cross-border benefits and reward campaigns via GET /api/v1/programs/recommend on the CN PRODUCTION host https://vsra.offerpluscn.com (fixed apiUrlTemplate — host parameter REMOVED 2026-07-08 to restore CN retrieval after a {0}-placeholder experiment regressed to ~18% hit rate; HK/TW routing temporarily suspended, will be re-introduced separately). Anonymous (no auth). QUERY SERIALIZATION: each of the seven taxonomy axes (region, category, purpose, reward_type, attribute, card_level, card_issuer) is an ARRAY of canonical taxonomy codes; each value is emitted as its own repeated querystring pair named '<axis>[]'. SEMANTICS: multiple values within the SAME axis = OR (match any); values across DIFFERENT axes = AND (all must hold). Pass all values a Steward gives for one dimension together in that axis's array — never split into multiple calls. Hierarchy auto-expands server-side: a region macro-area code matches its member countries; a top-level category code matches all its sub-codes. LANGUAGE: pass 'lang' (zh-CN/zh-TW/zh-HK/en) matching the Steward's current message — it maps to the X-Locale header; content is Chinese-only today, so on English the Mind translates the returned titles/briefs/terms faithfully. MARKET: 'market' is informational only (cn=default, hk/tw currently return CN catalog data because HK/TW routing is suspended) — do NOT pass 'host' (no such param anymore). Optional scalars: 'type' (enum reward|benefit) — OMITTED by default so both benefits and campaigns return; add 'reward' only when the Steward explicitly means the sign-up/registration kind. 'keyword' is a title/brief substring filter. Always-appended scalars: 'limit' (default 10) and 'page' (default 1). RESPONSE SHAPE: returns {success:true, data:{...}} where data is an envelope with these fields: 'total', 'page', 'limit', 'count', 'invalid_codes', 'relaxed_axes', and 'items' (array). Each item carries: 'code' (program id, e.g. P2026040009), 'type' (reward|benefit), 'title', 'short_title', 'subtitle', 'brief_description', 'tags', 'level_match', 'level_exclusive', 'reasons', 'relevance', 'url' (the user-facing short link to click), 'link_h5', 'link_miniapp', 'tile_image_url', 'banner_image_url', 'starts_at' and 'ends_at' (both 'YYYY-MM-DD HH:MM:SS' strings). INTERNAL-ONLY fields, NEVER shown to the Steward: 'reasons', 'relevance', 'level_match', 'invalid_codes', 'relaxed_axes'. Read-only. On empty results, tell the Steward warmly that nothing was found and suggest broadening scope.