{ "openapi": "3.1.1", "info": { "title": "China Snapshot API", "version": "2.0.0", "description": "Programmatic access to the China Snapshot agent-native surface: public data feeds (CORS-open JSON), the Professional research REST API, and the MCP Streamable HTTP endpoint. Public feeds need no key; research and MCP calls require a Professional credential with the matching entitlement. See the developer portal (https://china-snapshot.com/developers) for authentication, the CLI, and quickstarts.", "contact": { "email": "contact@china-snapshot.com", "name": "China Snapshot" } }, "servers": [ { "url": "https://china-snapshot.com", "description": "Production" } ], "x-api-version": "2", "x-versioning": { "current": "v2", "location": "X-Api-Version header on every API response", "policy": "v2 is the current surface. v1 was an internal preview with no public consumers and was superseded in place by v2 (no notice period). A future v3 will coexist with v2 for a notice period: the still-live v2 advertises a Deprecation (RFC 9745) date when retirement starts and a Sunset (RFC 8594) date when it is removed. Backward-compatible additive changes land on the current version without a bump and are documented in the developer portal." }, "x-rate-limits": { "headers": [ "RateLimit-Limit", "RateLimit-Remaining", "RateLimit-Reset", "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset", "Retry-After (on 429)" ], "per_ip": "30 requests / 60s", "per_account": "120 requests / 60s", "monthly_allowance": "Professional: 5,000 combined API + MCP requests per calendar month; hard cap, no overage.", "reset": "00:00 UTC on the 1st of each calendar month" }, "tags": [ { "name": "data", "description": "Public CORS-open data feeds." }, { "name": "research", "description": "The Professional research REST API." }, { "name": "mcp", "description": "The MCP Streamable HTTP JSON-RPC endpoint." }, { "name": "docs", "description": "Developer-facing documentation surfaces." } ], "paths": { "/data/endpoints.json": { "get": { "operationId": "getEndpointsCatalog", "summary": "Fetch endpoints", "description": "The self-describing catalog of every public China Snapshot data feed, regenerated after each collection run. Category, schema, access level, series, and item counts.", "tags": [ "data" ], "security": [], "responses": { "200": { "description": "The requested feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "generated_at": { "type": "string" }, "license": { "type": "string" }, "llms_txt": { "type": "string" }, "agents_txt": { "type": "string" }, "developer_portal": { "type": "string" }, "developer_portal_markdown": { "type": "string" }, "openapi": { "type": "string" }, "schema": { "type": "object", "properties": { "version": { "type": "integer" }, "feed_schema_url": { "type": "string" }, "digest_schema_url": { "type": "string" }, "synthesis_schema_url": { "type": "string" }, "geo_catalog_schema_url": { "type": "string" }, "signal_packet_schema_url": { "type": "string" }, "feeds": { "type": "string" }, "digest": { "type": "string" }, "history": { "type": "string" }, "series": { "type": "string" }, "access": { "type": "string" } } }, "access": { "type": "object", "properties": { "default": { "type": "string" }, "levels": { "type": "object", "properties": { "public": { "type": "string" }, "professional": { "type": "string" } } }, "professional_url_prefixes": { "type": "array", "items": { "type": "string" } }, "professional_endpoints": { "type": "object", "properties": { "https://china-snapshot.com/api/research": { "type": "string" }, "https://china-snapshot.com/api/mcp": { "type": "string" } } }, "how_to_access": { "type": "string" } } }, "archive": { "type": "object", "properties": { "description": { "type": "string" }, "access": { "type": "string" }, "how_to_access": { "type": "string" }, "index_url": { "type": "string" }, "url_template": { "type": "string" }, "slots": { "type": "array", "items": { "type": "string" } }, "earliest_date": { "type": "string" }, "latest_date": { "type": "string" }, "indexed_snapshots": { "type": "integer" }, "note": { "type": "string" } } }, "synthesis": { "type": "object", "properties": { "description": { "type": "string" }, "access": { "type": "string" }, "how_to_access": { "type": "string" }, "index_url": { "type": "string" }, "entities_url": { "type": "string" }, "topic_url_template": { "type": "string" }, "version_permalink_template": { "type": "string" }, "topic_count": { "type": "integer" } } }, "special": { "type": "object", "properties": { "agents_txt": { "type": "string" }, "daily_digest": { "type": "string" }, "daily_digest_markdown": { "type": "string" }, "payload_budget": { "type": "string" }, "health": { "type": "string" }, "source_reliability": { "type": "string" }, "geo_catalog": { "type": "string" }, "professional_api": { "type": "string" }, "professional_mcp": { "type": "string" }, "openapi": { "type": "string" }, "developer_portal": { "type": "string" }, "professional_signal_packet": { "type": "object", "properties": { "json": { "type": "string" }, "markdown": { "type": "string" }, "access": { "type": "string" } } }, "gov_registry_health": { "type": "string" }, "public_signal_packet": { "type": "string" }, "public_signal_packet_markdown": { "type": "string" } } }, "feeds": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" }, "access": { "type": "string" }, "as_of": { "type": "string" }, "schema_id": { "type": "string" }, "schema_url": { "type": "string" }, "item_count": { "type": "integer" }, "series": { "type": "array", "items": { "type": "string" } }, "history_url": { "type": "string" }, "history_access": { "type": "string" } } } }, "forecasts": { "type": "object", "properties": { "description": { "type": "string" }, "access": { "type": "string" }, "index_url": { "type": "string" }, "track_record_url": { "type": "string" }, "question_url_template": { "type": "string" }, "human_url": { "type": "string" }, "as_of": { "type": "string" }, "counts": { "type": "object", "properties": { "total": { "type": "integer" }, "public": { "type": "integer" }, "member": { "type": "integer" }, "open": { "type": "integer" }, "resolved": { "type": "integer" }, "void": { "type": "integer" } } }, "note": { "type": "string" } } } }, "additionalProperties": true, "description": "Inferred from the live feed at build time. The field inventory reflects this collection run; optional fields may be absent and the shape is refreshed on every deploy." } } } }, "404": { "description": "Feed not published for this run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/data/daily_digest.json": { "get": { "operationId": "getDailyDigest", "summary": "Fetch daily_digest", "description": "The current cross-source synthesis: headline, narrative, market snapshot, deviations, themes, entities, pillars, and ranked top stories.", "tags": [ "data" ], "security": [], "responses": { "200": { "description": "The requested feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_version": { "type": "integer" }, "digest_type": { "type": "string" }, "as_of": { "type": "string" }, "date": { "type": "string" }, "time_label": { "type": "string" }, "beijing_time": { "type": "string" }, "generated_by": { "type": "string" }, "editorial_review": { "type": "object", "properties": { "model": { "type": "string" }, "passes": { "type": "integer" }, "score": { "type": "integer" }, "dimensions": { "type": "object", "properties": { "evidence_integrity": { "type": "integer" }, "executive_clarity": { "type": "integer" }, "decision_utility": { "type": "integer" }, "selectivity": { "type": "integer" }, "voice": { "type": "integer" } } }, "hard_failures": { "type": "array", "items": {} }, "deterministic_issues": { "type": "array", "items": { "type": "string" } }, "revision_notes": { "type": "array", "items": { "type": "string" } }, "passed": { "type": "boolean" }, "ungrounded_overrides": { "type": "integer" }, "ungrounded_story_indices": { "type": "array", "items": {} }, "model_overrides_offered": { "type": "integer" }, "model_overrides_applied": { "type": "integer" }, "override_alignment_failed": { "type": "boolean" }, "sanitized_stories": { "type": "array", "items": {} }, "stories_dropped_by_sanitizer": { "type": "array", "items": {} }, "llm_usage": { "type": "object", "properties": { "calls": { "type": "integer" }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" } } }, "current_read_deterministic_issues": { "type": "array", "items": {} }, "current_read_passed": { "type": "boolean" }, "current_read_focused_recovery": { "type": "object", "properties": { "score": { "type": "integer" }, "dimensions": { "type": "object", "properties": { "evidence_integrity": { "type": "integer" }, "executive_clarity": { "type": "integer" }, "decision_utility": { "type": "integer" }, "selectivity": { "type": "integer" }, "voice": { "type": "integer" } } }, "hard_failures": { "type": "array", "items": {} }, "deterministic_issues": { "type": "array", "items": {} }, "llm_usage": { "type": "object", "properties": { "calls": { "type": "integer" }, "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" } } } } }, "current_read_failed_issues": { "type": "array", "items": { "type": "string" } }, "fallback": { "type": "string" } } }, "review_status": { "type": "string" }, "review_status_reason": { "type": "string" }, "headline": { "type": "string" }, "headline_zh": { "type": "string" }, "narrative": { "type": "string" }, "narrative_zh": { "type": "string" }, "market_snapshot": { "type": "string" }, "market_snapshot_stale": { "type": "boolean" }, "market_snapshot_session_date": { "type": "string" }, "deviations": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "note": { "type": "string" }, "note_zh": { "type": "string" }, "kind": { "type": "string" }, "flags": { "type": "array", "items": { "type": "string" } }, "z30": { "type": "number" }, "severity": { "type": "number" }, "days_flagged": { "type": "integer" } } } }, "changes_since_prior": { "type": "object", "properties": { "prior_as_of": { "type": "string" }, "prior_label": { "type": "string" }, "new_count": { "type": "integer" }, "carried_count": { "type": "integer" }, "new_signals": { "type": "array", "items": { "type": "string" } } } }, "themes": { "type": "array", "items": { "type": "string" } }, "theme_trends": { "type": "object", "properties": { "food safety": { "type": "object", "properties": { "status": { "type": "string" }, "days_seen": { "type": "integer" } } }, "infrastructure": { "type": "object", "properties": { "status": { "type": "string" }, "days_seen": { "type": "integer" } } }, "foreign investment": { "type": "object", "properties": { "status": { "type": "string" }, "days_seen": { "type": "integer" } } }, "sports governance": { "type": "object", "properties": { "status": { "type": "string" }, "days_seen": { "type": "integer" } } } } }, "entities": { "type": "array", "items": { "type": "string" } }, "pillars": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "label_zh": { "type": "string" } } } }, "top_stories": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "first_seen": { "type": "string" }, "days_on_board": { "type": "integer" }, "story_status": { "type": "string" }, "continuity_basis": { "type": "string" }, "narrative_eligible": { "type": "boolean" }, "narrative_reason": { "type": "string" }, "weight": { "type": "number" }, "weight_components": { "type": "object", "properties": { "base": { "type": "integer" }, "repeat_editions_excluded": { "type": "integer" }, "cross_platform_bonus": { "type": "number" }, "significance_class": { "type": "string" }, "source_class_factor": { "type": "number" }, "deviation_linked": { "type": "boolean" }, "deviation_factor": { "type": "number" }, "weight": { "type": "number" } } }, "platforms": { "type": "array", "items": { "type": "string" } }, "platform_count": { "type": "integer" }, "source_class": { "type": "string" }, "source_class_label": { "type": "string" }, "confidence": { "type": "number" }, "primary_title": { "type": "string" }, "english_title": { "type": "string" }, "observed_signal": { "type": "string" }, "why_it_matters": { "type": "string" }, "why_it_matters_zh": { "type": "string" }, "what_to_watch": { "type": "string" }, "what_to_watch_zh": { "type": "string" }, "pull_quote": { "type": "string" }, "pull_quote_zh": { "type": "string" }, "analysis_basis": { "type": "object", "properties": { "type": { "type": "string" }, "implication_source": { "type": "string" }, "watchpoint_source": { "type": "string" }, "evidence_ids": { "type": "array", "items": {} }, "note": { "type": "string" } } }, "watcher_lenses": { "type": "array", "items": { "type": "string" } }, "pillar": { "type": "string" }, "pillar_label": { "type": "string" }, "pillar_label_zh": { "type": "string" }, "source": { "type": "string" }, "category": { "type": "string" }, "url": { "type": "string" }, "appearances": { "type": "array", "items": { "type": "object", "properties": { "platform": {}, "rank": {} } } }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "id": {}, "source": {}, "source_label": {}, "rank": {}, "title": {}, "url": {}, "source_class": {}, "description": {} } } } } } }, "evidence_summary": { "type": "object", "properties": { "mode": { "type": "string" }, "claim_boundary": { "type": "string" }, "evidence_count": { "type": "integer" }, "source_classes": { "type": "object", "properties": { "official": { "type": "string" }, "state_media": { "type": "string" }, "commercial_press": { "type": "string" }, "social": { "type": "string" }, "market": { "type": "string" }, "calculation": { "type": "string" } } } } }, "sources_summary": { "type": "object", "properties": { "baidu_top": { "type": "integer" }, "weibo_hot": { "type": "integer" }, "tencent_wechat_hot": { "type": "integer" }, "xinhua_news": { "type": "integer" }, "thepaper_news": { "type": "integer" }, "ladymax_news": { "type": "integer" }, "gov_registry": { "type": "integer" }, "elite_press": { "type": "integer" }, "indices": { "type": "integer" }, "fx": { "type": "integer" } } }, "disclaimer": { "type": "string" }, "art": { "type": "object", "properties": { "key": { "type": "string" }, "src": { "type": "string" }, "subject": { "type": "string" }, "location": { "type": "string" }, "alt": { "type": "string" }, "position": { "type": "string" } } }, "hero_image": { "type": "string" }, "hero_caption": { "type": "string" }, "hero_credit": { "type": "string" } }, "additionalProperties": true, "description": "Inferred from the live feed at build time. The field inventory reflects this collection run; optional fields may be absent and the shape is refreshed on every deploy." } } } }, "404": { "description": "Feed not published for this run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/data/baselines.json": { "get": { "operationId": "getBaselines", "summary": "Fetch baselines", "description": "30/90-day archive baselines per numeric series plus a ranked deviations list (z-spikes, range breaks, new prints).", "tags": [ "data" ], "security": [], "responses": { "200": { "description": "The requested feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_version": { "type": "integer" }, "as_of": { "type": "string" }, "source": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "value": { "type": "number" }, "url": { "type": "string" }, "extra": { "type": "object", "properties": { "feed": { "type": "string" }, "feed_label": { "type": "string" }, "unit": { "type": "string" }, "kind": { "type": "string" }, "latest_source": { "type": "string" }, "baseline_30d": { "type": "object", "properties": { "days": {}, "mean": {}, "std": {}, "min": {}, "max": {} } }, "baseline_90d": { "type": "object", "properties": { "days": {}, "mean": {}, "std": {}, "min": {}, "max": {} } }, "z30": { "type": "number" }, "flags": { "type": "array", "items": {} }, "note": { "type": "string" }, "note_zh": { "type": "string" }, "days_flagged": { "type": "integer" }, "archive_corrected_days": { "type": "integer" }, "archive_stale_days_excluded": { "type": "integer" } } } } } }, "window_days": { "type": "integer" }, "short_window_days": { "type": "integer" }, "deviations": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "feed": { "type": "string" }, "feed_label": { "type": "string" }, "kind": { "type": "string" }, "flags": { "type": "array", "items": { "type": "string" } }, "z30": { "type": "number" }, "severity": { "type": "number" }, "severity_raw": { "type": "number" }, "first_flagged": { "type": "string" }, "last_flagged": { "type": "string" }, "days_flagged": { "type": "integer" }, "note": { "type": "string" }, "note_zh": { "type": "string" } } } }, "suppressed": { "type": "object", "properties": { "archive_corrections": { "type": "array", "items": {} }, "archive_correction_pending": { "type": "array", "items": {} }, "stale_archive_days": { "type": "object", "properties": { "ChiNext": { "type": "integer" }, "SSE Composite": { "type": "integer" }, "STAR 50": { "type": "integer" }, "Shenzhen Component": { "type": "integer" } } }, "suspect_values": { "type": "array", "items": {} }, "baseline_building": { "type": "array", "items": {} } } }, "notes": { "type": "string" } }, "additionalProperties": true, "description": "Inferred from the live feed at build time. The field inventory reflects this collection run; optional fields may be absent and the shape is refreshed on every deploy." } } } }, "404": { "description": "Feed not published for this run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/data/forecasts/index.json": { "get": { "operationId": "getForecastBoard", "summary": "Fetch forecasts/index", "description": "The Forecast Desk board: resolvable questions on Chinese policy and data prints with their resolution criteria and probability history.", "tags": [ "data" ], "security": [], "responses": { "200": { "description": "The requested feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_version": { "type": "integer" }, "as_of": { "type": "string" }, "source": { "type": "string" }, "counts": { "type": "object", "properties": { "total": { "type": "integer" }, "public": { "type": "integer" }, "member": { "type": "integer" }, "open": { "type": "integer" }, "resolved": { "type": "integer" }, "void": { "type": "integer" } } }, "track_record_url": { "type": "string" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "criterion": { "type": "string" }, "pillar": { "type": "string" }, "question_class": { "type": "string" }, "access": { "type": "string" }, "status": { "type": "string" }, "opens": { "type": "string" }, "resolve_by": { "type": "string" }, "resolver_summary": { "type": "string" }, "probability": { "type": "number" }, "spread": { "type": "number" }, "members": { "type": "integer" }, "method": { "type": "string" }, "model": { "type": "string" }, "provisional": { "type": "boolean" }, "base_rate": { "type": "object", "properties": { "available": { "type": "boolean" }, "kind": { "type": "string" }, "probability": { "type": "number" }, "observed_days": { "type": "integer" }, "note": { "type": "string" }, "reason": { "type": "string" }, "observed_prints": { "type": "integer" }, "detail": { "type": "string" }, "window": { "type": "object", "properties": { "first_day": {}, "last_day": {} } } } }, "evidence_quality": { "type": "object", "properties": { "grade": { "type": "string" }, "documents": { "type": "integer" }, "term_matched": { "type": "integer" }, "dated": { "type": "integer" } } }, "updated_at": { "type": "string" }, "resolution": {}, "note": { "type": "string" } } } } }, "additionalProperties": true, "description": "Inferred from the live feed at build time. The field inventory reflects this collection run; optional fields may be absent and the shape is refreshed on every deploy." } } } }, "404": { "description": "Feed not published for this run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/data/forecasts/track_record.json": { "get": { "operationId": "getForecastTrackRecord", "summary": "Fetch forecasts/track_record", "description": "The Forecast Desk track record in full, including misses and voids, so the score can be independently checked.", "tags": [ "data" ], "security": [], "responses": { "200": { "description": "The requested feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_version": { "type": "integer" }, "as_of": { "type": "string" }, "resolved": { "type": "integer" }, "void": { "type": "integer" }, "yes_rate": { "type": "number" }, "mean_brier": { "type": "number" }, "mean_log_score": { "type": "number" }, "base_rate_brier": { "type": "number" }, "base_rate_comparable_n": { "type": "integer" }, "brier_skill_vs_base_rate": { "type": "number" }, "calibration": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string" }, "low": { "type": "number" }, "high": { "type": "number" }, "n": { "type": "integer" }, "observed_yes": { "type": "integer" }, "observed_rate": { "type": "number" }, "mean_probability": { "type": "number" } } } }, "calibration_building": { "type": "boolean" }, "min_resolved_for_calibration": { "type": "integer" }, "note": { "type": "string" }, "resolved_questions": { "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string" }, "probability": { "type": "number" }, "base_rate": { "type": "number" }, "outcome": { "type": "string" }, "resolved_on": { "type": "string" }, "title": { "type": "string" }, "access": { "type": "string" } } } } }, "additionalProperties": true, "description": "Inferred from the live feed at build time. The field inventory reflects this collection run; optional fields may be absent and the shape is refreshed on every deploy." } } } }, "404": { "description": "Feed not published for this run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/data/signal-packet.json": { "get": { "operationId": "getSignalPacket", "summary": "Fetch signal-packet", "description": "The current validated public Signal Packet (export controls) as JSON.", "tags": [ "data" ], "security": [], "responses": { "200": { "description": "The requested feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_version": { "type": "integer" }, "packet_version": { "type": "integer" }, "packet_id": { "type": "string" }, "edition_id": { "type": "string" }, "topic_ids": { "type": "array", "items": {} }, "entity_ids": { "type": "array", "items": {} }, "institution_ids": { "type": "array", "items": { "type": "string" } }, "place_ids": { "type": "array", "items": {} }, "change": { "type": "object", "properties": { "change_type": { "type": "string" }, "measure_type": { "type": "string" }, "status": { "type": "string" }, "prior_state": { "type": "object", "properties": { "claim_id": { "type": "string" }, "claim_type": { "type": "string" }, "statement": { "type": "string" }, "material": { "type": "boolean" }, "support_status": { "type": "string" }, "evidence_ids": { "type": "array", "items": {} }, "calculation_ids": { "type": "array", "items": {} }, "basis_claim_ids": { "type": "array", "items": {} }, "provenance_kind": { "type": "string" }, "generated": { "type": "boolean" } } }, "materiality": { "type": "object", "properties": { "claim_id": { "type": "string" }, "claim_type": { "type": "string" }, "statement": { "type": "string" }, "material": { "type": "boolean" }, "support_status": { "type": "string" }, "evidence_ids": { "type": "array", "items": {} }, "calculation_ids": { "type": "array", "items": {} }, "basis_claim_ids": { "type": "array", "items": { "type": "string" } }, "provenance_kind": { "type": "string" }, "generated": { "type": "boolean" } } } } }, "observations": { "type": "array", "items": { "type": "object", "properties": { "claim_id": { "type": "string" }, "claim_type": { "type": "string" }, "statement": { "type": "string" }, "material": { "type": "boolean" }, "support_status": { "type": "string" }, "evidence_ids": { "type": "array", "items": { "type": "string" } }, "calculation_ids": { "type": "array", "items": {} }, "basis_claim_ids": { "type": "array", "items": {} }, "provenance_kind": { "type": "string" }, "generated": { "type": "boolean" }, "value": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": [ "integer", "string" ] }, "unit": { "type": "string" } } } } } }, "significance": { "type": "array", "items": { "type": "object", "properties": { "claim_id": { "type": "string" }, "claim_type": { "type": "string" }, "statement": { "type": "string" }, "material": { "type": "boolean" }, "support_status": { "type": "string" }, "evidence_ids": { "type": "array", "items": {} }, "calculation_ids": { "type": "array", "items": {} }, "basis_claim_ids": { "type": "array", "items": { "type": "string" } }, "provenance_kind": { "type": "string" }, "generated": { "type": "boolean" } } } }, "interpretation": { "type": "array", "items": {} }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "evidence_id": { "type": "string" }, "source_class": { "type": "string" }, "publisher_id": { "type": "string" }, "publisher_name": { "type": "string" }, "url": { "type": "string" }, "language": { "type": "string" }, "original_title": { "type": "string" }, "translated_title": { "type": "string" }, "translation_id": { "type": "string" }, "published_at": {}, "collected_at": { "type": "string" }, "supports_claim_ids": { "type": "array", "items": { "type": "string" } } } } }, "historical_comparisons": { "type": "array", "items": {} }, "uncertainties": { "type": "array", "items": { "type": "object", "properties": { "claim_id": { "type": "string" }, "claim_type": { "type": "string" }, "statement": { "type": "string" }, "material": { "type": "boolean" }, "support_status": { "type": "string" }, "evidence_ids": { "type": "array", "items": {} }, "calculation_ids": { "type": "array", "items": {} }, "basis_claim_ids": { "type": "array", "items": {} }, "provenance_kind": { "type": "string" }, "generated": { "type": "boolean" } } } }, "watch_next": { "type": "array", "items": { "type": "object", "properties": { "watch_id": { "type": "string" }, "institution_ids": { "type": "array", "items": { "type": "string" } }, "condition": { "type": "object", "properties": { "claim_id": { "type": "string" }, "claim_type": { "type": "string" }, "statement": { "type": "string" }, "material": { "type": "boolean" }, "support_status": { "type": "string" }, "evidence_ids": { "type": "array", "items": {} }, "calculation_ids": { "type": "array", "items": {} }, "basis_claim_ids": { "type": "array", "items": {} }, "provenance_kind": { "type": "string" }, "generated": { "type": "boolean" } } }, "expected_at": {}, "would_confirm_claim_ids": { "type": "array", "items": { "type": "string" } }, "would_invalidate_claim_ids": { "type": "array", "items": {} } } } }, "times": { "type": "object", "properties": { "event_at": {}, "published_at": {}, "effective_at": {}, "observed_at": { "type": "string" }, "collected_at": { "type": "string" }, "generated_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "translations": { "type": "array", "items": { "type": "object", "properties": { "translation_id": { "type": "string" }, "source_evidence_id": { "type": "string" }, "source_language": { "type": "string" }, "target_language": { "type": "string" }, "field": { "type": "string" }, "model_provider": { "type": "string" }, "model": { "type": "string" }, "generated_at": { "type": "string" } } } }, "calculations": { "type": "array", "items": {} }, "confidence": { "type": "object", "properties": { "evidence": { "type": "object", "properties": { "level": { "type": "string" }, "score": { "type": "number" }, "rationale": { "type": "string" }, "claim_type": { "type": "string" } } }, "change_detection": { "type": "object", "properties": { "level": { "type": "string" }, "score": { "type": "number" }, "rationale": { "type": "string" }, "claim_type": { "type": "string" } } }, "interpretation": { "type": "object", "properties": { "level": { "type": "string" }, "score": {}, "rationale": { "type": "string" }, "claim_type": { "type": "string" } } }, "overall": { "type": "object", "properties": { "level": { "type": "string" }, "score": { "type": "number" }, "rationale": { "type": "string" }, "claim_type": { "type": "string" } } } } }, "lifecycle": { "type": "object", "properties": { "state": { "type": "string" }, "freshness": { "type": "string" }, "prior_packet_id": {}, "replacement_packet_id": {}, "reason": {} } }, "access": { "type": "object", "properties": { "classification": { "type": "string" }, "public_sample": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "edition_packet_limit": { "type": "integer" }, "evidence_limit": { "type": "integer" }, "selected_evidence_ids": { "type": "array", "items": { "type": "string" } }, "projection_of_packet_id": { "type": "string" }, "selection_method": { "type": "string" } } } } } }, "additionalProperties": true, "description": "Inferred from the live feed at build time. The field inventory reflects this collection run; optional fields may be absent and the shape is refreshed on every deploy." } } } }, "404": { "description": "Feed not published for this run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/data/digest.md": { "get": { "operationId": "getDailyDigestMarkdown", "summary": "Fetch the current briefing as Markdown", "description": "The current cross-source synthesis as Markdown, served with Vary: Accept so Accept: text/markdown negotiation is cache-safe. The same document the human reads on the Snapshot page. A client that requests an unsupported representation receives 406.", "tags": [ "data" ], "security": [], "responses": { "200": { "description": "The briefing in Markdown.", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "406": { "$ref": "#/components/responses/NotAcceptable" } } } }, "/.well-known/mcp.json": { "get": { "operationId": "getMcpManifest", "summary": "The MCP server manifest", "description": "A standards-based MCP manifest declaring the Streamable HTTP endpoint, its five tools, capabilities, rate limits, and authentication, so clients that discover MCP servers by manifest can find this one.", "tags": [ "mcp" ], "security": [], "responses": { "200": { "description": "The MCP manifest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpManifest" } } } } } } }, "/api/{path}": { "get": { "operationId": "apiNotFound", "summary": "Catch-all for undocumented API routes", "description": "Any /api/* route no other handler owns returns this structured JSON 404 with an X-Api-Version header, so an agent probing an undocumented route gets a parseable envelope, never the HTML app shell.", "tags": [ "research" ], "security": [], "parameters": [ { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "apiNotFoundPost", "summary": "Catch-all for undocumented API routes (POST)", "description": "Structured JSON 404 for POST to an undocumented /api/* route.", "tags": [ "research" ], "security": [], "parameters": [ { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/research": { "get": { "operationId": "researchDiscovery", "summary": "Describe the Professional research API", "description": "Unauthenticated discovery response. Describes the endpoint, the five operations, authentication, quotas, and links to pricing and account. Actual research calls are POST-only.", "tags": [ "research" ], "security": [], "responses": { "200": { "description": "The self-describing discovery body.", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "operationId": "researchInvoke", "summary": "Run one Professional research operation", "description": "Runs one of the five operations: get_digest, get_signal_packet, export_signal_packet, search_stories, get_entity_timeline. Requires a Professional credential with the api_access entitlement. Metered against the monthly allowance; an exhausted allowance returns 429 with Retry-After and X-RateLimit-* headers and never charges an overage.", "tags": [ "research" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operation", "arguments" ], "properties": { "operation": { "type": "string", "enum": [ "get_digest", "get_signal_packet", "export_signal_packet", "search_stories", "get_entity_timeline" ], "description": "The research operation to run." }, "arguments": { "type": "object", "description": "Operation arguments, validated against the operation's typed input schema.", "oneOf": [ { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, { "type": "object", "properties": { "packet_id": { "type": "string", "maxLength": 180 } }, "required": [], "additionalProperties": false }, { "type": "object", "properties": { "packet_id": { "type": "string", "maxLength": 180 }, "format": { "type": "string", "enum": [ "markdown", "json" ] } }, "required": [ "format" ], "additionalProperties": false }, { "type": "object", "properties": { "query": { "type": "string", "maxLength": 180 }, "limit": { "type": "integer", "minimum": 1, "maximum": 20 } }, "required": [ "query" ], "additionalProperties": false }, { "type": "object", "properties": { "entity": { "type": "string", "maxLength": 120 }, "limit": { "type": "integer", "minimum": 1, "maximum": 20 } }, "required": [ "entity" ], "additionalProperties": false } ] } } } } } }, "responses": { "200": { "description": "The operation result with usage metering.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": true, "description": "The operation's result object. Field shape varies by operation; each operation carries the honesty fields its tool description names (coverage, low_confidence, preview, belongs_to_current_edition, retained_last_known_good, and the limits thresholds for the search tools)." }, "usage": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/mcp": { "get": { "operationId": "mcpDiscovery", "summary": "Describe the MCP Streamable HTTP endpoint", "description": "Unauthenticated discovery response. The endpoint implements JSON-RPC 2.0 over POST (MCP Streamable HTTP). initialize, notifications/initialized, and ping are unauthenticated protocol methods; tools/list and tools/call require the mcp_access entitlement. The five tool names are the operation names shared with the REST surface.", "tags": [ "mcp" ], "security": [], "responses": { "200": { "description": "The self-describing MCP discovery body.", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "operationId": "mcpJsonRpc", "summary": "Send a JSON-RPC 2.0 message to the MCP endpoint", "description": "MCP Streamable HTTP JSON-RPC transport. Accepts initialize, notifications/initialized, ping, tools/list, and tools/call. tools/call requires the mcp_access entitlement and is metered against the monthly allowance.", "tags": [ "mcp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": [ "integer", "string", "null" ] }, "method": { "type": "string", "enum": [ "initialize", "ping", "tools/list", "tools/call" ] }, "params": { "type": "object" } } } } } }, "responses": { "200": { "description": "The JSON-RPC result object.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Accepted for a notification (no body)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/developers": { "get": { "operationId": "developerPortal", "summary": "The developer portal", "description": "A public page documenting the API, MCP, CLI, OpenAPI spec, and agent-readable files.", "tags": [ "docs" ], "security": [], "responses": { "200": { "description": "The developer portal HTML page." } } } }, "/openapi.json": { "get": { "operationId": "getOpenApi", "summary": "This OpenAPI document", "description": "The complete OpenAPI 3.1 description of the China Snapshot API surface.", "tags": [ "docs" ], "security": [], "responses": { "200": { "description": "The OpenAPI 3.1 JSON document." } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer or Authorization: Bearer cs_live_." } }, "schemas": { "McpManifest": { "type": "object", "required": [ "mcpServers" ], "properties": { "mcpServers": { "type": "object", "additionalProperties": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "transport": { "type": "string" }, "description": { "type": "string" }, "capabilities": { "type": "object", "additionalProperties": true }, "rate_limits": { "type": "object", "additionalProperties": true }, "auth": { "type": "object", "additionalProperties": true } } } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code, e.g. unauthorized or not_found." }, "message": { "type": "string", "description": "A human-readable explanation." }, "hint": { "type": "string", "description": "Optional resolution pointer." } } } } } }, "responses": { "BadRequest": { "description": "Invalid request. JSON-RPC maps 400 to -32602.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid credential. JSON-RPC maps 401 to -32001.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Authenticated but not entitled. JSON-RPC maps 403 to -32003.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "The requested resource or operation does not exist. JSON-RPC maps 404 to -32002.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotAcceptable": { "description": "No supported representation matches the Accept header. Retry with Accept: text/html or Accept: text/markdown.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Monthly allowance reached; no overage is charged. Retry after the calendar-month reset. Response carries RateLimit-* and X-RateLimit-* headers plus Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }