REST API

REST API reference

23 endpoints under the base path /api/v1. All routes are API-key protected except GET /health.

Pass your key with the X-API-Key header (or Authorization: Bearer). See Authentication for headers, errors, and quotas.

Commodity(7)

GET/api/v1/alerts

Current active commodity impact alerts, newest first, each with a severity band and an impact_score.

Name	Required	Type / default	Description
limit	optional	default 50, range 1–500	Max alerts to return.
severity	optional	low/moderate/high/critical	Filter to a single severity band.

GET/api/v1/commodities

Daily closing price history for a commodity symbol.

Name	Required	Type / default	Description
symbol	optional	string	Commodity symbol; omit for all.
days	optional	default 30	Days of history.

GET/api/v1/impact/decomposition

Breaks a (region, commodity) impact score into weather vs tariff factors.

Name	Required	Type / default	Description
symbol	required	string	Commodity symbol.
region	required	string	Region ID.
date	optional	YYYY-MM-DD, default today	Date to decompose.

GET/api/v1/analogs

Historical weather episodes most similar to a region's conditions, plus a forward price-move distribution.

Name	Required	Type / default	Description
region	required	string	Region ID.
symbol	required	string	Commodity symbol.
date	optional	YYYY-MM-DD	Reference date.
limit	optional	default 5, range 1–20	Max analogs.
min_similarity	optional	0–100	Minimum similarity score.
same_stage	optional	true/false	Restrict to the same crop growth stage.

GET/api/v1/outlook

Standardized 1–14 day forward weather-impact outlook for a (region, commodity).

Name	Required	Type / default	Description
region	required	string	Region ID.
symbol	required	string	Commodity symbol.

GET/api/v1/climate/context

Seasonal climate percentiles vs the record since 1981.

Name	Required	Type / default	Description
region	required	string	Region ID.
date	optional	default latest weather day	Date to rank.

GET/api/v1/export

Streaming per-day backtest matrix (CSV or JSONL) for one (region, symbol).

Name	Required	Type / default	Description
region	required	string	Region ID.
symbol	required	string	Commodity symbol.
from	optional	default to−1yr	Start date (inclusive).
to	optional	default today	End date (inclusive).
format	optional	default csv; csv\|jsonl	Output format.

Tariffs(2)

GET/api/v1/tariffs/current

Currently active US import tariff rates (USITC HTS).

Name	Required	Type / default	Description
symbol	optional	string	Commodity symbol; omit for all.

GET/api/v1/tariffs/history

Historical US import tariff rates for a commodity.

Name	Required	Type / default	Description
symbol	required	string	Commodity symbol.
days	optional	default 90	Days of history.

Shipping(3)

GET/api/v1/ocean/conditions

Latest buoy observations per active station (port-operational score, delay probability).

Name	Required	Type / default	Description
corridor	optional	string	Corridor ID; omit for all.

GET/api/v1/ocean/corridor-summary

Shipping-disruption risk for one grain export corridor (sea-state + river-draft where applicable; worse-of).

404 if no buoy data for the corridor.

Name	Required	Type / default	Description
corridor	required	string	Corridor ID.
date	optional	default today	Date to evaluate.

GET/api/v1/shipping/index

Global maritime shipping-disruption index: 0–100 per chokepoint/corridor plus a weighted global composite.

No parameters.

Grid(6)

GET/api/v1/grid/coverage

Lists the US balancing authorities / ISOs covered (id, name, ISO, EIA BA code, lat/lon).

No parameters.

GET/api/v1/grid/stress

Standardized 0–10 grid reliability stress per BA plus a demand-weighted national composite.

Name	Required	Type / default	Description
region	optional	string (alias iso)	Narrow to one BA; region wins over iso; omit for all + national.

GET/api/v1/grid/outlook

Forward weather-driven grid demand outlook (~14 days) for one BA.

Name	Required	Type / default	Description
region	required	string	BA / ISO id.

GET/api/v1/grid/carbon/forecast

Forward 'cleanest hours' carbon projection (~48h) for one BA.

Name	Required	Type / default	Description
region	required	string	BA / ISO id.

GET/api/v1/grid/carbon

Average grid carbon intensity (gCO2/kWh) per BA from EIA-930, with a clean/moderate/high band.

No parameters.

GET/api/v1/grid/flexible-load

Cleanest upcoming carbon window plus current grid-stress for one BA, in one call.

Name	Required	Type / default	Description
region	required	string	BA / ISO id.

Meta(5)

GET/api/v1/summary

Cross-domain snapshot: coverage, top current alerts, national grid stress, global shipping status.

No parameters.

GET/api/v1/subscriptions

Lists the key's webhook alert subscriptions.

No parameters.

POST/api/v1/subscriptions

Creates a webhook alert subscription (secret returned once).

JSON body. 201 on success; 422 if the per-key subscription limit is reached.

Name	Required	Type / default	Description
region	optional	string	Filter to a region.
symbol	optional	string	Filter to a symbol.
min_severity	required	low/moderate/high/critical	Minimum severity that triggers the webhook.
target_url	required	HTTPS URL	Delivery URL (Slack incoming webhooks supported).

DELETE/api/v1/subscriptions/{id}

Deletes one of the key's subscriptions.

204 on success; 404 if not found / not owned.

Name	Required	Type / default	Description
id	required	UUID (path param)	Subscription id.

GET/api/v1/health

Open, unauthenticated health check.

No parameters.