--- title: "Valyzer API & MCP — geopolitical and regulatory events with evidence" description: "Structured, bitemporal geopolitical and regulatory events with the evidence in every field, through a REST API and MCP. Free Sandbox, no card." canonical: https://valyzer.com/for-developers last_updated: 2026-11-03 --- # Valyzer API & MCP — geopolitical and regulatory events with evidence > One API for sanctions, regulatory changes, critical assets and exposure. Every value with its evidence. Page: https://valyzer.com/for-developers ## Your agent sounds sure about a world it can't see. - Models answer sanctions, tariffs and regulation from stale training data, or make it up. - Web search returns headlines, not the official source, the date or what changed. - Building it yourself means watching gazettes, sanctions lists and courts every day, in many languages. ## Same question. An answer you can check. What export controls did China announce in April 2025? - Without Valyzer: My knowledge has a cutoff, so I may be missing recent announcements. China has used export controls before, but I can't confirm what was announced in April 2025. Please check official sources. - With Valyzer: On 4 April 2025, China's Ministry of Commerce (MOFCOM) published new export restrictions. Severity: high. (MOFCOM · 2025-04-04 · fact) Every answer carries its source, its date, and says “no data” instead of guessing. ## Ship the feature, not the pipeline. - **Sanctions alerts inside your procurement tool**: Your users get warned when a supplier is sanctioned. - **Route and port risk in your logistics copilot**: Your users see which ports on their route have active events. - **A regulatory change feed for your compliance agent**: Your users get what changed, with the official source. ## Watching a perimeter Valyzer does not store perimeters for API or MCP users and does not push notifications or webhooks. Your app keeps each user's perimeter and polls. 1. Store each user's perimeter in your app: ISO-2 `country` codes, entity ids (from `search_entities` / `GET /v1/entities`) and event `type` codes. 2. Query `search_events` / `GET /v1/events` with the `country`, `entity` and `type` filters (each repeatable, e.g. `?country=CN&country=TW&entity=&type=`). 3. For incremental checks call `list_event_changes` / `GET /v1/events/changes?since=`. It returns new, corrected and withdrawn events but cannot be filtered by perimeter: keep the items whose event matches the perimeter (fetch it with `get_event` / `GET /v1/events/{id}` when you need its countries or entities), then store `meta.until` as the next `since`. ## Live in your agent in one minute. Hand your coding agent the brief, or add Valyzer to the AI tools you already use. One record, the same evidence gates, the same quota. ### Paste this into your coding agent ```text Add Valyzer to this project. Read https://valyzer.com/for-developers.md and the OpenAPI spec at https://api.valyzer.com/v1/openapi.json. Call the REST API with the X-Api-Key header from the VALYZER_API_KEY env var. Use GET /v1/changes?since=… for incremental sync, and show each claim's evidence (sourceName, publishedAt) wherever the data is displayed. ``` ### MCP client MCP server URL: https://api.valyzer.com/v1/mcp #### claude.ai Works on the web and in the app. 1. Open Settings, then Connectors. 2. Choose Add custom connector. 3. Paste the URL below. 4. Sign in to approve. There is no key to copy. MCP server URL: ``` https://api.valyzer.com/v1/mcp ``` #### ChatGPT Add it as a custom connector in ChatGPT. 1. Open Settings, then Connectors. 2. Choose Add custom connector. 3. Paste the URL below. 4. Sign in to approve. There is no key to copy. MCP server URL: ``` https://api.valyzer.com/v1/mcp ``` #### Claude Desktop No config file needed. 1. Open Settings, then Connectors. 2. Choose Add custom connector. 3. Paste the URL below. 4. Sign in to approve. There is no key to copy. MCP server URL: ``` https://api.valyzer.com/v1/mcp ``` Headless, with an API key: ``` { "mcpServers": { "valyzer": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.valyzer.com/v1/mcp", "--header", "X-Api-Key:${VALYZER_API_KEY}" ], "env": { "VALYZER_API_KEY": "vyz_..." } } } } ``` #### Claude Code Sign in with OAuth the first time you use a Valyzer tool. terminal: ``` claude mcp add --transport http valyzer https://api.valyzer.com/v1/mcp ``` Headless, with an API key: ``` claude mcp add --transport http valyzer https://api.valyzer.com/v1/mcp \ --header "X-Api-Key: vyz_..." ``` #### Cursor One click, then sign in when Cursor asks. ~/.cursor/mcp.json: ``` { "mcpServers": { "valyzer": { "url": "https://api.valyzer.com/v1/mcp" } } } ``` Headless, with an API key: ``` { "mcpServers": { "valyzer": { "url": "https://api.valyzer.com/v1/mcp", "headers": { "X-Api-Key": "${env:VALYZER_API_KEY}" } } } } ``` #### VS Code One click, then sign in when VS Code asks. .vscode/mcp.json: ``` { "servers": { "valyzer": { "type": "http", "url": "https://api.valyzer.com/v1/mcp" } } } ``` Headless, with an API key: ``` { "inputs": [ { "type": "promptString", "id": "valyzer-api-key", "description": "Valyzer API key", "password": true } ], "servers": { "valyzer": { "type": "http", "url": "https://api.valyzer.com/v1/mcp", "headers": { "X-Api-Key": "${input:valyzer-api-key}" } } } } ``` For headless clients and CI, send your API key in the X-Api-Key header. Replace vyz_... with your key. MCP tools: - Search published events - Get one event with evidence - Get an event's revision history - Search entities - Get one entity - Get a country brief - Search the world atlas - List impact changes since a date - List event changes since a date (incremental sync) - List entity changes since a date (incremental sync) ## An answer your agent can cite. Stop at any level. Nothing is a summary: each layer points to the one below. 1. **Source**: Gazette, sanctions list, court or press. Rights-approved. 2. **Evidence**: Exact locator, URL and publication date. 3. **Claim**: Fact or inference. Never mixed. 4. **Event**: Typed, severity-rated, located, linked to entities. 5. **Impact**: Direction, mechanism, horizon and confidence 0–1. Two time axes on every record: `asOf` (when it was true) and `knownAt` (when it was known). Every correction is a new version. Nothing is overwritten. - Facts and inferences are never mixed. - Null where coverage is thin, never a fake zero. - Corrections are new versions you can replay with knownAt. ## Ask it in plain language - **Compliance & KYC**: "Did any supplier on my list get sanctioned today?" (`/v1/changes`, `/v1/entities`, `/v1/events`) - **Supply chain**: "Which ports on my Asia–Europe route have active events?" (`/v1/world/search`, `/v1/world/paths`, `/v1/events`) - **Energy & commodities**: "Which LNG terminals are exposed to EU–Russia tension?" (`/v1/world/tension`, `/v1/world/exposure`, `/v1/world/search`) - **Legal & regulatory**: "What changed in export controls since 1 October, as known then?" (`/v1/events`, `/v1/events/:id/history`, `/v1/changes`) - **Risk & insurance**: "Which countries in my portfolio are most exposed now?" (`/v1/world/exposure`, `/v1/world/tension`, `/v1/entities`) - **Research & media**: "Show every correction to this event and its evidence." (`/v1/events/:id/history`, `/v1/events`, `/v1/entities`) ## Call the REST API from any language. Three requests cover most integrations. Every claim carries its evidence, and every record its two time axes: asOf, when it was true; knownAt, when it was known. ### GET /v1/events Search published events. Filter by type, country, entity and time, now or as known on a past date. ```bash curl -G https://api.valyzer.com/v1/events \ -H "X-Api-Key: $VALYZER_API_KEY" \ -d type=export_restriction -d country=CN \ -d knownAt=2025-04-30T00:00:00Z ``` ```ts const url = new URL("https://api.valyzer.com/v1/events"); url.search = new URLSearchParams({ type: "export_restriction", country: "CN", knownAt: "2025-04-30T00:00:00Z", }).toString(); const res = await fetch(url, { headers: { "X-Api-Key": process.env.VALYZER_API_KEY! }, }); if (!res.ok) throw new Error(`Valyzer ${res.status}`); const { data } = await res.json(); ``` ```python import os import requests res = requests.get( "https://api.valyzer.com/v1/events", headers={"X-Api-Key": os.environ["VALYZER_API_KEY"]}, params={"type": "export_restriction", "country": "CN", "knownAt": "2025-04-30T00:00:00Z"}, ) res.raise_for_status() data = res.json()["data"] ``` Response, abbreviated (200 OK): ```json { "data": [{ "type": "export_restriction", "severity": "high", "occurrence": { "from": "2025-04-04T00:00:00Z" }, "claims": [{ "kind": "fact", "confidence": 0.95, "evidence": [{ "sourceName": "MOFCOM", "publishedAt": "2025-04-04T00:00:00Z" }] }], "impacts": [{ "direction": "negative", "horizon": "short_term", "confidence": 0.6 }], "updatedAt": "2025-04-07T09:12:00Z" }] } ``` ### GET /v1/changes Sync what changed since a date. Poll with since to get impacts that became known or were corrected. Nothing is overwritten, so your copy never drifts. ```bash curl -G https://api.valyzer.com/v1/changes \ -H "X-Api-Key: $VALYZER_API_KEY" \ -d since=2025-04-01T00:00:00Z ``` ```ts const url = new URL("https://api.valyzer.com/v1/changes"); url.search = new URLSearchParams({ since: "2025-04-01T00:00:00Z", }).toString(); const res = await fetch(url, { headers: { "X-Api-Key": process.env.VALYZER_API_KEY! }, }); if (!res.ok) throw new Error(`Valyzer ${res.status}`); const { data } = await res.json(); ``` ```python import os import requests res = requests.get( "https://api.valyzer.com/v1/changes", headers={"X-Api-Key": os.environ["VALYZER_API_KEY"]}, params={"since": "2025-04-01T00:00:00Z"}, ) res.raise_for_status() data = res.json()["data"] ``` Response, abbreviated (200 OK): ```json { "data": [{ "kind": "added", "changedAt": "2025-04-07T09:12:00Z", "impact": { "direction": "negative", "confidence": 0.6 } }], "meta": { "since": "2025-04-01T00:00:00Z", "until": "…" } } ``` ### GET /v1/world/exposure Exposure by country, gaps stated. A 0–100 score per country, or null where coverage is too thin. An unanswered question is never shown as a safe one. ```bash curl https://api.valyzer.com/v1/world/exposure \ -H "X-Api-Key: $VALYZER_API_KEY" ``` ```ts const url = new URL("https://api.valyzer.com/v1/world/exposure"); const res = await fetch(url, { headers: { "X-Api-Key": process.env.VALYZER_API_KEY! }, }); if (!res.ok) throw new Error(`Valyzer ${res.status}`); const { data } = await res.json(); ``` ```python import os import requests res = requests.get( "https://api.valyzer.com/v1/world/exposure", headers={"X-Api-Key": os.environ["VALYZER_API_KEY"]}, ) res.raise_for_status() data = res.json()["data"] ``` Response, abbreviated (200 OK): ```json { "data": { "version": "geoexposure-v1", "calculatedAt": "…", "values": { "": 0–100 | null }, "quality": { "": "complete" | "partial" | "stale" } } } ``` ### Main endpoints - `GET /v1/events`: Published events, filtered by type, country, entity and time - `GET /v1/events/:id`: One event with claims, evidence, entities and impacts - `GET /v1/changes`: What changed since a timestamp, for polling and sync - `GET /v1/entities/:id`: Entity profile, current and historical - `GET /v1/world/exposure`: Exposure of countries, assets and routes - `GET /v1/world/tension`: Bilateral tension, comparable over time ### From sign-up to first call in two minutes. 1. **Create an account**: Email only. Starts on Sandbox. 2. **Create a key**: In the console. Shown once. 3. **Call /v1**: Send it in the X-Api-Key header. X-Api-Key keys you create and revoke in your console. Over quota the API answers 429, never a surprise bill. ## Built to be read by agents. Every entry point is machine-readable, so an agent can find the spec, learn the contract and call the API without a human in the loop. ### Machine-readable resources - llms.txt: https://valyzer.com/llms.txt (Index of the site for LLMs) - llms-full.txt: https://valyzer.com/llms-full.txt (Offers, pricing and FAQ in one document) - This page as Markdown: https://valyzer.com/for-developers.md (The same copy and snippets, no HTML) - OpenAPI 3.1: https://api.valyzer.com/v1/openapi.json (The full spec, importable anywhere) - MCP endpoint: https://api.valyzer.com/v1/mcp (OAuth 2.1 or API key) - Interactive docs: https://api.valyzer.com/v1/docs (Try every endpoint in the browser) ### The contract - `QUOTA_EXCEEDED · RATE_LIMITED`: 429 with a Retry-After header. Over quota, never a surprise bill. - `PLAN_HISTORY_LIMIT`: 403 when asOf, knownAt or since is older than your plan's history window. - `X-Valyzer-History-Days`: Response header with your plan's history window. - `X-Valyzer-Page-Limit`: Response header with the page size applied to your call. - `REST · MCP`: One record, the same evidence gates, the same quota. ## Start free. Upgrade in one click. Sandbox is free forever. Developer is a flat €99 a month, cancel any time. No overage. ### Sandbox €0 free forever · no card. 1,000 calls / month · 10 req/min. - Same published data and evidence - Last 30 days of history · 20 records per call - asOf / knownAt inside that window - Up to 2 API keys ### Developer €99 / month · or €990 / year (2 months free). 25,000 calls / month · 120 req/min. - Everything in Sandbox - 12 months of history · 100 records per call - Bulk export (JSON / CSV / GeoJSON) - Up to 10 API keys, usage in your console - Invoices with VAT and tax ID · email support ### Enterprise Custom annual agreement. From 1,000,000 calls / month · 600 req/min. - Full history · 100 records per call - SLA and declared redistribution rights - Your own perimeter in a private workspace - Frozen reports and custom integrations Sandbox and Developer: Every published event, claim and source; World layers, exposure, tension and search; Revision history within your plan's window. Enterprise only: Client perimeters: suppliers, sites, dependencies; Workspace alerts and frozen reports; Human analysis and custom sources. A call is one authenticated request to /v1. Quotas are per account and reset on the 1st of each month (UTC). Prices exclude VAT. ## Technical questions. **Where does the data come from?** Official gazettes, sanctions lists, courts, open datasets and press. A source only reaches the API after its rights and provenance are approved, and every claim links back to it. **What happens when a fact is corrected?** Nothing is overwritten. The old version is closed and a new one recorded, so you can query the current truth or replay what the API returned on a past date with knownAt. **How do I connect claude.ai or ChatGPT?** Add a custom connector, paste https://api.valyzer.com/v1/mcp and sign in to approve. There is no key to copy: approving creates a connection that runs on your plan's quota and limits, and it does not count toward your API key limit. You can disconnect it from your console. **What happens if I exceed my quota?** The API answers 429 (QUOTA_EXCEEDED or RATE_LIMITED) with a Retry-After header. There is no overage billing: upgrade to Developer, or talk to us about Enterprise. **Can I show Valyzer data to my own customers?** Yes, inside your product, with the source attribution included in each response. Bulk redistribution or resale requires an Enterprise agreement. **How do payment and cancellation work?** Developer is paid by card through Stripe, with VAT and an invoice with your tax ID. Change the card, switch monthly/yearly or cancel from the billing portal in your console; you keep the plan until the end of the paid period. **How much history and how many records per call does each plan include?** Sandbox reads the last 30 days with up to 20 records per call; Developer reads the last 12 months with up to 100; Enterprise has full history. A larger limit is clamped to your plan's page size (see the X-Valyzer-Page-Limit header). An asOf, knownAt or since older than your window, or a single record outside it, answers 403 PLAN_HISTORY_LIMIT. X-Valyzer-History-Days shows your window.