API Reference — DataCrop

Introduction

The DataCrop API is a REST API that delivers real-time grain market intelligence — price observations, 13-week forecasts, procurement signals, and alert management — across corn, soybeans, and wheat.

Base URLhttps://api.datacrop.dev

Local devhttp://localhost:8000

Response formatJSON / UTF-8

TLSRequired in production

Tier	Requests / day	Commodities
Free	200	Corn only
Pro	2,000	All 3
Max	5,000	All 3
Team	20,000	All 3

Authentication

Every request must include your API key in the Authorization header as a Bearer token. Get your key from Dashboard → API Key.

Authorization: Bearer YOUR_API_KEY

Every authenticated response carries three rate-limit headers:

Header	Description
X-RateLimit-Limit	Daily request quota for your tier
X-RateLimit-Remaining	Requests left today
X-RateLimit-Reset	Epoch seconds when the quota resets (midnight UTC)

Account

GET/v1/meAll tiers

Returns your API key's identity: tier, daily rate limit, requests used today, remaining requests, allowed commodities, and a feature flag map. Useful for dynamically adjusting your integration based on your plan.

Example

curl -X GET "https://api.datacrop.dev/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "api_key_id": "3f9a1b2c-...",
  "tier": "max",
  "rate_limit_per_day": 5000,
  "requests_today": 134,
  "requests_remaining": 4866,
  "resets_at": "2026-06-05T00:00:00+00:00",
  "allowed_commodities": ["corn", "soybean", "wheat"],
  "features": {
    "forecasts": true,
    "procurement_tools": true,
    "alerts": true,
    "raw_export": false,
    "dashboard": true,
    "write": false
  }
}

Series Data

GET/v1/seriesFree+

Fetch paginated time-series price observations for a commodity. Supports three sources: AMS (weekly cash bids), FRED (monthly PPI index and global prices), and NASS (annual price received). Free tier is limited to corn and the past 1 year; Pro and above get all commodities and full history.

Parameters

Parameter	Type	Required	Description
commodity	string	✱ yes	Commodity slug e.g. corn, soybean, wheat
source	string[]	no	Filter by source: FRED \| AMS \| NASS (repeatable)
start_date	string	no	Floor date YYYY-MM-DD
end_date	string	no	Ceiling date YYYY-MM-DD
limit	integer	no	Page size, max 1000 (default 1000)
offset	integer	no	Pagination offset (default 0)
as_of	string	no	Vintage cutoff YYYY-MM-DD — return data as it was known on this date

Example

curl -X GET \
  "https://api.datacrop.dev/v1/series?commodity=corn&source=AMS&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "commodity": "corn",
  "pagination": { "limit": 5, "offset": 0, "total": 1843, "has_more": true },
  "series": [
    { "source": "AMS", "source_ref": "3223", "date": "2026-06-04",
      "value": 4.52, "unit": "USD/bu", "region": "IL" },
    { "source": "AMS", "source_ref": "3223", "date": "2026-05-28",
      "value": 4.48, "unit": "USD/bu", "region": "IL" }
  ],
  "freshness": { "last_updated": "2026-06-04", "stale": false },
  "warnings": []
}

GET/v1/commoditiesAll tiers

Returns the list of commodity slugs your API key is allowed to query, along with the earliest available date for your tier. Use this to build dynamic dropdowns or validate commodity inputs before calling /v1/series.

Example

curl -X GET "https://api.datacrop.dev/v1/commodities" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "tier": "max",
  "commodities": ["corn", "soybean", "wheat"],
  "date_range": { "start": "2015-01-01", "end": null }
}

GET/v1/freshness/{commodity}All tiers

Returns the last-ingested date for each data source (AMS, FRED, NASS) for the given commodity. Use this to show users when data was last updated or to detect stale feeds.

Parameters

Parameter	Type	Required	Description
commodity	string	✱ yes	Commodity slug in the URL path e.g. /v1/freshness/corn

Example

curl -X GET "https://api.datacrop.dev/v1/freshness/corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "commodity": "corn",
  "sources": {
    "AMS":  { "last_date": "2026-06-04", "stale": false },
    "FRED": { "last_date": "2026-05-01", "stale": false },
    "NASS": { "last_date": "2026-01-01", "stale": false }
  }
}

Forecasts

GET/v1/forecastsPro+

Returns the latest 13-week LightGBM forecast for a commodity as P10 (bear), P50 (base), and P90 (bull) price bands. Updated every Monday at 7 AM ET after the weekly AMS/FRED/NASS data ingestion completes.

Parameters

Parameter	Type	Required	Description
commodity	string	✱ yes	Commodity slug e.g. corn

Example

curl -X GET \
  "https://api.datacrop.dev/v1/forecasts?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "commodity": "corn",
  "run_date": "2026-06-02",
  "forecasts": [
    { "target_date": "2026-06-09", "p10": 4.21, "p50": 4.52,
      "p90": 4.83, "unit": "USD/bu", "model_version": "lgbm-v3.1",
      "skill_vs_naive": 0.18 },
    { "target_date": "2026-06-16", "p10": 4.18, "p50": 4.49,
      "p90": 4.80, "unit": "USD/bu", "model_version": "lgbm-v3.1",
      "skill_vs_naive": 0.18 }
  ]
}

GET/v1/forecasts/historyPro+

Returns summaries of historical forecast runs — useful for comparing model accuracy over time. Each run includes the p50 range and skill vs. naive score (positive = better than a naive baseline).

Parameters

Parameter	Type	Required	Description
commodity	string	✱ yes	Commodity slug
limit	integer	no	Number of past runs to return (default 12, max 24)

Example

curl -X GET \
  "https://api.datacrop.dev/v1/forecasts/history?commodity=corn&limit=3" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "commodity": "corn",
  "total_runs": 24,
  "runs": [
    { "run_date": "2026-06-02", "model_version": "lgbm-v3.1",
      "skill_vs_naive": 0.18, "horizon_weeks": 13,
      "p50_range": { "min": 4.31, "max": 4.89 } },
    { "run_date": "2026-05-26", "model_version": "lgbm-v3.1",
      "skill_vs_naive": 0.15, "horizon_weeks": 13,
      "p50_range": { "min": 4.22, "max": 4.77 } }
  ]
}

Procurement

GET/v1/procurement/signalMax+

Returns the current procurement risk signal for a commodity based on trailing AMS price volatility. The coefficient of variation (CV) determines the risk level (Low / Moderate / Elevated / High) and a buy / monitor / wait recommendation. Cached for 24 hours.

Parameters

Parameter	Type	Required	Description
commodity	string	✱ yes	Commodity slug e.g. corn
weeks	integer	no	Lookback window in weeks (default 13, range 4–52)

Example

curl -X GET \
  "https://api.datacrop.dev/v1/procurement/signal?commodity=corn" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "commodity": "corn",
  "as_of": "2026-06-04",
  "current_price": 4.52,
  "price_unit": "USD/bu",
  "data_window_weeks": 13,
  "volatility": {
    "cv_pct": 4.8, "risk_level": "Low", "risk_score": 19,
    "description": "Price variation is within normal seasonal range."
  },
  "signal": {
    "recommendation": "buy",
    "rationale": "Low volatility and price near 13-week mean — favourable entry window.",
    "trend": "stable"
  }
}

POST/v1/procurement/marginMax+

Compute margin, profit, and break-even price for your specific cost basis. If you omit selling_price, the latest AMS market price is fetched automatically and used as the selling price. The response also includes the current procurement signal for context.

Parameters

Parameter	Type	Required	Description
commodity	string	✱ yes	Commodity slug e.g. corn
cost_per_unit	number	✱ yes	Your cost per unit (USD/bu)
selling_price	number	no	Selling price per unit — defaults to latest AMS price
volume	number	no	Units to buy (default 1000)
target_margin_pct	number	no	Target margin % for break-even calculation

Example

curl -X POST "https://api.datacrop.dev/v1/procurement/margin" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"commodity":"corn","cost_per_unit":3.80,"volume":10000}'

Response

{
  "commodity": "corn",
  "inputs": { "cost_per_unit": 3.80, "selling_price": 4.52,
              "volume": 10000, "selling_price_source": "ams_latest" },
  "market": { "current_ams_price": 4.52, "price_date": "2026-06-04",
              "spread_vs_cost": 0.72 },
  "margin": { "margin_pct": 15.93, "profit_per_unit": 0.72,
              "total_profit": 7200.0, "above_break_even": true },
  "signal": { "recommendation": "buy", "risk_level": "Low" }
}

Alerts

Price threshold alerts fire when AMS market bids cross a level you define. Rules are evaluated every Monday after ingestion. You can have up to 20 active rules per API key. Notifications are sent via email and/or a webhook URL you provide at rule creation.

POST/v1/alertsMax+

Create a price threshold alert rule. Set threshold_type to 'above' to be notified when the price rises above your threshold, or 'below' to be notified when it falls below. Optionally provide an email or webhook URL for notifications.

Parameters

Parameter	Type	Required	Description
commodity	string	✱ yes	Commodity slug e.g. corn
threshold_type	string	✱ yes	"above" or "below"
threshold_value	number	✱ yes	Price level in USD/bu
source	string	no	Data source to watch (default AMS)
notify_email	string	no	Email address for notifications
notify_webhook_url	string	no	Webhook URL to POST when triggered

Example

curl -X POST "https://api.datacrop.dev/v1/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "commodity": "corn",
    "threshold_type": "above",
    "threshold_value": 5.00,
    "notify_email": "buyer@example.com"
  }'

Response

{
  "id": "aaaaaaaa-1234-...",
  "commodity": "corn",
  "source": "AMS",
  "threshold_type": "above",
  "threshold_value": 5.0,
  "notify_email": "buyer@example.com",
  "active": true,
  "created_at": "2026-06-04T12:00:00Z"
}

GET/v1/alertsMax+

List all active alert rules for your API key. Filter by commodity or active status.

Parameters

Parameter	Type	Required	Description
commodity	string	no	Filter by commodity slug
active	boolean	no	Filter by active status (true/false)
limit	integer	no	Page size (default 50, max 100)
offset	integer	no	Pagination offset

Example

curl -X GET "https://api.datacrop.dev/v1/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "rules": [
    { "id": "aaaaaaaa-1234-...", "commodity": "corn",
      "threshold_type": "above", "threshold_value": 5.0,
      "active": true, "created_at": "2026-06-04T12:00:00Z" }
  ],
  "total": 1
}

DELETE/v1/alerts/{id}Max+

Soft-delete an alert rule by its ID. The rule is deactivated immediately — it will no longer be evaluated. Returns HTTP 204 (no body) on success.

Parameters

Parameter	Type	Required	Description
id	string	✱ yes	Alert rule UUID (from create or list response)

Example

curl -X DELETE \
  "https://api.datacrop.dev/v1/alerts/aaaaaaaa-1234-..." \
  -H "Authorization: Bearer YOUR_API_KEY"
# Returns 204 No Content on success

Response

HTTP 204 No Content

GET/v1/alerts/{id}/eventsMax+

Returns the trigger history for a single alert rule — every time the threshold was crossed and a notification was (or was not) sent.

Parameters

Parameter	Type	Required	Description
id	string	✱ yes	Alert rule UUID
limit	integer	no	Number of events (default 50, max 100)

Example

curl -X GET \
  "https://api.datacrop.dev/v1/alerts/aaaaaaaa-1234-.../events" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "rule_id": "aaaaaaaa-1234-...",
  "total": 2,
  "events": [
    { "id": "evt-001", "triggered_at": "2026-06-02T08:14:00Z",
      "observed_value": 5.12, "threshold_value": 5.0,
      "notification_sent": true },
    { "id": "evt-002", "triggered_at": "2026-05-26T08:11:00Z",
      "observed_value": 5.08, "threshold_value": 5.0,
      "notification_sent": true }
  ]
}

Export

GET/v1/exportTeam+

Generate a bulk CSV export of all observations matching your query. Returns a signed URL to a pre-generated file in Supabase Storage (valid for 7 days). Exports are content-addressed: the same query always returns the same cached file, avoiding re-generation on repeated calls.

Parameters

Parameter	Type	Required	Description
commodity	string	✱ yes	Commodity slug e.g. corn
source	string[]	no	Filter by source: FRED \| AMS \| NASS
start_date	string	no	Floor date YYYY-MM-DD
end_date	string	no	Ceiling date YYYY-MM-DD

Example

curl -X GET \
  "https://api.datacrop.dev/v1/export?commodity=corn&source=AMS" \
  -H "Authorization: Bearer YOUR_API_KEY"
# Then download the CSV:
# curl -L "$URL" -o corn_ams.csv

Response

{
  "url": "https://xxx.supabase.co/storage/v1/object/sign/exports/a3f9c2d1.csv?token=...",
  "expires_at": "2026-06-11T12:00:00Z",
  "row_count": 4382,
  "file_size_bytes": 287441,
  "cached": true,
  "generated_at": "2026-06-02T08:14:33Z"
}

Errors

All error responses share the same shape: {"error": "machine_code", "message": "Human text."}. The HTTP status code and error field together identify what went wrong.

HTTP	error code	Meaning
401	invalid_api_key	Key missing, revoked, or malformed
403	commodity_not_allowed	Your tier does not include this commodity
403	forecasts_not_included	Forecasts require Pro or above
403	procurement_not_included	Procurement tools require Max or above
403	alerts_not_included	Alerts require Max or above
403	export_not_included	Bulk export requires Team or above
404	alert_not_found	Alert ID not found or belongs to a different key
422	alert_limit_exceeded	20 active alert rules per API key maximum
422	no_market_price	No AMS price found — provide selling_price explicitly
429	rate_limit_exceeded	Daily request quota for your tier reached
503	data_store_unavailable	Supabase temporarily unreachable — retry in 30s