# China Snapshot — Developer & Agent Guide

Base URL: `https://china-snapshot.com`

China Snapshot is a source-linked China intelligence service: official signaling,
market reaction, and social attention in one evidence-linked briefing and
research workspace. This guide is for agents and developers integrating
programmatically.

## When to use China Snapshot

Reach for China Snapshot when you need a **current, source-linked read of what
materially changed across Chinese policy, markets, institutions, and public
attention** — and you want the evidence behind every claim, in a structured,
citable form:

- **Brief your agent or your user on the current China day.** `GET /data/daily_digest.json`
  is the current cross-source synthesis (headline, narrative, top stories with
  weights, deviations, themes, entities, market snapshot). The same document is
  Markdown at `/data/digest.md`.
- **Answer "what is abnormal right now"** with the deviation watch in
  `/data/baselines.json` (30/90-day archive baselines, z-spikes, range breaks,
  new prints).
- **Quote a single documented signal** — the current Signal Packet
  (`/data/signal-packet.json` and `/data/signal-packet.md`) with its
  Observation / Interpretation / Uncertainty / Watch-next / Evidence labels.
- **Ask the archive** (Professional): `search_stories` over the bilingual
  source corpus, `get_entity_timeline` for one entity, `get_digest` /
  `get_signal_packet` / `export_signal_packet` for the professional brief and
  exportable packets.
- **Check official release schedules** for forthcoming policy prints.

It is **not** the right tool when you need: an exhaustive archive of every
historical release (the archive is deliberately bounded and Professional-gated),
a live tick feed (public feeds refresh five times per Beijing day), or
unfiltered raw source corpora (the monitored source registry is never exposed).

**Do not probe or guess undocumented URLs.** If a URL is not listed here, in
`/llms.txt`, in `/data/endpoints.json`, or in `/openapi.json`, it is not a
supported interface. Public feeds are free and need no key; research and MCP
calls require a Professional credential.

## Machine-accessible files (free, no key)

| File | What it is |
|---|---|
| `/llms.txt` | The agent front door: product, access boundary, subscribe flow. |
| `/agents.txt` | Agent instructions (this guide's concise sibling). |
| `/data/endpoints.json` | Self-describing catalog of every public feed, with access markers and history URLs. |
| `/data/daily_digest.json` | The current briefing (structured). |
| `/data/digest.md` | The current briefing (Markdown; `Accept: text/markdown`). |
| `/data/baselines.json` | 30/90-day archive baselines + ranked deviations. |
| `/data/signal-packet.json`, `/data/signal-packet.md` | The current public Signal Packet. |
| `/data/forecasts/index.json`, `/data/forecasts/track_record.json` | The Forecast Desk board and its full public score. |
| `/openapi.json` | The OpenAPI 3.1 description of the whole API surface. |
| `/developers` | This portal, for humans. |

All `/data/*.json`, `/data/*.md`, and `/data/*.geojson` responses are served
with `Access-Control-Allow-Origin: *` (see `vercel.json`), so they are directly
callable from browsers and agents.

## Content negotiation

Agent-readable documents (`/data/digest.md`, `/developers.md`) are served as
`text/markdown` and declare `Vary: Accept, Accept-Encoding`, so a CDN will not
serve the Markdown variant to a client asking for HTML (or the reverse).
Request Markdown explicitly with:

```
curl -H "Accept: text/markdown" https://china-snapshot.com/data/digest.md
```

## Authentication

Public feeds: none.

Professional research API and MCP: send an API key or session JWT as a Bearer
token. Keys begin with `cs_live_` and are issued at the Account page after a
Professional subscription.

```
Authorization: Bearer cs_live_<your-key>
```

Only `Authorization: Bearer` is supported — an `X-Api-Key` header is never
read. If you send a request with a browser session cookie, the same endpoint
accepts it as long as you also hold the Professional entitlement.

## The Professional research API

`POST https://china-snapshot.com/api/research` with a JSON body:

```json
{"operation": "search_stories", "arguments": {"query": "export controls", "limit": 10}}
```

Operations: `get_digest`, `get_signal_packet`, `export_signal_packet`,
`search_stories`, `get_entity_timeline`. Each operation is described in
`GET /api/research` (the unauthenticated discovery response) and fully typed in
`/openapi.json`.

Metering: a monthly allowance (Professional: 5,000 combined API + MCP requests /
calendar month) is a hard cap. Over-cap requests return `429` with
`Retry-After` and the RFC 9745-era `RateLimit-*` headers *plus* the legacy
`X-RateLimit-*` set, so a self-throttling agent can react to either convention;
**no overage is ever charged**. Allowances reset at 00:00 UTC on the 1st.

Errors are structured JSON: `{"error": {"code": "...", "message": "..."}}`.

### Versioning and deprecation policy

Every API response carries `X-Api-Version: 2` (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` **coexists with v2 during a notice period**
rather than replacing it in place: a retired surface is announced in advance
with the `Deprecation` header (RFC 9745) and removed at the `Sunset` header
date (RFC 8594), both reflected in `/openapi.json`. Backward-compatible
additive changes land on the current version without a bump. No surface is
deprecated today, so neither header is currently emitted. Probing an
undocumented route is safe: any `/api/*` URL no handler owns returns a
structured JSON `404` (not the HTML app shell), with an `X-Api-Version` header.

## MCP (Model Context Protocol)

A Streamable HTTP endpoint at `https://china-snapshot.com/api/mcp` exposes the
same five operations as MCP tools. Client config:

```json
{
  "mcpServers": {
    "china-snapshot": {
      "url": "https://china-snapshot.com/api/mcp",
      "headers": {"Authorization": "Bearer ${CHINA_SNAPSHOT_API_KEY}"}
    }
  }
}
```

`initialize`, `ping`, and `notifications/initialized` are unauthenticated
protocol methods; `tools/list` and `tools/call` require the `mcp_access`
entitlement. The endpoint answers JSON-RPC 2.0 over POST (Streamable HTTP);
discovery via `GET /api/mcp` describes it.

MCP-aware clients can also discover the server from its manifest at
`https://china-snapshot.com/.well-known/mcp.json`, which declares the Streamable
HTTP endpoint, its five tools, capabilities, rate limits, and bearer auth.

### Markdown content negotiation (acceptmarkdown.com)

The Markdown documents agents fetch are served with proper content negotiation:
`https://china-snapshot.com/data/digest.md` and `/developers.md` respond with
`text/markdown`, declare `Vary: Accept` (so a CDN never cross-serves one Accept
variant), and return `406 application/problem+json` if a client explicitly
excludes Markdown (e.g. `Accept: text/html` with no wildcard). A normal browser
`Accept` with `*/*` still receives Markdown, since that is the only
representation these URLs offer.

## CLI

An official, dependency-free CLI ships in the repository at
`tools/china_snapshot_cli.py`. Install by placing it on `PATH`, or run in place:

```bash
python3 tools/china_snapshot_cli.py feeds
python3 tools/china_snapshot_cli.py digest --json
python3 tools/china_snapshot_cli.py packet
CHINA_SNAPSHOT_API_KEY=cs_live_... python3 tools/china_snapshot_cli.py research get_digest '{}'
python3 tools/china_snapshot_cli.py mcp-config
```

Subcommands: `feeds`, `digest`, `packet`, `research <operation> [json]`,
`mcp-config`. Public subcommands need no key; `research` requires
`CHINA_SNAPSHOT_API_KEY` (or `--key`).

## OpenAPI

`GET /openapi.json` is the OpenAPI 3.1 document describing every public
endpoint, the research operations, the MCP transport, authentication, and the
structured error responses. It is generated from the same tool contract the
MCP endpoint advertises (`tools/build_openapi.py`), so the two cannot drift.
Every public feed 200 response carries a schema **inferred from the live feed
at build time** — an exact field inventory with types, refreshed every deploy,
rather than a hand-maintained approximation. The versioning and rate-limit
policy is declared, and the MCP manifest and authenticated-route errors are
described.

## Evidence and honesty contract

Material claims should cite the original evidence URL and timestamp. Generated
narrative and analytical fields are interpretation, not primary evidence.
Chinese source text is translated with DeepSeek; verify consequential claims
against the linked source. Research responses carry honesty fields
(`coverage`, `low_confidence`, `preview`, `belongs_to_current_edition`,
`retained_last_known_good`, and the `limits` thresholds) — respect them, and do
not treat absence from a bounded result as absence of evidence.

## Support

- Developer portal: `https://china-snapshot.com/developers`
- OpenAPI: `https://china-snapshot.com/openapi.json`
- Contact: `contact@china-snapshot.com`
- Pricing: `https://china-snapshot.com/pricing.html`
- Account / keys: `https://china-snapshot.com/account.html`