Valyzer API

Public HTTP API, generated from the same contracts the API validates against. Machine-readable version at /v1/openapi.json.

Base URL: https://api.valyzer.com

Authentication

Every operation below is called with a vyz_-prefixed API key, created in your Valyzer account, sent as either header:

Quickstart

Create an API key in your Valyzer account, then call any route:

curl -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/events?type=export_restriction&country=CN&knownAt=2025-04-30T00:00:00Z"

The same call with fetch:

const response = await fetch(
  "https://api.valyzer.com/v1/events?type=export_restriction&country=CN&knownAt=2025-04-30T00:00:00Z",
  { headers: { "X-Api-Key": process.env.VALYZER_API_KEY } },
);
const { data: events, page } = await response.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).

Authentication

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.

Plans & quotas

A key's plan is derived from its owner's current entitlement: no entitlement means sandbox (free), otherwise developer or enterprise. Limits are per account, across every key the account owns, per calendar month (UTC). Above the monthly limit the API answers 429 QUOTA_EXCEEDED — there is no overage billing. Developer plan list price: €99/month or €990/year (VAT excluded).

PlanPer-minute limitMonthly quotaMax active keysMax page sizeHistory
sandbox10 / min1,000 / month22030 days
developer120 / min25,000 / month10100365 days
enterprise600 / min1,000,000 / month50100unlimited

Page size. A list limit above the plan's maximum is clamped, not rejected; the effective value is returned in X-Valyzer-Page-Limit.

History window. An API key reads back to now - history (X-Valyzer-History-Days: 30, 365 or unlimited). Default listings only return records inside the window (event lists by occurrence time, revision history by recordedFrom). An explicit asOf (valid time), knownAt / since (recorded time) or occurredFrom earlier than the window, and a single record outside it (GET /v1/events/{id}), answer 403 PLAN_HISTORY_LIMIT. Entity profiles stay readable; their states, events and series are clamped to the window. The /v1/mcp tools apply the same limits.

Rate limits

Independent of plan quotas, every request is also gated by its route's rate-limit class, enforced per minute by Cloudflare's native Rate Limiting bindings (not the old KV-backed counter). A limited request answers 429 RATE_LIMITED with a Retry-After header. Each request is metered in the class of its key's plan: api-sandbox, api-developer or api-enterprise.

ClassLimit
api-developer120 / 60s
api-enterprise600 / 60s
api-sandbox10 / 60s

Pagination

List endpoints return { data: [...], page: { nextCursor, hasMore } }. Pass the previous response's nextCursor back as the cursor query parameter to fetch the next page; nextCursor is null once hasMore is false. Cursors are opaque strings — do not parse or construct them.

Temporal queries: asOf and knownAt

Valyzer data is bitemporal: valid_from/valid_to track when something was true in the world, recorded_from/recorded_to track when the platform came to know/publish it. Most endpoints that accept these expose them as:

Errors

Every error response uses the same envelope: { error: { code, message, requestId, details } }. requestId identifies the request in server logs; details is an array of structured validation issues when code is VALIDATION_ERROR, otherwise empty.

CodeMeaning
VALIDATION_ERRORThe request's query, params or body failed schema validation.
UNAUTHORIZEDThe caller is not allowed to perform this operation.
FORBIDDENThe caller is authenticated but lacks the required role/tier.
NOT_FOUNDNo resource exists at the given id.
RATE_LIMITEDThe caller's per-minute rate-limit class was exceeded; retry after `Retry-After` seconds.
API_KEY_REQUIREDThe request carried no `X-Api-Key` / `Authorization: Bearer vyz_...` key.
API_TIER_REQUIREDThe resolved API plan does not permit this operation (e.g. export needs Developer+).
API_KEY_INVALIDThe supplied API key is malformed or unknown.
API_KEY_REVOKEDThe supplied API key has been revoked.
QUOTA_EXCEEDEDThe account already used its plan's monthly call allowance this UTC month; there is no overage, upgrade the plan or wait for next month.
EXPORT_DAILY_LIMITThe account fetched its plan's export pages for the UTC day (Developer 40, Enterprise 1000); `retry-after` is the seconds to the next UTC midnight. The rejected call spent no monthly quota.
EXPORT_RATE_LIMITEDMore than 6 export pages in a minute for this account; `retry-after` is the seconds to the next minute. The rejected call spent no monthly quota.
PLAN_HISTORY_LIMITThe request reaches further back than the key's plan history window (Sandbox 30 days, Developer 12 months, Enterprise unlimited): an explicit time parameter before the window, or a single record outside it. Upgrade the plan for deeper history.
LOGIN_REQUIREDNo API key was sent with the request.
SERVICE_UNAVAILABLEA transient upstream failure; safe to retry with backoff.
INTERNAL_ERRORAn unexpected server error; the `requestId` in the body identifies it in logs.

Versioning & deprecation

/v1 is the only versioned surface; there is no /v2 yet. The number changes only for a breaking change across the entire surface — an individual route is retired through deprecation (below), not by bumping the whole API.

Breaking vs. additive

Additive (no notice required)Breaking (requires the policy below)
A new endpoint, or a new optional query/body fieldRemoving or renaming an endpoint, field, or error code
A new field on a response objectChanging a field's type, meaning, or removing it
A new enum value accepted on inputRemoving/renaming an accepted enum value, or rejecting a previously-accepted value
Relaxing a validation constraintTightening a validation constraint (new 4xx where there was none)
A new error code for a case that previously had noneChanging the HTTP status or semantics of an existing error code

Minimum notice per plan

Before a breaking change ships on a route still in use, every affected account receives the Deprecation/Sunset headers below (and, where email is on file, a direct notice) at least this long before the Sunset date:

PlanMinimum noticeSupport window after notice
Sandbox30 daysBest-effort; the route keeps answering with Deprecation/Sunset set until the sunset date
Developer90 daysSame contract; 90 days is the quoted "aviso de cambios con antelación pactada" for paid self-serve plans
Enterprise180 days, or the contracted SLA notice period if longerNegotiated per contract; can include an extended/paid support window past the public sunset date

Headers

A deprecated route keeps answering — it never disappears silently — but every response adds:

The same deprecated: true flag appears on the route's operation in /v1/openapi.json.

No route is currently deprecated.

Events

GET/v1/events

Cursor-paginated, bitemporal event feed. Only `published` events are ever returned; `asOf`/`knownAt` select the valid-time and recorded-time cut, defaulting to now/latest.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • cursor string optional
  • 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

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
    • 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/events"

GET/v1/events/:id

Full projection: entities, claims, relationships, impacts, evidence. `locale=en` drops Spanish-only evidence.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • id uuid required
  • asOf ISO 8601 date-time optional
  • knownAt ISO 8601 date-time 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 The event.

  • 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

404 No published event with this id at the given cut.

Error envelope — see Errors.

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/events/11111111-1111-4111-8111-111111111111"

GET/v1/events/:id/history

The recorded-time revision timeline of a published event, without workspace or reviewer identity.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • id uuid 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 A page of revisions.

  • data object[] required
    • eventId uuid required
    • versionId uuid required
    • supersedesVersionId uuid | null required
    • kind "publication" | "correction" required
    • reason string | null required
    • validFrom ISO 8601 date-time required
    • validTo ISO 8601 date-time | null required
    • recordedFrom ISO 8601 date-time required
    • recordedTo ISO 8601 date-time | null required
    • title string required
    • summary string required
    • severity "low" | "medium" | "high" | "critical" required
    • occurrence object required
    • locations object[] required
    • confidence number | null 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/events/11111111-1111-4111-8111-111111111111/history"

GET/v1/events/:id/evolution

Paginated timeline of publications, corrections, claim resolutions and impact reviews at a reproducible bitemporal cut. Compares explicit version ids; restricted comparisons are marked unavailable instead of leaking editorial snapshots.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • id uuid required
  • cursor string optional
  • limit integer optional
  • 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 A page of evolution entries with resolved clocks in meta.

  • data object[] required
    • id uuid required
    • kind "publication" | "event_correction" | "claim_resolution" | "impact_review" required
    • recordedAt ISO 8601 date-time required
    • validFrom ISO 8601 date-time required
    • validTo ISO 8601 date-time | null required
    • publicReason string | null required
    • changes object[] required
    • changesCursor string | null optional
  • page object required
    • nextCursor string | null required
    • hasMore boolean required
  • meta object required
    • asOf ISO 8601 date-time required
    • knownAt ISO 8601 date-time required
    • partial boolean required

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/events/11111111-1111-4111-8111-111111111111/evolution"

GET/v1/events/:id/evolution/:changeId/changes

Returns additional changes when an evolution entry exceeds the initial page size.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • id uuid required
  • changeId uuid 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 A page of typed before/after changes.

  • data object[] required
    • targetType "event" | "claim" | "impact" required
    • targetId uuid required
    • beforeVersionId uuid | null required
    • afterVersionId uuid | null required
    • fields object | object | object[] required
    • evidenceAdded object[] optional
    • evidenceRemoved object[] optional
    • comparisonStatus "available" | "unavailable" optional
  • page object required
    • nextCursor string | null required
    • hasMore boolean required
  • meta object required
    • asOf ISO 8601 date-time required
    • knownAt ISO 8601 date-time required
    • partial boolean required

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/events/11111111-1111-4111-8111-111111111111/evolution/11111111-1111-4111-8111-111111111111/changes"

GET/v1/events/changes

What changed in the public event record between two recorded-time instants, for clients syncing a local copy incrementally -- not what happened (`/v1/events`). Each entry says whether the id is new, corrected (close-and-insert; the client's copy is stale, not gone) or withdrawn (closed with no public successor), and links to `/v1/events/:id/history` for the full before/after. Scoped to publicly published events only, through the same publication/evidence gate as `/v1/events/:id/history`. `since` is required; `until` defaults to request time and is always echoed back in `meta.until`.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • cursor string optional
  • limit integer optional
  • since ISO 8601 date-time required
  • until 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 page of event changes.

  • data object[] required
    • kind "new" | "corrected" | "withdrawn" required
    • changedAt ISO 8601 date-time required
    • event object required
    • historyUrl string required
  • page object required
    • nextCursor string | null required
    • hasMore boolean required
  • meta object required
    • since ISO 8601 date-time required
    • until ISO 8601 date-time required

400 `until` precedes `since`.

Error envelope — see Errors.

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/events/changes?since=2026-01-15T00%3A00%3A00Z"

Briefing

GET/v1/briefing

Published facts in the window, ranked by importance, with their change times and a per-region coverage count. `locale=en` keeps only facts with English or multilingual evidence and links that evidence; unknown language is excluded. Country/region filters drop facts without a located country and count them in `unlocatedExcluded`.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • window "24h" | "7d" | "30d" optional
  • region "EAP" | "ECA" | "LAC" | "MENA" | "NA" | "SA" | "SSA" optional
  • country string optional
  • topic "conflict" | "economic" | "political" | "infrastructure" 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 The Briefing.

  • data object required
    • window "24h" | "7d" | "30d" required
    • occurredFrom string required
    • occurredTo string required
    • facts object[] required
    • truncated boolean required
    • coverage object[] required
    • unlocatedExcluded integer required
    • subjects object[] required

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/briefing"

Impacts

GET/v1/impacts/:id/explanation

Returns the authorized premise chain for an impact at the requested temporal cut.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • id uuid required
  • 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 Impact explanation projection.

  • 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

404 Impact not found or withdrawn at current cut.

Error envelope — see Errors.

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/impacts/11111111-1111-4111-8111-111111111111/explanation"

Entities

GET/v1/entities

Cursor-paginated entity list with kind and free-text filters. `statePredicate` (a catalog predicate of form `state`, e.g. `sanctions.designation`) restricts to subjects of a currently public State at the requested asOf/knownAt — '¿quién está designado a T?'; `stateValue` narrows to one coexisting value (a regime's entity uuid, or literal text).

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • cursor string optional
  • limit integer optional
  • kind "country" | "region" | "company" | "sector" | "industry" | "commodity" | "resource" | "infrastructure" | "trade_route" | "regulation" | "government" | "organization" | "person" | "political_party" | "service" | "country" | "region" | "company" | "sector" | "industry" | "commodity" | "resource" | "infrastructure" | "trade_route" | "regulation" | "government" | "organization" | "person" | "political_party" | "service"[] optional
  • query string optional
  • asOf ISO 8601 date-time optional
  • knownAt ISO 8601 date-time optional
  • statePredicate string optional
  • stateValue 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 A page of entities.

  • data object[] required
    • id uuid required
    • kind "country" | "region" | "company" | "sector" | "industry" | "commodity" | "resource" | "infrastructure" | "trade_route" | "regulation" | "government" | "organization" | "person" | "political_party" | "service" required
    • canonicalName string required
    • aliases string[] required
    • aliasContributions object[] optional
    • requestedEntityId uuid optional
    • canonicalEntityId uuid optional
    • identityDecisionId uuid | null optional
    • geography object | null required
    • states object[] optional
    • relationships object[] required
    • events object[] required
    • updatedAt ISO 8601 date-time required
    • relatedPress object[] optional
  • page object required
    • nextCursor string | null required
    • hasMore boolean required

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/entities"

GET/v1/entities/:id

Full projection: relationships and linked events.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • id uuid required
  • 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 entity.

  • data object required
    • id uuid required
    • kind "country" | "region" | "company" | "sector" | "industry" | "commodity" | "resource" | "infrastructure" | "trade_route" | "regulation" | "government" | "organization" | "person" | "political_party" | "service" required
    • canonicalName string required
    • aliases string[] required
    • aliasContributions object[] optional
    • requestedEntityId uuid optional
    • canonicalEntityId uuid optional
    • identityDecisionId uuid | null optional
    • geography object | null required
    • states object[] optional
    • relationships object[] required
    • events object[] required
    • updatedAt ISO 8601 date-time required
    • relatedPress object[] optional

404 No entity with this id.

Error envelope — see Errors.

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/entities/11111111-1111-4111-8111-111111111111"

GET/v1/entities/changes

What changed in the public entity graph between two recorded-time instants, for clients syncing a local copy incrementally. Each entry says whether the id is new, corrected (close-and-insert; the client's copy is stale, not gone) or withdrawn (closed with no public successor). Scoped to publicly visible entities only, through the same publication boundary as `/v1/entities/:id`. `since` is required; `until` defaults to request time and is always echoed back in `meta.until`.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • cursor string optional
  • limit integer optional
  • since ISO 8601 date-time required
  • until 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 page of entity changes.

  • data object[] required
    • kind "new" | "corrected" | "withdrawn" required
    • changedAt ISO 8601 date-time required
    • entity object required
  • page object required
    • nextCursor string | null required
    • hasMore boolean required
  • meta object required
    • since ISO 8601 date-time required
    • until ISO 8601 date-time required

400 `until` precedes `since`.

Error envelope — see Errors.

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/entities/changes?since=2026-01-15T00%3A00%3A00Z"

Exposure & Impact

GET/v1/companies/:id/exposure

Impacts targeting this company (fact, mechanism, direction, confidence, and evidence per claim) plus its relationships to other entities. 404 if the id is not a company.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • id uuid required
  • 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 company's exposure.

  • data object required
    • entity object required
    • impacts object[] required
    • relationships object[] required
    • meta object required

404 No company with this id.

Error envelope — see Errors.

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/companies/11111111-1111-4111-8111-111111111111/exposure"

GET/v1/sectors/:id/exposure

Same shape as company exposure, scoped to a sector entity. 404 if the id is not a sector.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • id uuid required
  • 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 sector's exposure.

  • data object required
    • entity object required
    • impacts object[] required
    • relationships object[] required
    • meta object required

404 No sector with this id.

Error envelope — see Errors.

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/sectors/11111111-1111-4111-8111-111111111111/exposure"

GET/v1/commodities/:id/risk

Same shape as company exposure, scoped to a commodity entity -- the wedge's first link (sanction -> commodity). 404 if the id is not a commodity.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • id uuid required
  • 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 commodity's risk exposure.

  • data object required
    • entity object required
    • impacts object[] required
    • relationships object[] required
    • meta object required

404 No commodity with this id.

Error envelope — see Errors.

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/commodities/11111111-1111-4111-8111-111111111111/risk"

GET/v1/impact

Cursor-paginated feed of every public impact, each enriched with its claim, event, and target entity. Filterable by entity id and direction.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • cursor string optional
  • limit integer optional
  • entity uuid | uuid[] optional
  • direction "positive" | "negative" | "mixed" | "neutral" | "unknown" | "positive" | "negative" | "mixed" | "neutral" | "unknown"[] optional
  • 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 A page of impacts.

  • data object[] required
    • id uuid required
    • entityId uuid required
    • claimId uuid required
    • direction "positive" | "negative" | "mixed" | "neutral" | "unknown" required
    • mechanism string required
    • horizon "immediate" | "short_term" | "medium_term" | "long_term" required
    • confidence number | null required
    • outcomeClaimId uuid | null required
    • evidence object[] required
    • reviewStatus "current" | "needs_review" | "withdrawn" | "legacy_untracked" optional
    • claim object required
    • event object required
    • entity object 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/impact"

GET/v1/changes

What changed in what we knew between two recorded-time instants -- not what happened (`/v1/events`). `since` is required; `until` defaults to request time and is always echoed back in `meta.until` rather than left implicit.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • cursor string optional
  • limit integer optional
  • since ISO 8601 date-time required
  • until 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 page of changes.

  • data object[] required
    • kind "added" | "removed" required
    • changedAt ISO 8601 date-time required
    • impact object required
  • page object required
    • nextCursor string | null required
    • hasMore boolean required
  • meta object required
    • since ISO 8601 date-time required
    • until ISO 8601 date-time required

400 `until` precedes `since`.

Error envelope — see Errors.

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/changes?since=2026-01-15T00%3A00%3A00Z"

Map & World

GET/v1/map/events

The same event filters as `/v1/events`, scoped to a `west,south,east,north` viewport.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • iso2 string required
  • 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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • code string required
  • 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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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`.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

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"

Observatories

GET/v1/observatories/:topic

Source-gated statistical projection. Returns a stable definition, bitemporal observations, an opaque cursor tied to filters and `knownAt`, and explicit coverage. Definitions may be `unavailable` while source mapping or rights approval is pending; unavailable responses never include factual observations.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • topic "migration" | "housing" | "labour_market" required
  • indicator "foreign_born_share" | "immigration_flow" | "first_asylum_applicants" | "irregular_arrivals" | "house_price_index" | "rental_monthly_median" | "housing_cost_overburden" | "average_wage_gross_annual" | "minimum_wage_gross_monthly" optional
  • geo string[] optional
  • from integer optional
  • to integer optional
  • knownAt ISO 8601 date-time optional
  • cursor string optional
  • limit integer optional
  • locale "en" | "es" 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 selected observatory definition and observation page.

  • definition object required
    • key "foreign_born_share" | "immigration_flow" | "first_asylum_applicants" | "irregular_arrivals" | "house_price_index" | "rental_monthly_median" | "housing_cost_overburden" | "average_wage_gross_annual" | "minimum_wage_gross_monthly" required
    • topic "migration" | "housing" | "labour_market" required
    • label string required
    • definition string required
    • unit "persons" | "percent" | "per_1000" | "index" | "eur_month" | "lcu_month" | "lcu_year" required
    • frequency "annual" | "quarterly" | "cumulative" required
    • populationUniverse string required
    • sourceDatasetRef uuid | null required
    • sourceVariants object[] required
    • methodologyUrl string | null required
    • geoLevels "country" | "autonomous_community" | "autonomous_city"[] required
    • denominatorDefinition string | null required
    • basePeriod string | null required
    • comparabilityGroup string required
    • nextReleaseOn string | null required
    • publicationState "published" | "unavailable" required
    • unavailableReason string | null required
    • wageBasis "gross" | "net" | null required
    • wagePayPeriod "hourly" | "monthly" | "annual" | null required
    • labelEn string | null optional
    • definitionEn string | null optional
    • populationUniverseEn string | null optional
    • denominatorDefinitionEn string | null optional
    • textLocale "en" | "es" optional
  • observations object[] required
    • id uuid required
    • revisionId uuid required
    • indicatorKey "foreign_born_share" | "immigration_flow" | "first_asylum_applicants" | "irregular_arrivals" | "house_price_index" | "rental_monthly_median" | "housing_cost_overburden" | "average_wage_gross_annual" | "minimum_wage_gross_monthly" required
    • geoCode string required
    • geoLevel "country" | "autonomous_community" | "autonomous_city" required
    • periodStart string required
    • periodEnd string required
    • value number | null required
    • missingReason "not_ingested" | "not_available" | "suppressed" | "not_comparable" | "no_statutory_minimum" | "variable_sub_national_or_sectoral" | null required
    • status "provisional" | "final" required
    • sourceDocumentId uuid optional
    • sourceUrl string optional
    • sourcePublishedAt ISO 8601 date-time required
    • recordedAt ISO 8601 date-time required
    • methodologyVersion string required
    • unit "persons" | "percent" | "per_1000" | "index" | "eur_month" | "lcu_month" | "lcu_year" required
    • basePeriod string | null required
    • denominatorValue number | null required
    • denominatorDocumentId uuid | null required
    • coverageNote string | null required
    • currency string | null required
    • paymentsPerYear integer | null required
  • nextCursor string | null required
  • resolvedKnownAt ISO 8601 date-time required
  • coverage object required
    • state "ready" | "empty" | "partial" | "unavailable" required
    • expectedGeographies integer required
    • availableGeographies integer required
    • observations integer required
    • unavailableReason string | null required

400 Invalid filters, cursor mismatch, or incompatible indicator/topic.

Error envelope — see Errors.

404 Unknown observatory topic.

Error envelope — see Errors.

503 Temporarily unavailable; retry later.

Error envelope — see Errors.

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/observatories/migration"

MCP

POST/v1/mcp

Stateless MCP (Streamable HTTP, JSON-RPC 2.0) for agents such as Claude, ChatGPT or Copilot. Authenticate with OAuth 2.1 (claude.ai, ChatGPT and other clients that sign in on a person's behalf: discovery at `/.well-known/oauth-protected-resource/v1/mcp` and `/.well-known/oauth-authorization-server`, scopes `mcp:read` and `offline_access`, PKCE S256, dynamic client registration and Client ID Metadata Documents, consent at valyzer.com) or with an API key (`X-Api-Key` or `Authorization: Bearer vyz_…`) for code and headless clients. Read-only tools: search_events, get_event, get_event_history, search_entities, get_entity, get_country, search_world, list_impact_changes, list_event_changes, list_entity_changes. Protocol messages are free; each tool call is executed as one ordinary `/v1` request with your key, so it counts as one call against your plan's monthly quota and per-minute limit and returns the same data. Quota and rate-limit refusals come back as tool errors (`isError`).

  • Auth: API key
  • Rate limit class: public-read

Body

  • jsonrpc "2.0" required
  • id string | number optional — Request id; omit for notifications.
  • method string required — e.g. initialize, tools/list, tools/call, ping.
  • params object optional — Method parameters, e.g. { name, arguments } for tools/call.

Responses

200 JSON-RPC response (JSON or a single SSE message).

401 Missing, invalid or revoked API key.

Example

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":"tools/call","params":{"name":"search_events","arguments":{"country":["CN"],"type":["export_restriction"],"limit":5}}}' \
  "https://api.valyzer.com/v1/mcp"

Press

GET/v1/press/readings

Original human or agent descriptions and external links, with optional topic and public canonical entity filters. Bibliographic links are not evidence or verified events. Requires the normal data-reading entitlement.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • entityId uuid optional
  • topic 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 Current published readings.

  • data object[] required
    • publisher "reuters" | "bloomberg" | "wall-street-journal" | "new-york-times" | "bbc" | "global-voices" | "el-salto" | "associated-press" | "agence-france-presse" | "efe" | "deutsche-welle" | "france-medias-monde" | "swissinfo" | "rtve" | "voice-of-america" | "civio" | "financial-times" | "the-economist" | "the-guardian" | "al-jazeera" | "politico-europe" | "euractiv" | "el-pais" | "nikkei-asia" required
    • url any required
    • title string required
    • summary string required
    • language "es" | "en" required
    • publishedAt ISO 8601 date-time required
    • checkedAt ISO 8601 date-time required
    • authoredBy string required
    • summaryBasis "editorial_description" required
    • location object | null optional
    • relatedEvents object[] required
    • relatedSituations object[] required
    • signal object | null optional
    • topics string[] optional
    • classificationReason string optional
    • relatedEntities object[] optional
    • agent object optional

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/press/readings"

Hypotheses

GET/v1/press/graph

Current published readings linked to public canonical entities, topics and cited events. Mentions and classifications are not verified entity-to-entity relationships. Requires normal data access; no historical cut is implied.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • entityId uuid optional
  • topic 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 Bibliographic graph.

  • data object required
    • basis "bibliographic_links_not_verified_relationships" required
    • nodes object[] required
    • edges object[] required

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/press/graph"

GET/v1/hypotheses

AI- or Valyzer-editorial-team-authored theses over deterministic clusters of published events. Not facts: model `proposed` versions are unreviewed. Hidden when fewer than two cited events remain public. Legacy API identifiers remain hypotheses.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • topic string optional
  • country 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 Hypotheses grouped by topic.

  • data object required
    • topics object[] required

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/hypotheses"

GET/v1/hypotheses/:id

Current version, rival alternatives and version history.

  • Auth: API key
  • Rate limit class: api-sandbox, api-developer, api-enterprise

Parameters

  • id uuid 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 The hypothesis.

  • data object required
    • hypothesis object required
    • alternatives object[] required
    • history object[] required

404 Unknown or hidden.

Error envelope — see Errors.

Example

curl \
  -H "X-Api-Key: $VALYZER_API_KEY" \
  "https://api.valyzer.com/v1/hypotheses/11111111-1111-4111-8111-111111111111"