Developers

Query China records. Build your own export.

The public datasets API gives your scripts and agents the records available in the browser. Filter by date, publisher and title, follow result pages, and preserve the sources behind your work.

Open the OpenAPI spec Read llms.txt

Public data and member research

Choose the right way in.

Explore data and the public datasets API need no account. The research examples include sources, calculations and evidence downloads. The research API and MCP tools require Professional access; the public datasets API does not change those entitlements.

Public datasets and feeds

Filter retained records at /api/datasets and export pages as CSV or JSON. Current feeds are listed in /data/endpoints.json. No key required.

Read public records →

Research REST API

Five Professional operations for the brief, document search, entity timelines and signal packets. Requires member authorization; monthly request caps apply.

Read research discovery →

MCP endpoint

Streamable HTTP at /api/mcp exposes the five research operations as tools. Tool listing and calls require Professional MCP access.

Read MCP discovery →

Official CLI

A dependency-free CLI ships in the repo: feeds, digest, packet, research, mcp-config. Public subcommands need no key.

Read the CLI guide →

Public topic reference

Use the same readings and evidence as the website.

Start at /data/topics/index.json. Follow a topic to its current reading, available history and original citations. Each revision links to HTML, JSON and Markdown; no key is required. Reading dates describe changes to our analysis. Connections count shared citations. Keep the coverage notes and interpretation labels in your own work.

Explore topics →

Public datasets API

Filter records and request the next page.

GET /api/datasets returns document metadata by default, with 50 rows per page. Choose dataset=documents, social or indicators. No key is required. The limit is 60 requests per minute per IP and 100 rows per page. Results and continuation headers are accessible through CORS.

Filters and columns

q matches a literal substring in titles and publisher labels; it does not search document bodies. Use source for an exact publisher label, ignoring case. Both accept up to 180 printable characters. Set fields to comma-separated field keys and limit to 1–100. The response lists the available fields and source labels.

Use text=available with the documents dataset to find approved original-language extractions. For record detail, send a returned id with its dataset and no filters or cursor.

Dates and repeated observations

from and to are inclusive UTC dates in YYYY-MM-DD format. They filter first collection for documents, observed time for social rows, and collection time for indicators. Publication dates and reference periods are separate fields and can be unknown.

Repeated rows can refer to the same hot-list story or economic release. They do not count distinct posts or new events. Read coverage.notes; keep missing values as unknown. Heat scores are not comparable across platforms, and WeChat heat is unavailable.

One page per export

JSON returns items, row_count, next_cursor and as_of, plus coverage and field information. The row count covers this page. Repeat the same dataset and filters with the opaque cursor until it is null. Cursors expire after 24 hours and exclude later inserts; existing document edits can still appear.

Set format=csv to download the page. Read X-Dataset-Next-Cursor, X-Dataset-Row-Count and X-Dataset-Export-Scope from the headers. An empty cursor marks the end. Follow successive pages to build a larger export; one call does not download every matching row.

Original text and its source

Document detail adds original_text, text_truncated and rights_basis_url. Text is available only for an exact extraction approved for public release. text_status distinguishes available, source_only and not_extracted. Use the original publisher link when text is unavailable.

Responses contain up to 120,000 characters of the extraction and flag truncation. They do not certify a complete document or provide full-document translations. Preserve source and date attribution, and check the public dataset terms. Display permission does not grant rights to republish third-party text.

Dataset errors use {"error":"message"}. Invalid parameters or an expired cursor return 400; missing record detail returns 404; temporary failures return 503. A 429 response includes Retry-After. Read the full API guide for field definitions, response metadata and continuation rules.

Machine-accessible files

Find the supported interfaces.

Start with llms.txt or the Markdown guide. The feed catalog and OpenAPI document describe the supported endpoints and access requirements.

/data/topics/index.json
Public topics and shared citations; dated readings and their Markdown/JSON exports.
/api/datasets
Public record pages, filters, CSV/JSON exports and document detail.
/llms.txt
The agent front door: public topics, evidence, datasets and research access.
/agents.txt
Concise agent instructions and entry points.
/developers.md
This guide, as Markdown (Accept: text/markdown).
/openapi.json
The complete OpenAPI 3.1 API description.
/data/endpoints.json
Self-describing catalog of every public feed, with access markers.
/data/daily_digest.json
The current cross-source synthesis, structured.
/data/digest.md
The current briefing as Markdown.
/data/baselines.json
30/90-day archive baselines plus ranked deviations.
/data/signal-packet.json
The current validated public Signal Packet.
/data/forecasts/track_record.json
The Forecast Desk track record, in full.

Quick start

Start with a public query.

Read public document records

curl --get https://china-snapshot.com/api/datasets \
  --data-urlencode 'dataset=documents' \
  --data-urlencode 'q=property' \
  --data-urlencode 'limit=100'

Export a page as CSV

curl --get https://china-snapshot.com/api/datasets \
  --data-urlencode 'dataset=documents' \
  --data-urlencode 'text=available' \
  --data-urlencode 'format=csv' \
  --dump-header headers.txt --output documents-page.csv

Search member research

curl -X POST https://china-snapshot.com/api/research \
  -H "Authorization: Bearer cs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"operation":"search_stories",
       "arguments":{"query":"export controls"}}'

Connect an MCP client (Professional)

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

Professional authentication and limits

Member research access is separate.

Authorize research and MCP calls

Send Authorization: Bearer <session JWT> or Bearer cs_live_<API key>. An X-Api-Key header is never read. Research and MCP callers must hold the matching entitlement (api_access or mcp_access).

Hard monthly cap, no overage

Professional allows 5,000 combined API + MCP requests per calendar month. Over-cap calls return 429 with Retry-After and X-RateLimit-* headers, and no overage is ever charged.

Search the China Snapshot archive