Public HTTP API, generated from the same contracts the API validates against.
Machine-readable version at /v1/openapi.json.
MCP (Model Context Protocol)
Let an AI agent query Valyzer directly. The endpoint is
POST https://api.valyzer.com/v1/mcp: Streamable HTTP, JSON-RPC 2.0, authenticated with
OAuth 2.1 (for clients that sign in on a person's behalf) or with the same API key as the REST
API (X-Api-Key or Authorization: Bearer).
- Stateless. No sessions: every request stands alone, and
GET
and DELETE answer 405.
- Read-only tools. Protocol messages (
initialize,
tools/list) are free. Each tools/call runs as one ordinary
/v1 request with your key, so it counts as one call against your plan's quota and
per-minute limit and returns the same data.
- Errors are tool results. Quota and rate-limit refusals come back as a result
with
isError: true and a message naming the code, not as an HTTP error.
Authentication
- OAuth 2.1 (recommended for chat apps and IDEs). Add the URL as a custom
connector or server and sign in to Valyzer to approve; no key to copy. Protected resource
metadata is at
/.well-known/oauth-protected-resource/v1/mcp and authorization
server metadata at /.well-known/oauth-authorization-server. Scopes are
mcp:read and offline_access (refresh token); PKCE
(S256) is required. Clients register through dynamic client registration or
identify themselves with a Client ID Metadata Document. Consent happens at valyzer.com.
- API key. For your own code and clients that can send a header, use
X-Api-Key or Authorization: Bearer vyz_....
- Quota and revocation. OAuth connections run on your plan's quota and
limits and do not count toward the API key limit. Disconnect one any time under
Connected apps in valyzer.com/developers; its tokens stop working immediately.
Connect a client
claude.ai, Claude Desktop and ChatGPT. Add a custom connector (MCP) with the
URL https://api.valyzer.com/v1/mcp, then sign in to Valyzer and approve. No key and no
config file are needed.
The snippets below send an API key. Keep the key out of files you commit: export it as
VALYZER_API_KEY where the client supports variable expansion. With OAuth, omit the
header and authenticate from the client.
Claude Code
OAuth: add the URL, then run /mcp and choose Authenticate.
claude mcp add --transport http valyzer https://api.valyzer.com/v1/mcp
Or with an API key:
claude mcp add --transport http valyzer https://api.valyzer.com/v1/mcp --header "X-Api-Key: vyz_..."
Or share it with the team in the project's .mcp.json:
{
"mcpServers": {
"valyzer": {
"type": "http",
"url": "https://api.valyzer.com/v1/mcp",
"headers": {
"X-Api-Key": "${VALYZER_API_KEY}"
}
}
}
}
Cursor
~/.cursor/mcp.json. For OAuth, set only url and sign in when Cursor asks; the headers entry below is the API key variant:
{
"mcpServers": {
"valyzer": {
"url": "https://api.valyzer.com/v1/mcp",
"headers": {
"X-Api-Key": "${env:VALYZER_API_KEY}"
}
}
}
}
VS Code
.vscode/mcp.json. For OAuth, set only type and url and sign in when VS Code asks. The API key variant below prompts for the key once and stores it securely:
{
"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}"
}
}
}
}
Claude Desktop
Use Settings, Connectors and add a custom connector with the URL (OAuth). To use an API key
instead, edit claude_desktop_config.json and go through the
mcp-remote bridge (requires Node.js):
{
"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_..."
}
}
}
}
Raw HTTP
Any HTTP client works. Send both Content-Type: application/json and
Accept: application/json, text/event-stream. The response arrives as a single
server-sent event (one data: {...} line) or as plain JSON.
curl -X POST \
-H "X-Api-Key: $VALYZER_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}' \
"https://api.valyzer.com/v1/mcp"
curl -X POST \
-H "X-Api-Key: $VALYZER_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_events","arguments":{"country":["CN"],"type":["export_restriction"],"limit":5}}}' \
"https://api.valyzer.com/v1/mcp"
The tool result's structuredContent holds the same body the matching REST route
returns ({ data, page } for lists); content[0].text is that body as JSON
text. Call tools/list to get the same tool definitions as JSON Schema.
Tools
Ten tools, all read-only. Arguments are sent as a JSON object under
params.arguments; array arguments take JSON arrays (for example
"country": ["CN", "US"]).
search_events
List published Valyzer events filtered by type, country, severity, entity and dates. Returns summaries only (title, summary, type, severity, dates, locations); the claims, relationships, impacts and evidence arrays are empty in list results. Call get_event with an event id for the full claims and evidence. Paginate with cursor.
type array of "export_restriction" | "sanction" | "trade_restriction" | "armed_clash" | "military_attack" | "ceasefire" | "diplomatic_action" | "cyber_operation" | "supply_disruption" | "infrastructure_disruption" | "regulatory_change" optional
country array of string optional — ISO-3166 alpha-2 codes, e.g. ['CN','US'].
severity array of "low" | "medium" | "high" | "critical" optional
status array of "draft" | "processing" | "ready" | "needs_review" | "published" | "rejected" | "failed" | "archived" optional
entity array of string (uuid) optional — Entity ids from search_entities.
occurredFrom string (ISO 8601 date-time) optional — ISO-8601 instant, e.g. 2025-04-30T00:00:00Z
occurredTo string (ISO 8601 date-time) optional — ISO-8601 instant, e.g. 2025-04-30T00:00:00Z
asOf string (ISO 8601 date-time) optional — Valid time: answer as the world was at this instant. ISO-8601, e.g. 2025-04-30T00:00:00Z.
knownAt string (ISO 8601 date-time) optional — Recorded time: answer with only what Valyzer had published by this instant (no hindsight). ISO-8601.
sort "occurred" | "importance" optional — occurred (newest first, default) or importance.
locale "en" | "es" optional — Language for titles and summaries (default en).
limit integer (1-100) optional — Page size, 1-100 (default 20).
cursor string optional — Opaque cursor from a previous page's page.nextCursor.
get_event
Fetch one published event with its claims, evidence excerpts, sources, entities and impacts. Use asOf/knownAt to read a past version.
id string (uuid) required
asOf string (ISO 8601 date-time) optional — Valid time: answer as the world was at this instant. ISO-8601, e.g. 2025-04-30T00:00:00Z.
knownAt string (ISO 8601 date-time) optional — Recorded time: answer with only what Valyzer had published by this instant (no hindsight). ISO-8601.
locale "en" | "es" optional — Language for titles and summaries (default en).
get_event_history
List the publications and corrections of one event, with reasons and recorded times. Shows how the published record changed without rewriting history.
id string (uuid) required
limit integer (1-100) optional — Page size, 1-100 (default 20).
cursor string optional — Opaque cursor from a previous page's page.nextCursor.
search_entities
Find countries, companies, people, organisations, sectors, commodities and regulations by name or kind. Optionally restrict to entities that currently hold a published state, such as politics.head_of_state (countries with a published head of state). Sanctions are stored as relationships, not states, so they cannot be filtered here.
query string optional
kind array of "country" | "region" | "company" | "sector" | "industry" | "commodity" | "resource" | "infrastructure" | "trade_route" | "regulation" | "government" | "organization" | "person" | "political_party" | "service" optional
statePredicate string optional — Namespaced state predicate, e.g. politics.head_of_state or politics.head_of_government.
stateValue string optional
asOf string (ISO 8601 date-time) optional — Valid time: answer as the world was at this instant. ISO-8601, e.g. 2025-04-30T00:00:00Z.
knownAt string (ISO 8601 date-time) optional — Recorded time: answer with only what Valyzer had published by this instant (no hindsight). ISO-8601.
limit integer (1-100) optional — Page size, 1-100 (default 20).
cursor string optional — Opaque cursor from a previous page's page.nextCursor.
get_entity
Fetch one entity with its aliases, identifiers, relationships and current states.
id string (uuid) required
asOf string (ISO 8601 date-time) optional — Valid time: answer as the world was at this instant. ISO-8601, e.g. 2025-04-30T00:00:00Z.
knownAt string (ISO 8601 date-time) optional — Recorded time: answer with only what Valyzer had published by this instant (no hindsight). ISO-8601.
get_country
Country profile: government, recent published events, tensions and key assets. asOf answers the government and tension blocks at a past date.
iso2 string required — ISO-3166 alpha-2 code, e.g. ES.
asOf string (ISO 8601 date-time) optional — Valid time: answer as the world was at this instant. ISO-8601, e.g. 2025-04-30T00:00:00Z.
knownAt string (ISO 8601 date-time) optional — Recorded time: answer with only what Valyzer had published by this instant (no hindsight). ISO-8601.
search_world
Free-text name search across the world atlas: assets (ports, plants, LNG terminals, airports), places, actors and published events (kinds: asset, geo, event, or an entity kind).
q string required
kinds array of string optional — Restrict to these object kinds.
country string optional
asOf string (ISO 8601 date-time) optional — Valid time: answer as the world was at this instant. ISO-8601, e.g. 2025-04-30T00:00:00Z.
knownAt string (ISO 8601 date-time) optional — Recorded time: answer with only what Valyzer had published by this instant (no hindsight). ISO-8601.
limit integer (1-100) optional — Page size, 1-100 (default 20).
cursor string optional — Opaque cursor from a previous page's page.nextCursor.
list_impact_changes
Impacts that were published, corrected or retracted between since and until (default now). Use it to sync or to answer 'what changed since X'.
since string (ISO 8601 date-time) required — ISO-8601 instant, e.g. 2025-04-30T00:00:00Z
until string (ISO 8601 date-time) optional — ISO-8601 instant, e.g. 2025-04-30T00:00:00Z
limit integer (1-100) optional — Page size, 1-100 (default 20).
cursor string optional — Opaque cursor from a previous page's page.nextCursor.
list_event_changes
Public events that became new, corrected or withdrawn between since and until (default now) -- what changed in what we publicly know, not what happened. Each item carries a historyUrl pointing at that event's full revision history. Use it to sync a local copy incrementally.
since string (ISO 8601 date-time) required — ISO-8601 instant, e.g. 2025-04-30T00:00:00Z
until string (ISO 8601 date-time) optional — ISO-8601 instant, e.g. 2025-04-30T00:00:00Z
limit integer (1-100) optional — Page size, 1-100 (default 20).
cursor string optional — Opaque cursor from a previous page's page.nextCursor.
list_entity_changes
Public entities that became new, corrected or withdrawn between since and until (default now). Use it to sync a local copy of the entity graph incrementally.
since string (ISO 8601 date-time) required — ISO-8601 instant, e.g. 2025-04-30T00:00:00Z
until string (ISO 8601 date-time) optional — ISO-8601 instant, e.g. 2025-04-30T00:00:00Z
limit integer (1-100) optional — Page size, 1-100 (default 20).
cursor string optional — Opaque cursor from a previous page's page.nextCursor.
Map & World
GET/v1/map/events
The same event filters as `/v1/events`, scoped to a `west,south,east,north` viewport.
Parameters
limit integer optional
sort "occurred" | "importance" optional
locale "es" | "en" optional
type "export_restriction" | "sanction" | "trade_restriction" | "armed_clash" | "military_attack" | "ceasefire" | "diplomatic_action" | "cyber_operation" | "supply_disruption" | "infrastructure_disruption" | "regulatory_change" | "export_restriction" | "sanction" | "trade_restriction" | "armed_clash" | "military_attack" | "ceasefire" | "diplomatic_action" | "cyber_operation" | "supply_disruption" | "infrastructure_disruption" | "regulatory_change"[] optional
severity "low" | "medium" | "high" | "critical" | "low" | "medium" | "high" | "critical"[] optional
status "draft" | "processing" | "ready" | "needs_review" | "published" | "rejected" | "failed" | "archived" | "draft" | "processing" | "ready" | "needs_review" | "published" | "rejected" | "failed" | "archived"[] optional
entity uuid | uuid[] optional
country string | string[] optional
occurredFrom ISO 8601 date-time optional
occurredTo ISO 8601 date-time optional
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
west number required
south number required
east number required
north number required
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 A page of events.
data object[] required
id uuid required
type "export_restriction" | "sanction" | "trade_restriction" | "armed_clash" | "military_attack" | "ceasefire" | "diplomatic_action" | "cyber_operation" | "supply_disruption" | "infrastructure_disruption" | "regulatory_change" required
family "conflict" | "economic" | "political" | "infrastructure" required
typeCode string required
severity "low" | "medium" | "high" | "critical" required
title string required
occurrence object required
locations object[] required
confidence number | null required
verificationStatus "provisional" | "verified" required
verificationMethod "human" | "automated" | "hybrid" required
qualityStatus "clear" | "warning" | "disputed" required
page object required
nextCursor string | null required
hasMore boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/map/events?west=1&south=1&east=1&north=1"
GET/v1/world/features
Composite layer (`events`, `situations`, `countries`) for one viewport and zoom level. Area layers answer on valid time (`asOf`) so the map can reconstruct a past date.
Parameters
bbox string required
zoom number optional
layers string optional
locale "es" | "en" optional
types string optional
severity string optional
situation string optional
resource "oil" | "natural_gas" | "coal" | "uranium" | "wheat" | "maize" | "nitrogen_fertilizer" | "phosphate_fertilizer" | "potash" | "lithium" | "cobalt" | "rare_earths" | "graphite" | "nickel" | "copper" | "manganese" | "platinum" | "palladium" | "tungsten" | "bauxite" optional
verification "provisional" | "verified" optional
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
occurredFrom ISO 8601 date-time optional
occurredTo ISO 8601 date-time optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 A GeoJSON FeatureCollection.
type "FeatureCollection" required
features object[] required
type "Feature" required
id string | number optional
geometry object required
properties object required
meta object required
generatedAt ISO 8601 date-time required
asOf ISO 8601 date-time | null required
knownAt ISO 8601 date-time required
cluster boolean required
nextCursor string | null required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/features?bbox=string"
GET/v1/world/annual
Without `layer`, returns the catalogue of published annual series. With `layer`, returns the full `from..to` window in one payload so the client can scrub years without one request per year. Optional `knownAt` selects the recorded-time cut; absent, the series is current knowledge.
Parameters
layer string optional
from integer optional
to integer optional
locale "es" | "en" optional
knownAt ISO 8601 date-time optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Catalogue or series, depending on `layer`.
data object[] required
layer string required
family string required
metric "reserves" | "production" | "consumption" | "imports" | "exports" | "dependency" | "bilateral_flow" | null required
name object required
unit string required
direction "higher_is_worse" | "higher_is_better" | null required
from integer | null required
to integer | null required
countries integer required
page object required
nextCursor string | null required
hasMore boolean required
404 No such annual layer is published.
Error envelope — see Errors.
503 The world reader is not configured.
Error envelope — see Errors.
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/annual"
GET/v1/world/exposure
Public choropleth layer; `data` is null when no score has ever been calculated.
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Exposure scores.
data object | null required
version "geoexposure-v1" required
calculatedAt ISO 8601 date-time required
values object required
quality object required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/exposure"
GET/v1/world/tension
Public. The current reading plus annual history; 100 is the documented great-power total-war reference. `data` is null when nothing has been computed yet.
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 World tension readings.
data object | null required
version "world-tension-v1" required
calculatedAt ISO 8601 date-time required
current object | null required
history object[] required
thresholds object required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/tension"
GET/v1/world/tension/pairs
Public. `from` is the emitter side of the published relation edges behind the score, `to` the counterpart. `data` is null when no score has been computed for the pair — never a synthetic zero.
Parameters
from string required
to string required
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Bilateral tension reading, or null when not computed.
data object | null required
version "country-pair-tension-v1" required
fromIso2 string required
toIso2 string required
score number | null required
dimensions object required
coverage object required
reducedTo string[] required
quality "complete" | "partial" required
calculatedAt ISO 8601 date-time required
400 from and to are not two distinct ISO-2 codes.
Error envelope — see Errors.
503 The world reader is not configured.
Error envelope — see Errors.
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/tension/pairs?from=string&to=string"
GET/v1/world/countries/:iso2
Public country projection: gauges, problems, resource trends, optional geometry.
Parameters
geometry "true" | "false" optional — Include country boundary geometry when `true`.
asOf string optional — Valid-time instant for the government/tensions blocks (the single world clock).
knownAt string optional — Knowledge-time instant. Today only the State-based `brief.government` block is scoped by it.
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 The country brief.
data object required
iso2 string required
context object | null optional
situation object | null required
region object | null required
name object required
geometry object | null required
resources object[] required
exposure object | null required
brief object required
government object | null required
tensions object[] | null required
relations object[] | null required
pairTensions object[] | null required
503 The world reader is not configured.
Error envelope — see Errors.
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/countries/string"
GET/v1/world/regions/:code
Model-prepared region situation brief (Valyzer AI analyst team) and the member countries with their current brief headline, for the /countries index. Pilot: europe.
Parameters
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 The region.
data object required
code "europe" required
name object required
brief object | null required
members object[] required
404 Unknown region.
Error envelope — see Errors.
503 The world reader is not configured.
Error envelope — see Errors.
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/regions/string"
GET/v1/world/situations/:slug
Public situation (armed conflict, sanctions regime, ...) projection. Some fields (or the whole record, for pilot situations awaiting backfill) require authentication.
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 The situation.
data object required
id uuid required
slug string required
type "armed_conflict" | "geopolitical_confrontation" | "crisis" | "sanctions_regime" required
name object required
summary object required
status "active" | "inactive" | "resolved" required
severity "low" | "medium" | "high" | "critical" required
confidence number | null required
verificationStatus "provisional" | "verified" required
verificationMethod "human" | "automated" | "hybrid" required
validFrom ISO 8601 date-time required
validTo ISO 8601 date-time | null required
geometry object | null required
participants object[] required
eventIds uuid[] required
evidenceIds uuid[] required
fatalities integer | null required
source object | null required
404 Situation not found (or requires authentication).
Error envelope — see Errors.
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/situations/:slug"
GET/v1/world/export
Deprecated alias of `GET /v1/export?dataset=events&country=ISO2`: one metered export page (up to 500 rows, 10 calls of quota, daily cap), inside the plan history window. `scope=country&id=ISO2`, as JSON or CSV; the JSON body adds `page`.
Parameters
scope "country" required — Only `country` is supported today.
id string required — ISO 3166-1 alpha-2 country code.
format "json" | "csv" optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Events for the country, as JSON or a CSV attachment.
data object[] required
source object | null optional
excerpt string | null optional
id uuid required
type "export_restriction" | "sanction" | "trade_restriction" | "armed_clash" | "military_attack" | "ceasefire" | "diplomatic_action" | "cyber_operation" | "supply_disruption" | "infrastructure_disruption" | "regulatory_change" required
family "conflict" | "economic" | "political" | "infrastructure" required
typeCode string required
status "published" required
severity "low" | "medium" | "high" | "critical" required
title string required
summary string required
occurrence object required
locations object[] required
confidence number | null required
verificationStatus "provisional" | "verified" required
verificationMethod "human" | "automated" | "hybrid" required
qualityStatus "clear" | "warning" | "disputed" required
entities object[] required
claims object[] required
relationships object[] required
impacts object[] required
claimCount integer optional
entityCount integer optional
evidenceCount integer optional
updatedAt ISO 8601 date-time required
page object required
nextCursor string | null required
hasMore boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/export?scope=country&id=string"
GET/v1/export
Developer and Enterprise only (Sandbox answers `403 API_TIER_REQUIRED`). One request is one page of up to 500 rows and costs 10 calls of the monthly quota; follow `X-Valyzer-Export-Next-Cursor` (also sent as a `Link: rel=next`) for the next page. An account may fetch 40 pages per UTC day on Developer (1000 on Enterprise) and 6 per minute: beyond that the API answers `429 EXPORT_DAILY_LIMIT` / `EXPORT_RATE_LIMITED` without spending quota. Rows are the public published records, inside the plan's history window (`since` is clamped to it for events). `format=geojson` is events only and omits events without a coordinate.
Parameters
dataset "events" | "entities" optional
format "ndjson" | "csv" | "geojson" optional
country string optional
since ISO 8601 date-time optional
until ISO 8601 date-time optional
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
cursor string optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 One page: NDJSON (one record per line), CSV with a header row, or a GeoJSON FeatureCollection.
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/export"
GET/v1/world/layers
DAT-02 layer definitions and catalogue snapshot.
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Layer catalogue envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/layers"
GET/v1/world/viewport
NET-02 viewport query with layerStates and pagination.
Parameters
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
bbox string required
zoom number optional
layers string required
filters string optional
snapshotId uuid optional
live "1" | "true" optional
cursor string optional
limit integer optional
locale "es" | "en" optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Viewport envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
409 Cursor belongs to another query.
Error envelope — see Errors.
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/viewport?bbox=string&layers=string"
GET/v1/world/search
Full-text search over published geographies, assets, and entities.
Parameters
cursor string optional
limit integer optional
q string required
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
kinds string optional
country string optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Search results envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/search?q=string"
GET/v1/world/changes
Grouped world changes by decision within a bounded time window.
Parameters
changeClock "valid" | "known" optional
changeFrom ISO 8601 date-time required
changeTo ISO 8601 date-time required
scope "selection" | "viewport" | "global" optional
cursor string optional
limit integer optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Grouped world changes.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/changes?changeFrom=2026-01-15T00%3A00%3A00Z&changeTo=2026-01-15T00%3A00%3A00Z"
GET/v1/world/clusters/:key/members
Expand a viewport cluster key into its authorized member features.
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Cluster members envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/clusters/:key/members"
GET/v1/world/geographies/:id
Geography unit with ancestors, paginated children, and geometry version.
Parameters
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Geography envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/geographies/:id"
GET/v1/world/observations
DAT-03 observations projected from statistical and object sources.
Parameters
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
metric string required
geoIds string required
from ISO 8601 date-time required
to ISO 8601 date-time required
cursor string optional
limit integer optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Observations envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/observations?metric=string&geoIds=string&from=2026-01-15T00%3A00%3A00Z&to=2026-01-15T00%3A00%3A00Z"
GET/v1/world/objects/:kind/:id
Detail for event, asset, connection, or entity world objects.
Parameters
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Object envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/objects/:kind/:id"
GET/v1/world/objects/:kind/:id/observations
Metric observations attached to a specific world object.
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Object observations envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/objects/:kind/:id/observations"
GET/v1/world/objects/:kind/:id/explanations
Paginated public impact explanation summaries for a world object.
Parameters
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Explanation page.
data object required
impactId uuid required
impactVersionId uuid required
status "current" | "needs_review" | "withdrawn" | "legacy_untracked" required
method object | null required
explanation string | null required
premises object[] required
completeness "complete" | "restricted" | "legacy" required
meta object required
asOf ISO 8601 date-time required
knownAt ISO 8601 date-time required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/objects/:kind/:id/explanations"
GET/v1/world/relations
Actor relations and connected nodes up to depth 2.
Parameters
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Relations envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/relations"
GET/v1/world/actors/:id
Published actor projection with typed relations.
Parameters
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Actor envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/actors/:id"
GET/v1/world/territorial-assertions
Published territorial assertions with temporal filters.
Parameters
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Assertions envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/territorial-assertions"
GET/v1/world/paths
Bounded multi-hop path search over published network edges.
Parameters
from uuid required
to uuid required
mode string optional
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
snapshotId uuid optional
cursor string optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Path results envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/paths?from=11111111-1111-4111-8111-111111111111&to=11111111-1111-4111-8111-111111111111"
GET/v1/world/metrics
Published world metric definitions and comparability metadata.
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Metrics envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/metrics"
GET/v1/world/raster-sample
Nearest-cell raster value for a layer revision and period.
Parameters
layer string required
revision uuid required
period string required
lon number required
lat number required
knownAt ISO 8601 date-time optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Raster sample envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/raster-sample?layer=string&revision=11111111-1111-4111-8111-111111111111&period=string&lon=1&lat=1"
GET/v1/world/intersections
Spatial coincidence query with explicit non-causation disclaimer.
Parameters
asOf ISO 8601 date-time optional
knownAt ISO 8601 date-time optional
Responses
401 No API key was sent (`LOGIN_REQUIRED`), or the supplied key is malformed/unknown (`API_KEY_INVALID`) or revoked (`API_KEY_REVOKED`).
Error envelope — see Errors.
403 The resolved API tier does not permit this operation (`API_TIER_REQUIRED`), e.g. export requires a Developer or Enterprise tier. API-key requests also get `PLAN_HISTORY_LIMIT` when an explicit time parameter (`asOf`, `knownAt`, `since`, `occurredFrom`, ...) or a single record lies outside the plan's history window.
Error envelope — see Errors.
429 The caller's rate-limit class was exceeded (`RATE_LIMITED`), or an API key's monthly plan quota was exceeded (`QUOTA_EXCEEDED`, with `retry-after`).
Error envelope — see Errors.
200 Intersections envelope.
data any required
snapshotId uuid required
resolvedAsOf ISO 8601 date-time | null required
resolvedKnownAt ISO 8601 date-time required
generatedAt ISO 8601 date-time required
queryKey string required
layerStates object[] required
layerId "territory_jurisdiction" | "territory_claims" | "territory_control" | "conflict_frontlines" | "assets" | "connections" | "pipelines" | "rail" | "physical_relief" | "air_temperature_2m" | "situations" | "events" | "geoexposure" required
revisionId uuid required
status "ready" | "empty" | "partial" | "unavailable" | "error" required
reason string | null required
coverage object required
renderedLevel integer required
sourcePeriod object | null required
counts object required
events integer required
assets integer required
territories integer required
countScope "exact" | "lower_bound" | "unknown" required
nextCursor string | null required
truncated boolean required
Example
curl \
-H "X-Api-Key: $VALYZER_API_KEY" \
"https://api.valyzer.com/v1/world/intersections"