The data is free; keeping it current, correct, and integration-ready is the product. The
SoftSignal Data API exposes the same derived signals as our MCP server over plain REST/JSON —
COT positioning, WASDE balance sheets, agro-climatic stress, EIA energy, and supply-chain risk —
with one defining feature: every payload carries its own freshness contract.
You always know the through-date and whether a series is on-time, behind, or stale, without
leaving your tool.
Base URL
https://chat.getsoftsignal.com/api/v1
Authentication
Pass your subscriber API key as a bearer token —
Authorization: Bearer ss_your_key — or as a
?key= query parameter. It's the same key as the
MCP server: one subscription covers both surfaces, no separate API tier. The
/api/v1 catalog and /api/v1/status are
public so you can assess the API before subscribing.
Get your key: sign in to your hub at
chat.getsoftsignal.com/hub and click
API key — you can view, copy, and rotate it there. The same key works in
Claude Desktop / ChatGPT over MCP and on this API.
The freshness contract
Every successful response includes a freshness block —
{ as_of, status, cadence, age_days, source } — for that
endpoint's primary series, drawn from our live data-freshness monitor.
status is cadence-aware: a weekly series reflecting its
source's normal one-week publish lag reads current, not stale. See
the full picture on the data status page or fetch
/api/v1/status.
Conventions
Derived signals only — raw prices are never returned. Responses are
{ "status": "success", ... } on 200; an unknown identifier or
unavailable series returns 404 with
{ "status": "error", "error": "..." }.
$ curl -s https://chat.getsoftsignal.com/api/v1/cot/corn \
-H "Authorization: Bearer ss_your_key_here"
{
"status": "success",
"as_of": "2026-06-02T00:00:00Z",
"context": { "market": "corn" },
"data": { "mm_net_pct": 59, "signal": "neutral — no positioning edge", ... },
"freshness": {
"as_of": "2026-06-02", "status": "current", "cadence": "weekly",
"age_days": 4, "source": "CFTC Disaggregated COT"
},
"source": "CFTC Disaggregated COT"
}
Endpoints
Discovery & status
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1
API catalog — every endpoint, params, and a sample. |
— |
public |
| GET/api/v1/status
Freshness status for every public series (the status page, as JSON). |
— |
public |
| GET/api/v1/markets
All markets, regions, and commodities covered, with identifiers. |
— |
key |
| GET/api/v1/freshness
Through-date + cadence-aware status for every pipeline series. |
— |
key |
COT positioning
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1/cot/{market}
COT positioning snapshot for a market. |
market — path — identifier from /markets |
key |
| GET/api/v1/cot/{market}/percentile
Managed-money positioning percentile + signal. |
market — path |
key |
| GET/api/v1/cot/{market}/change
Week-over-week change in managed-money net. |
market — path |
key |
| GET/api/v1/cot/{market}/history
Weekly COT time series (default 52, max 200 weeks). |
market — pathweeks — query int, default 52 |
key |
| GET/api/v1/cot
Multi-market COT snapshot. ?markets=corn,natgas,hogs_lean |
markets — query CSV of identifiers |
key |
Weather
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1/weather/{region}
Agro-climatic snapshot for a coffee growing region. |
region — path — e.g. arabica_brazil |
key |
| GET/api/v1/weather/{region}/history
Dekadal weather series (default 36, max 108 dekads). |
region — pathdekads — query int, default 36 |
key |
| GET/api/v1/weather/{region}/seasonal
Current CWSI vs. same dekad in prior years. |
region — path |
key |
| GET/api/v1/cwsi/{region}
Crop Water Stress Index deviation + seasonal rank. |
region — path |
key |
| GET/api/v1/weather-forecast
14-day forecast for a region (omit region for all). |
region — query, optional |
key |
Energy
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1/eia/storage
Current EIA natural-gas storage report + percentile. |
— |
key |
| GET/api/v1/eia/storage/history
Weekly NG storage series (default 52, max 260 weeks). |
weeks — query int, default 52 |
key |
| GET/api/v1/eia/petroleum-demand
US gasoline + distillate demand (4-wk avg, YoY). |
— |
key |
| GET/api/v1/eia/crack-spread
3-2-1 crack spread (refiner margin) + percentile. |
— |
key |
| GET/api/v1/eia/biofuel-feedstock
Soybean oil's share of US biomass-based diesel feedstock + volume. |
— |
key |
| GET/api/v1/eia/biofuel-feedstock/history
Monthly soy-oil biofuel feedstock series (default 36, max 120 months). |
months — query int, default 36 |
key |
Climate
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1/enso
ENSO phase with ONI, RONI, Rnino34 + commodity implications. |
— |
key |
WASDE supply & demand
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1/wasde/{commodity}
WASDE balance sheet for a commodity (corn/soybeans/wheat/cotton). |
commodity — path |
key |
| GET/api/v1/wasde/{commodity}/stocks-to-use
World stocks-to-use ratio + percentile rank. |
commodity — path |
key |
| GET/api/v1/wasde/{commodity}/revision
Month-over-month WASDE revision. |
commodity — path |
key |
Acreage
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1/acreage
Planted-acre snapshot for all five crops. |
— |
key |
| GET/api/v1/acreage/{crop}
Planted-acre estimate for a crop + percentile. |
crop — path — corn/soybeans/cotton/wheat_winter/wheat_spring |
key |
| GET/api/v1/acreage/{crop}/history
Full planted-acreage history since 1990. |
crop — path |
key |
Drought
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1/drought/{region}
US Drought Monitor D3+D4 coverage for a region. |
region — path — e.g. drought_corn_belt |
key |
| GET/api/v1/drought/{region}/history
Weekly D3+D4 coverage (default 52, max 260 weeks). |
region — pathweeks — query int, default 52 |
key |
Livestock
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1/livestock/stress
Heat/cold stress for hog + feedlot belts, with 14-day forecast. |
— |
key |
Crop progress
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1/crop-progress
USDA NASS planting progress + condition ratings (US national). |
— |
key |
Coffee
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1/coffee/fundamentals
Coffee PSD balance + BRL/USD context. |
— |
key |
| GET/api/v1/coffee/certified-stocks
ICE certified (deliverable) coffee stocks — level, YoY, range, history. |
contract — query — robusta (default) or arabica |
key |
| GET/api/v1/coffee/leaf-rust
Weather CONDUCIVENESS to coffee leaf rust by origin (temp × leaf-wetness, recent + 14-day forecast). Environmental risk signal, NOT observed disease. |
region — query, optional — origin key or 'all' (default) |
key |
Supply-chain & exports
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1/grain-exports
USDA FAS ESR export pace (omit grain for all). |
grain — query, optional — corn/soybeans/wheat |
key |
| GET/api/v1/argentina
Argentina production estimates (omit commodity for all). |
commodity — query, optional |
key |
Calendar
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1/release-schedule
Upcoming USDA/EIA/CFTC release calendar. |
— |
key |
Other
| Endpoint | Parameters | Auth |
|---|
| GET/api/v1/kb
Knowledge base (public, read-only): resolve a term/acronym/metric/methodology, or fetch one entry. ?q=<question> to search, ?id=<entry id> to fetch (e.g. a provenance method_ref), no params for the full menu. |
q — query, optional — e.g. 'what is RONI vs ONI'id — entry id, optional — e.g. iod-dmi-self-computedlimit — query int, default 3 (search only) |
public |
| GET/api/v1/coffee-frost
Brazil arabica frost risk. Omit point for all 10 + belt share. |
point — query, optional — e.g. poco_caldas |
key |
| GET/api/v1/coffee-leaf-rust
Coffee leaf-rust conduciveness by origin. |
region — query, optional — default all |
key |
| GET/api/v1/china-weather/frost
NE China early-autumn frost risk. Omit point for all 5 monitored points. |
point — query, optional |
key |
| GET/api/v1/china-weather/dry-hot-wind
NCP China dry-hot-wind (干热风) risk. Omit point for all 5 stations. |
point — query, optional |
key |
| GET/api/v1/china-weather/harvest-rain
NCP China harvest-window rain -> quality risk. Omit province for all 5. |
province — query, optional |
key |
| GET/api/v1/iod
Indian Ocean Dipole — DMI phase, West/East poles + history. |
months — query, optional history window (default 24) |
key |
| GET/api/v1/navigability
Northern Arc navigability — Brazil Arco Norte barge-corridor pressure tier + per-leg (Madeira/Tapajós/mainstem) dry-season-low forecasts. |
— |
key |
| GET/api/v1/fertilizer
Brazil fertilizer supply-risk: gas→urea margin, import flows, chokepoint, affordability + farmgate barter. |
— |
key |
| GET/api/v1/fertilizer/india
India fertilizer supply-risk: importer-margin-vs-NBS gap (DAP landed vs MRP+subsidy), urea subsidy-bill pressure (Asia LNG + rupee), import chokepoint exposure. |
— |
key |
| GET/api/v1/fertilizer/us
US fertilizer supply-risk: producer competitiveness (gas→urea cost cushion vs world/EU), Mississippi barge logistics (rate + river stage), import chokepoint (Canada potash). |
— |
key |
| GET/api/v1/fertilizer/exporters
Global exporter fertilizer supply-risk: export concentration (HHI), swing-exporter availability vs seasonal normal (China quotas), European marginal-cost squeeze. |
— |
key |
| GET/api/v1/sugar
Brazil CS sugar–ethanol parity & mill-mix: signed sugar-supply tilt from sugar vs ethanol netback (R$/kg ATR), CONAB realized sugar-mix %, and ANP pump-parity demand. |
— |
key |
| GET/api/v1/crop
Free catalog of crop-agency subject views — subject, as-of date, freshness, commodities, teaser, and the source reports behind each. The full cited view is on /crop/{subject}. Optional ?commodity= filters the catalog: views are keyed by subject, so one commodity spans several of them (wheat runs through the Canada, Brazil, EU, Ukraine, Australia and Indonesia views; cotton through the Brazil, China and India views). The response carries the closed vocabulary in 'commodities_available'. |
commodity — query, optional: barley | coffee | corn | cotton | durum | ethanol | palm-oil | rapeseed | rice | rye | sorghum | soybean-meal | soybeans | sugar | wheat |
public |
| GET/api/v1/crop/{subject}
The cited agency view on a subject (e.g. china-corn | brazil-corn | brazil-cotton | india-cotton | canada-canola | ukraine-grain | eu-grain | brazil-enso | brazil-coffee — 28 in all): current position, revision trail, sources, and SoftSignal's separate note. Views are keyed by subject, not agency — the Brazil views carry Conab and USDA side by side because they disagree. Sources come in three kinds: attaché ('Post') figures are USDA staff research, not official; Conab's levantamento is Brazil's official survey; 'industry research' (Fundação Procafé's coffee warning stations) is select monitored plots — evidence a condition is present in the area, never a share of regional production. Where 'observation_period' is present it, not 'as_of', is the date the conditions describe, and may be weeks earlier — cite it on every statement. Licensing differs per view — see the 'license' field (Conab and Procafé material require source citation). Call /crop for the live subject list. |
subject — path: one of the 28 subject ids — call /crop for the live list (china-corn | brazil-corn | brazil-cotton | india-cotton | canada-canola | ukraine-grain | eu-grain | brazil-enso | …) |
key |