API and agent guide

Foresight Engine publishes every run through a read-only JSON API. There is no sign-up and no API key: send a GET request and you get the same bytes the engine's own kernel returns for that path.

Base URL: https://foresight-engine.pages.dev
OpenAPI 3.1 document: /openapi.json (also at /api/openapi.json)
Agent summary: /llms.txt, with every page in full at /llms-full.txt
Authentication: none. All endpoints are public and read-only.
Formats: JSON for data, binary for snapshots, logos and workbooks. Every HTML page is also served as Markdown when you send Accept: text/markdown.

When to use this API

Use it when you need sourced, reviewable numbers about a specific insured loss and the technology that mitigates it, for example:

listing the ventures working on flood or wildfire damage to property in Europe, with their country, impact channel and evidence;
quoting a ten-year insured-loss trajectory with its low and high bands, and saying which parameters move it most;
tracing a figure back to the archived report it came from, and to the research leads who approved it.

Do not use it for live market prices, policy quotes or claims data about individual people: it holds none of those.

Quickstart

List the runs, then read one run's catalog and forecast:

curl -s https://foresight-engine.pages.dev/api/runs
curl -s https://foresight-engine.pages.dev/api/runs/2026-wildfire-southern-europe/ventures
curl -s https://foresight-engine.pages.dev/api/runs/2026-wildfire-southern-europe/forecast

Download the archived source behind a figure by its SHA-256 digest, as listed in a run's evidence:

curl -s https://foresight-engine.pages.dev/api/runs/2026-wildfire-southern-europe/evidence
curl -sO https://foresight-engine.pages.dev/api/runs/2026-wildfire-southern-europe/snapshots/<digest>

Endpoints

Endpoint	Operation	What it returns
`GET /api/health`	`getHealth`	Engine health and version.
`GET /api/packs`	`listPacks`	List industry packs.
`GET /api/packs/{pack_id}`	`getPack`	Get one industry pack.
`GET /api/runs`	`listRuns`	List forecast runs.
`GET /api/runs/{run_id}`	`getRun`	Get one run with its stages and sign-offs.
`GET /api/runs/{run_id}/ventures`	`listRunVentures`	List a run's venture catalog.
`GET /api/runs/{run_id}/categories`	`listRunCategories`	List a run's mitigation categories.
`GET /api/runs/{run_id}/forecast`	`getRunForecast`	Get a run's loss forecast.
`GET /api/runs/{run_id}/sensitivity`	`getRunSensitivity`	Get a run's sensitivity analysis.
`GET /api/runs/{run_id}/evidence`	`getRunEvidence`	Get a run's evidence graph.
`GET /api/runs/{run_id}/log`	`getRunLog`	Get a run's event log.
`GET /api/runs/{run_id}/tasks`	`listRunTasks`	List a run's agent tasks.
`GET /api/runs/{run_id}/gates`	`getRunGates`	Get a run's methodology gate findings.
`GET /api/runs/{run_id}/evals/tiering`	`getRunTieringEval`	Get a run's category tiering check.
`GET /api/tasks`	`listTasks`	List agent tasks across all runs.
`GET /api/runs/{run_id}/snapshots/{digest}`	`getRunSnapshot`	Download an archived source snapshot.
`GET /api/runs/{run_id}/logos/{vid}`	`getVentureLogo`	Download a venture's logo.
`GET /api/runs/{run_id}/exports/catalog.xlsx`	`downloadVentureCatalog`	Download a run's venture catalog workbook.

Errors

Errors are JSON with a detail field that says what went wrong in plain words. An unknown run, pack, venture or snapshot answers 404. A forecast or sensitivity request on a run that has not reached its computed stage answers with the status the kernel gives it. Unknown pages answer a real 404, in Markdown if you asked for it.

Writing

Creating runs, answering agent tasks and signing off stages happen in the web app, where the engine runs inside your browser and commits its changes to shared storage. They are deliberately not part of the public API. Open the app to do them.

Limits

The site runs on Cloudflare's free plan, so every request shares one daily quota. Cache what you read, avoid polling more than once a minute, and prefer /api/runs to discover what changed. Responses may be gzip-compressed; send Accept-Encoding: gzip or let your client decompress.