Data API and agent tools
The public production data is free to read without an API key. The test website remains authenticated and excluded from indexing. All documents are generated offline from the records used by the main website.
Start here
API catalogue
OpenAPI 3.1 specification
Database collections and canonical record index
Canonical records, evidence, and assertions
Linked data (gzip)
GET https://chanceries.org/api/v1/index.json
GET https://chanceries.org/api/v1/people/index.json
GET https://chanceries.org/api/v1/people/pages/0001.json
GET https://chanceries.org/api/v1/people/{recordKey}.jsonCopy a recordKey from the index; do not derive it from a display name. Each collection index provides its dataUrl, recordsKey, count, and fixed page links. Page files contain at most 100 index entries; follow next until null. Unknown record keys and page numbers return not found.
Collections
People are canonical biographies. Appointments are distinct terms or rank phases. Countries include narrative and bilateral records. Properties are the same nonduplicative selection as the property database. Events are the published historical accounts. The source inventory preserves claim contexts, source dates, access dates, and locators without inventing review dates.
Canonical records
Schema 1.0.0 distinguishes person, appointment, polity, place, event, bilateral_relationship, and topic. The five existing collection names and documents remain available. The singular type names select canonical records through the same read tools. An appointment is a compact reference, while article search includes only records with a published narrative or reference article.
The canonical snapshot uses XZ compression and verified references to the existing JSON documents. The supplied Python client resolves those references and verifies the complete reconstructed graph. Each reference names a fixed public document and JSON pointer; it cannot request an arbitrary URL. The index records counts, source ownership, checksums, and the wire format. Preserve the snapshot and its declared dependencies together for an offline copy.
Sources and assertions support the seven record types. An assertion identifies its subject, predicate, target or value, supporting sources, locators, and evidence class. Direct support, interpretation, derivation, and contextual association remain distinct. An event linked as context does not establish personal participation. Contested alternatives retain their own status and provenance.
Search and filtering
This is a static HTTP API, not a query server. Adding ?q= or ?country= does not filter a JSON document. Use the downloadable client or MCP adapter for full-text, country, and service-year filtering, or filter the bulk files in your own software. Search results retain evidence and uncertain date classifications.
Agent tools
Download the main Python client (also download its retrieval module). It uses Python's standard library and offers read-only search, record retrieval, country appointments, and sources. No shell, write, or administrative tool is exposed.
python chanceries_agent.py search "Hu Shih" --country china
python chanceries_agent.py appointments china --year 1938
python chanceries_agent.py search "recognition and representation" --kind topic
python chanceries_agent.py search "Cuba and the United States" --kind bilateral_relationship
python chanceries_agent.py mcpThe adapter is a local stdio MCP server that retrieves this website's public data. A client must explicitly connect it. It is not an anonymously discoverable hosted /mcp service. Use --site-dir with a local site snapshot for offline evaluation. The production host is the default; staging access requires your own authorized authentication and is never embedded in downloads.
Download the retrieval module and canonical record reference module. Keep all three Python files in the same directory. The local adapter also exposes citation-compatible search and fetch tools.
Bulk downloads and consistency
The ZIP includes the five established collections as JSON Lines and CSV, a canonical record index in both formats, and SHA-256 checksums. The typed index points to person and appointment content inside that archive. The canonical additions document contains the new article records and their cited assertions; the canonical snapshot separately supplies the complete assertion graph and source provenance. CSV provides a compact index, while JSON preserves nested evidence. Leading formula characters are escaped for spreadsheet safety. The catalogue includes a dataset digest and ZIP checksum. Retrieve index.json before and after reading several files; retry when its version changes. Historical source releases are preserved separately in the project's release archives.
Dates, limits, and citations
Null values stay unknown. Year-level dates are not days; an unknown departure is not a continuous term. The client bounds results to 100 per call and labels uncertain service overlap. Cite a record's canonicalUrl and retain original source citations. Use the bulk download instead of making thousands of repeated requests. Cross-origin browser access depends on the host's policy; ordinary agent HTTP requests and the supplied client do not require browser CORS.
Evidence and reuse policy
Diplomatic linked-data vocabulary
Coverage
The optional complete linked graph and deduplicated source inventory are gzip downloads. Decompress them before parsing JSON; individual HTML pages retain plain JSON-LD and records retain their original source metadata.