GET/v1/health
Liveness probe. Always public, never rate-limited by identity.
Valyzer API
Public and authenticated HTTP surface, generated from the same contracts the API validates
against. Machine-readable version at /v1/openapi.json.
The internal service-token boundary (/v1/internal/**) and the MCP editorial
boundary are not part of this document.
Base URL: https://api.valyzer.com
Meta
GET
GET/v1/openapi.json
This document, generated from `@valyzer/contracts`.
GET/v1/docs
A self-contained HTML page (no external scripts or stylesheets) rendering this spec.
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.
GET/v1/events/:id
Full projection: entities, claims, relationships, impacts, evidence. `locale=en` drops Spanish-only evidence (WORLD_NEWS §7).
GET/v1/events/:id/history
The recorded-time revision timeline of a published event, without workspace or reviewer identity.
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.
GET/v1/events/:id/evolution/:changeId/changes
Returns additional changes when an evolution entry exceeds the initial page size.
POST/v1/events/:id/corrections
Reviewer/admin only, restricted to the configured editorial workspace. Closes the current event version's recorded interval and appends its successor atomically; preserves valid time. A patch with no effective change is rejected with 409.
Editorial
POST/v1/editorial/conflicts
Admin-only in the configured editorial workspace. Creates an auditable conflict between two stored claim versions and records an opening decision.
GET/v1/editorial/conflicts
Admin-only paginated list of open or resolved conflicts in the editorial workspace.
GET/v1/editorial/conflicts/:id
Admin-only detail view with both claim sides, authorized evidence, and paginated decisions.
POST/v1/editorial/conflicts/:id/resolve
Admin-only resolution with optimistic concurrency on revision and premise versions.
POST/v1/editorial/entities/merge-preview
Admin-only read of expected versions, affected counts, incompatibilities, and a preview token.
POST/v1/editorial/entities/merge
Admin-only merge with preview token validation and auditable equivalence redirect.
POST/v1/editorial/entity-decisions/:id/revert
Admin-only compensating decision that closes the equivalence redirect.
GET/v1/editorial/entities/:id/decisions
Admin-only paginated history of merge decisions for an entity with revert eligibility.
POST/v1/editorial/predicate-proposals
Admin-only vocabulary proposal with authorized examples. Does not relax runtime catalog validation.
GET/v1/editorial/predicate-proposals
Admin-only paginated list filtered by status (default proposed).
GET/v1/editorial/predicate-proposals/:id
Admin-only detail with up to 20 examples and paginated decisions.
POST/v1/editorial/predicate-proposals/:id/decide
Admin-only decision with coverage threshold on accept (3 documents, 2 roots).
POST/v1/editorial/predicate-proposals/:id/mark-implemented
Admin-only closure once the deployed catalog contains an exact matching entry.
GET/v1/editorial/impacts/review-queue
Admin-only paginated queue of impacts marked needs_review or legacy_untracked.
POST/v1/editorial/impacts/:id/review
Admin-only attach, reaffirm, or withdraw with optimistic concurrency on impact and premise versions.
POST/v1/editorial/world/territorial-assertions
Editorial staging for territorial assertions; does not auto-publish.
POST/v1/editorial/world/metric-observations
Editorial staging for metric observations; does not auto-publish.
GET/v1/reviews
Authenticated, reviewer/admin of the requested workspace.
GET/v1/ingestions
Authenticated, reviewer/admin of the requested workspace.
GET/v1/source-catalog
Authenticated. Dataset-scoped rights and document assessments for one workspace.
POST/v1/source-catalog/approvals
Authenticated mutation over the source catalogue.
POST/v1/events/:id/reviews
Authenticated. Publish, reject, or request changes for a pending event analysis. Publishing with known quality flags requires `confirmQualityRisks: true`.
Impacts
GET/v1/impacts/:id/explanation
Returns the authorized premise chain for an impact at the requested temporal cut.
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?' (docs/data/STATE_FORM.md §7); `stateValue` narrows to one coexisting value (a regime's entity uuid, or literal text).
GET/v1/entities/:id
Full projection: relationships and linked events.
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.
GET/v1/sectors/:id/exposure
Same shape as company exposure, scoped to a sector entity. 404 if the id is not a sector.
GET/v1/commodities/:id/risk
Same shape as company exposure, scoped to a commodity entity -- the wedge's first link (`sanction -> commodity`, `docs/product/MOAT_STRATEGY.md` §4). 404 if the id is not a commodity.
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.
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.
Map & World
GET/v1/map/events
The same event filters as `/v1/events`, scoped to a `west,south,east,north` viewport.
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.
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.
GET/v1/world/exposure
Public choropleth layer; `data` is null when no score has ever been calculated.
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.
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.
GET/v1/world/connections
Authenticated. Returns the entity's relationships as connection edges.
GET/v1/world/countries/:iso2
Public country projection: gauges, problems, resource trends, optional geometry.
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.
GET/v1/world/export
Authenticated. `scope=country&id=ISO2`, as JSON or CSV.
GET/v1/world/layers
DAT-02 layer definitions and catalogue snapshot.
GET/v1/world/viewport
NET-02 viewport query with layerStates and pagination.
GET/v1/world/search
Full-text search over published geographies, assets, and entities.
GET/v1/world/changes
Grouped world changes by decision within a bounded time window.
GET/v1/world/clusters/:key/members
Expand a viewport cluster key into its authorized member features.
GET/v1/world/geographies/:id
Geography unit with ancestors, paginated children, and geometry version.
GET/v1/world/observations
DAT-03 observations projected from statistical and object sources.
GET/v1/world/objects/:kind/:id
Detail for event, asset, connection, or entity world objects.
GET/v1/world/objects/:kind/:id/observations
Metric observations attached to a specific world object.
GET/v1/world/objects/:kind/:id/explanations
Paginated public impact explanation summaries for a world object.
GET/v1/world/relations
Actor relations and connected nodes up to depth 2.
GET/v1/world/actors/:id
Published actor projection with typed relations.
GET/v1/world/territorial-assertions
Published territorial assertions with temporal filters.
GET/v1/world/paths
Bounded multi-hop path search over published network edges.
GET/v1/world/metrics
Published world metric definitions and comparability metadata.
GET/v1/world/raster-sample
Nearest-cell raster value for a layer revision and period.
GET/v1/world/intersections
Spatial coincidence query with explicit non-causation disclaimer.
Observatories
GET/v1/observatories/:topic
Source-gated statistical projection for PR-010/011. 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.
Account
GET/v1/me
Authenticated. Profile preferences plus resolved workspace roles.
Admin
GET/v1/admin/load-diary
Admin-only operational read (docs/product/ADMIN.md §3): daily flows of the freeze → assess → load → publish → retract cycle over the public-projection corpus, plus the current public corpus counts. Days are Europe/Madrid calendar days.
GET/v1/admin/invisibility
Admin-only operational read (docs/product/ADMIN.md §4): current graph versions that fail their `publication_boundary_*` predicate at `now()`, each with the first failing gate from the closed `InvisibilityReason` enum.
Client panel
GET/v1/client/workspaces
Only enabled client workspaces the caller currently belongs to, with the effective client capability. No editorial-role inheritance.
GET/v1/client/workspaces/:workspaceId/profile
Current declared profile version plus operator-held identity resolution state. Absent data means unknown, never zero exposure.
PUT/v1/client/workspaces/:workspaceId/profile
Requires the profile-manager capability. Close-and-insert with `expectedVersion` optimistic concurrency; identity resolution stays operator-only.
GET/v1/client/workspaces/:workspaceId/dependencies
Current versions of the private dependency context declared by the organization.
POST/v1/client/workspaces/:workspaceId/dependencies
Requires the profile-manager capability. `expectedVersion` must be null for a new declaration.
PUT/v1/client/workspaces/:workspaceId/dependencies/:id
Requires the profile-manager capability. Close-and-insert against `expectedVersion`; the subject of a declaration is immutable.
GET/v1/client/workspaces/:workspaceId/perimeter
Current perimeter versions including pending resolutions. `original_text` is immutable and preserved verbatim.
POST/v1/client/workspaces/:workspaceId/perimeter
Requires the profile-manager capability. New items enter as `pending`; clients never resolve identities themselves.
POST/v1/client/workspaces/:workspaceId/perimeter/:id/remove
Requires the profile-manager capability. Closes the current version and inserts a `removed` one; nothing is deleted.
GET/v1/client/workspaces/:workspaceId/preferences
Personal preferences of the caller in this workspace; never another member's.
PUT/v1/client/workspaces/:workspaceId/preferences
Personal filtering only; preferences never change the shared profile or the base ranking. The IANA timezone is confirmed, not deduced.
GET/v1/client/workspaces/:workspaceId/today
Deterministic, explainable selection over eligible published data. Responses declare the cut, rule and profile versions, pending counts and honest coverage; a cursor pins pagination to a persisted snapshot.
GET/v1/client/workspaces/:workspaceId/topics/:id
Re-evaluates eligibility before answering; opening a topic never marks it reviewed.
POST/v1/client/workspaces/:workspaceId/topics/:id/reviews
Per-user check bound to an exact material version; idempotent per idempotency key. Does not change the shared status.
POST/v1/client/workspaces/:workspaceId/topics/:id/actions
Requires the collaborator capability. Follow/unfollow/dismiss/close/reopen/assign with expected shared-state version; dismissal requires a reason. Append-only history.
GET/v1/client/workspaces/:workspaceId/members
Membership and client capabilities are operator-managed; there is no self-elevation.
GET/v1/client/workspaces/:workspaceId/sectors
Only currently published sector/industry entities; free text stays pending classification.
GET/v1/client/workspaces/:workspaceId/reports
Only delivered frozen report versions; drafts and reviews are never listed.
GET/v1/client/workspaces/:workspaceId/reports/:id
Hash-verified reopening of the frozen bundle; the report is never recalculated and opening it marks nothing reviewed. Storage keys are never exposed.