> API Documentation

Seldon Vault provides a free, public, read-only REST API. No authentication required. All responses are JSON. Base URL:

http://frontend/api/v1

Rate limit: 60 requests/minute per IP (20/min for search and browse endpoints). Returns 429 if exceeded.

// Endpoints

GET

/forecasts/daily

Today's forecast digest — all forecasts created today.

curl http://frontend/api/v1/forecasts/daily

{
  "date": "2026-03-12",
  "forecasts": [
    {
      "id": "uuid",
      "title_en": "EU-China Trade Tensions Escalation",
      "title_ru": "Эскалация торговых напряжений ЕС-Китай",
      "probability": 0.72,
      "sector": "economics",
      "severity": "high",
      "status": "active",
      "horizon_days": 14,
      "created_at": "2026-03-12T08:00:00Z"
    }
  ]
}

GET

/forecasts

Browse all forecasts with filtering, search, and pagination.

?status=active|resolved|expired

?search=keyword

?date_from=2026-01-01&date_to=2026-03-12

?prob_min=0.5&prob_max=0.9

?page=1&per_page=20

curl "http://frontend/api/v1/forecasts?status=active&sector=geopolitics&page=1"

{
  "items": [...],
  "total": 42,
  "page": 1,
  "per_page": 20
}

GET

/forecasts/{id}

Full forecast detail with agent analyses, Skeptic review, historical analogies, and Seldon synthesis.

curl http://frontend/api/v1/forecasts/550e8400-e29b-41d4-a716-446655440000

{
  "id": "550e8400-...",
  "title_en": "...",
  "probability": 0.72,
  "description_en": "...",
  "geopolitician_analysis": { "summary": "...", "probability": 0.75 },
  "skeptic_analysis": { "risk_score": 68, "approved": true, "critique": "..." },
  "seldon_synthesis": { "digest_summary_en": "..." },
  "brier_score": null
}

GET

/forecasts/{id}/updates

Probability update history for a specific forecast (Bayesian updates over time).

curl http://frontend/api/v1/forecasts/550e8400-.../updates

[
  {
    "id": "...",
    "probability": 0.72,
    "previous_prob": 0.65,
    "delta": 0.07,
    "trigger_event": "New satellite imagery confirms troop movements",
    "updated_at": "2026-03-12T14:00:00Z"
  }
]

GET

/metrics

Aggregated accuracy metrics: total forecasts, resolved count, average Brier Score, broken down by sector and agent.

curl http://frontend/api/v1/metrics

{
  "total_forecasts": 1247,
  "resolved_forecasts": 823,
  "avg_brier_score": 0.18,
  "by_sector": {
    "geopolitics": { "count": 312, "avg_brier_score": 0.19 },
    "economics": { "count": 289, "avg_brier_score": 0.16 }
  }
}

GET

/metrics/resolution

Resolution statistics — auto-resolved vs manual vs expired, resolution rate, breakdown by outcome.

curl http://frontend/api/v1/metrics/resolution

{
  "total": 1247,
  "active": 312,
  "expired": 112,
  "resolved": 823,
  "auto_resolved": 487,
  "manual_resolved": 336,
  "has_criteria": 1135,
  "auto_resolve_rate": 0.5918,
  "resolution_rate": 0.8802,
  "by_resolution": {
    "correct": 612,
    "incorrect": 156,
    "partial": 43,
    "ambiguous": 12
  }
}

GET

/metrics/calibration

Calibration curve data — predicted probability buckets vs actual outcomes.

GET

/regions

Regional risk summaries: active forecast count, average probability, top sector per region.

GET

/regions/{region}/forecasts

Forecasts filtered by geographic region.

Regions: global, north_america, south_america, europe, middle_east, africa, central_asia, east_asia, south_asia, southeast_asia, oceania

GET

/narratives

Cascade narratives — causal chains between related forecasts.

?status=active|resolved

?page=1&per_page=20

GET

/narratives/{id}

Narrative detail with causal links between forecasts.

GET

/narratives/{id}/graph

D3-compatible graph data (nodes + edges) for visualizing causal chains.

GET

/signals

Raw news signals collected from RSS, GDELT, ACLED, and other sources.

GET

/signals/clusters

Signal clusters — semantically grouped signals with source diversity metrics.

?pipeline_run_id=uuid

?page=1&per_page=20

curl http://frontend/api/v1/signals/clusters

{
  "items": [
    {
      "id": "uuid",
      "headline": "EU imposes new tariffs on Chinese EVs",
      "summary": "Multiple sources report...",
      "signal_count": 4,
      "source_count": 3,
      "sources": ["Reuters", "BBC", "DW"],
      "importance_max": 85,
      "sentiment_avg": -0.42,
      "sectors": ["economics", "geopolitics"],
      "source_ratings": {"Reuters": 0.85, "BBC": 0.72, "DW": 0.68}
    }
  ],
  "total": 47,
  "page": 1,
  "per_page": 20
}

GET

/signals/clusters/{id}

Cluster detail with all constituent signals.

GET

/sources/ratings

Source reliability ratings — per-source, per-sector accuracy computed from historical Brier scores.

?min_signals=10

?page=1&per_page=50

curl http://frontend/api/v1/sources/ratings

{
  "items": [
    {
      "id": "uuid",
      "source_name": "Reuters",
      "sector": "_all",
      "accuracy": 0.8523,
      "independence": 0.3200,
      "composite": 0.6926,
      "signal_count": 147,
      "cluster_count": 89,
      "forecast_count": 23,
      "avg_brier": 0.1477,
      "computed_at": "2026-03-17T01:00:00Z"
    }
  ],
  "total": 82,
  "page": 1,
  "per_page": 50
}

GET

/sources/ratings/{source_name}

All sector ratings for a specific source, plus global aggregate.

curl http://frontend/api/v1/sources/ratings/Reuters

{
  "source_name": "Reuters",
  "global_rating": {
    "sector": "_all",
    "accuracy": 0.8523,
    "independence": 0.3200,
    "composite": 0.6926,
    "signal_count": 147,
    "forecast_count": 23,
    "avg_brier": 0.1477
  },
  "sectors": [
    { "sector": "geopolitics", "composite": 0.7812, "accuracy": 0.8874 },
    { "sector": "economics", "composite": 0.6240, "accuracy": 0.7920 },
    { "sector": "_all", "composite": 0.6926, "accuracy": 0.8523 }
  ]
}

GET

/events/chains

Event chains — cross-day temporal linking of signal clusters into evolving storylines with lifecycle stages.

?status=active|stale|resolved

?page=1&per_page=20

curl http://frontend/api/v1/events/chains

{
  "items": [
    {
      "id": "uuid",
      "headline": "Iran nuclear negotiations stall",
      "summary": "Multi-day storyline tracking...",
      "current_stage": "escalation",
      "cluster_count": 5,
      "first_seen": "2026-03-11T08:00:00Z",
      "last_seen": "2026-03-17T08:00:00Z",
      "sectors": ["geopolitics", "military"],
      "status": "active",
      "forecast_ids": ["uuid1", "uuid2"]
    }
  ],
  "total": 31,
  "page": 1,
  "per_page": 20
}

GET

/events/chains/{id}

Event chain detail with full cluster timeline, lifecycle stage history, and linked forecasts.

curl http://frontend/api/v1/events/chains/550e8400-...

{
  "id": "...",
  "headline": "Iran nuclear negotiations stall",
  "current_stage": "escalation",
  "cluster_count": 5,
  "clusters": [
    {
      "id": "uuid",
      "headline": "IAEA reports enrichment increase",
      "chain_position": 1,
      "lifecycle_stage": "rumor",
      "created_at": "2026-03-11T08:00:00Z"
    },
    {
      "id": "uuid",
      "headline": "Western diplomats confirm stalled talks",
      "chain_position": 2,
      "lifecycle_stage": "confirmation",
      "created_at": "2026-03-13T08:00:00Z"
    }
  ]
}

GET

/structural/reports

Seldon Plan report archive — monthly long-term psychohistorical reports with master scenarios.

?page=1&per_page=20

curl http://frontend/api/v1/structural/reports

{
  "items": [
    {
      "id": "uuid",
      "report_date": "2026-03-01",
      "epoch": 1,
      "created_at": "2026-03-31T22:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

GET

/structural/reports/latest

Latest Seldon Report with all domain forecasts, master scenarios, critical junctures, and leading indicators.

curl http://frontend/api/v1/structural/reports/latest

{
  "id": "uuid",
  "report_date": "2026-03-01",
  "epoch": 1,
  "master_scenarios": [
    {
      "label": "Turbulent Equilibrium",
      "probability": 0.35,
      "description": "Managed fragmentation...",
      "key_drivers": ["US-China competition", "Energy transition"],
      "risks": ["Cascading crisis", "Policy failure"]
    }
  ],
  "critical_junctures": [...],
  "leading_indicators": [...],
  "seldon_commentary": "...",
  "forecasts": [...]
}

GET

/structural/reports/{id}

Full Seldon Report by ID with all domain forecasts attached.

GET

/structural/reports/{id}/domains/{domain}

Single domain forecast detail from a Seldon Report.

GET

/structural/indicators

Leading indicator snapshots — quarterly tracking of structural metrics against thresholds.

?report_id=uuid

?page=1&per_page=20

GET

/shadow/reports

The Mule report archive — weekly contrarian analysis with alternative narratives.

?page=1&per_page=20

curl http://frontend/api/v1/shadow/reports

{
  "items": [
    {
      "id": "uuid",
      "report_date": "2026-04-06",
      "epoch": 1,
      "mega_chains_count": 22,
      "status": "published",
      "created_at": "2026-04-06T05:07:30Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

GET

/shadow/reports/latest

Latest Mule report with all narratives, evidence, cui bono analysis, and general commentary.

curl http://frontend/api/v1/shadow/reports/latest

{
  "id": "uuid",
  "report_date": "2026-04-06",
  "epoch": 1,
  "mega_chains_count": 22,
  "general_commentary_en": "The world this week presented...",
  "general_commentary_ru": "Мир на этой неделе...",
  "narratives": [
    {
      "title_en": "The Semiconductor Silk Road",
      "title_ru": "Полупроводниковый Шёлковый путь",
      "thesis_en": "The trade war is cover for...",
      "absurdity_index": 0.6,
      "status": "new",
      "connected_chains": ["US-China Trade War", "AI Chip Export Controls"],
      "evidence": [
        { "fact": "TSMC announced...", "source": "fact_check", "relevance": "..." }
      ],
      "cui_bono": [
        { "actor": "TSMC", "motive": "Monopoly pricing power" }
      ],
      "what_to_watch": ["TSMC Q2 earnings call", "New export control announcements"]
    }
  ]
}

GET

/shadow/reports/{id}

Full Mule report by ID with all narratives and commentary.

GET

/events/stream

Server-Sent Events (SSE) — real-time notifications.

curl -N http://frontend/api/v1/events/stream

event: forecast_created
data: {"id": "...", "title_en": "...", "probability": 0.72}

event: forecast_updated
data: {"id": "...", "probability": 0.78, "delta": 0.06}

event: narrative_created
data: {"id": "...", "title_en": "..."}

GET

/pipeline/runs

Pipeline audit log — history of all pipeline runs with statistics.

?run_type=daily|update

?page=1&per_page=20

curl http://frontend/api/v1/pipeline/runs

{
  "items": [
    {
      "id": "uuid",
      "run_type": "daily",
      "status": "success",
      "duration_seconds": 754.2,
      "statistics": {
        "proposals_total": 23,
        "proposals_approved": 4,
        "forecasts_stored": 4
      },
      "started_at": "2026-03-16T08:04:40Z"
    }
  ],
  "total": 47,
  "page": 1,
  "per_page": 20
}

GET

/pipeline/runs/{id}

Pipeline run detail with all analyst proposals (approved + rejected), Skeptic reviews, and final decisions.

curl http://frontend/api/v1/pipeline/runs/550e8400-...

{
  "id": "...",
  "run_type": "daily",
  "status": "success",
  "proposals": [
    {
      "source_agent": "geopolitician",
      "title_en": "NATO expansion triggers buildup",
      "status": "approved",
      "skeptic_risk_score": 78,
      "seldon_final_probability": 0.68
    },
    {
      "source_agent": "economist",
      "title_en": "Eurozone recession deepens",
      "status": "rejected",
      "skeptic_risk_score": 35,
      "skeptic_critique": "Insufficient evidence"
    }
  ]
}

← About How It Works