API Documentation & Reference

Complete REST endpoint specifications, request parameters, rate limits, and JSON schemas for statutory Indian agricultural MSP data.

Zero-Auth & Open CORS

No API keys, tokens, or registration required. Standard Access-Control-Allow-Origin: * headers are sent on every response.

Rate Limiting & Caching

Standard limit is 100 requests per 15 minutes per IP. Static responses are served from global Vercel Edge Serverless cache.

GET/v1/msp/current

Current Mandated MSP Across All Crops

Returns the active statutory Minimum Support Price across all 28 commodities with year-over-year price change calculations, CCEA A2+FL cost benchmarks, and season classifications.

Example Request:

curl -s "https://msp-benchmarks-api.vercel.app/v1/msp/current"

Sample 200 OK Response Envelope:

{
  "success": true,
  "data": [
    {
      "crop_slug": "wheat",
      "crop_name": "Wheat",
      "category": "Cereals",
      "season": "rabi",
      "crop_year": 2026,
      "marketing_season": "RMS 2027-28",
      "fixed_price": 2610,
      "previous_year_price": 2585,
      "absolute_increase": 25,
      "percentage_increase": 0.97,
      "cost_a2_fl": 1264,
      "margin_percent": 106.49,
      "unit": "INR per quintal"
    }
  ],
  "meta": {
    "count": 28,
    "description": "Latest statutory floor prices announced across all mandated commodities.",
    "rate_limit": "100 requests per 15 minutes"
  }
}

GET/v1/msp/crops

List All Commodities Catalog

Returns the complete master catalog of all 28 agricultural commodities with their crop groupings, seasons, and available history counts.

Request Parameters

Parameter	Type	Requirement	Description
`category`	string	Optional	Filter by group: cereals, pulses, oilseeds, commercial
`season`	string	Optional	Filter by crop season: kharif, rabi, commercial

Example Request:

curl -s "https://msp-benchmarks-api.vercel.app/v1/msp/crops?category=pulses"

Sample 200 OK Response Envelope:

{
  "success": true,
  "data": [
    {
      "slug": "tur-arhar",
      "name": "Tur (Arhar)",
      "category": "Pulses",
      "season": "kharif",
      "latest_msp": 8450,
      "latest_crop_year": 2026,
      "latest_marketing_season": "KMS 2026-27",
      "history_years_count": 17
    }
  ],
  "meta": {
    "count": 5,
    "filters": {
      "category": "pulses",
      "season": "all"
    }
  }
}

GET/v1/msp/crops/:slug

Crop History & Parity Timeseries

Retrieves the complete 17-year statutory price history (2010–2026/27) for a specific commodity, including CACP recommended prices, central bonuses, and variety notes.

Request Parameters

Parameter	Type	Requirement	Description
`slug`	string (path)	Required	Standardized commodity identifier (e.g. wheat, gram, mustard, paddy-common)

Example Request:

curl -s "https://msp-benchmarks-api.vercel.app/v1/msp/crops/wheat"

Sample 200 OK Response Envelope:

{
  "success": true,
  "data": {
    "crop_slug": "wheat",
    "crop_name": "Wheat",
    "category": "Cereals",
    "season": "rabi",
    "latest_msp": 2610,
    "total_historical_years": 17,
    "history": [
      {
        "crop_year": 2026,
        "marketing_season": "RMS 2027-28",
        "fixed_price": 2610,
        "recommended_price": 2610,
        "cost_a2_fl": 1264,
        "margin_percent": 106.49
      },
      {
        "crop_year": 2025,
        "marketing_season": "RMS 2026-27",
        "fixed_price": 2585,
        "recommended_price": 2585
      }
    ]
  }
}

GET/v1/msp/seasons/:season

Commodities by Agricultural Season

Filters statutory crop records by marketing season: kharif (monsoon), rabi (winter), or commercial crops.

Request Parameters

Parameter	Type	Requirement	Description
`season`	string (path)	Required	Target agricultural season: kharif, rabi, or commercial

Example Request:

curl -s "https://msp-benchmarks-api.vercel.app/v1/msp/seasons/rabi"

Sample 200 OK Response Envelope:

{
  "success": true,
  "data": [
    {
      "slug": "wheat",
      "name": "Wheat",
      "category": "Cereals",
      "latest_msp": 2610,
      "latest_marketing_season": "RMS 2027-28"
    }
  ],
  "meta": {
    "season": "rabi",
    "count": 7
  }
}

GET/v1/msp/compare

Production Cost (A2+FL) & Margin Analysis

Calculates the statutory return-over-cost guaranteed margin based on official CCEA A2+FL cost projections.

Request Parameters

Parameter	Type	Requirement	Description
`crop`	string (query)	Required	Commodity slug to analyze (e.g. wheat, rapeseed-mustard)
`year`	integer (query)	Optional	Target crop year (defaults to active 2026 year)

Example Request:

curl -s "https://msp-benchmarks-api.vercel.app/v1/msp/compare?crop=rapeseed-mustard&year=2026"

Sample 200 OK Response Envelope:

{
  "success": true,
  "data": {
    "crop_slug": "rapeseed-mustard",
    "crop_name": "Rapeseed & Mustard",
    "crop_year": 2026,
    "marketing_season": "RMS 2027-28",
    "fixed_price": 6200,
    "cost_a2_fl": 3008,
    "absolute_margin": 3192,
    "margin_percent": 106.12,
    "statutory_floor_guarantee": "Swaminathan 1.5x Principle Met"
  }
}

GET/v1/freshness

Dataset Freshness & Upstream Sync

Returns the exact synchronization timestamp, CACP upstream source hash, and latest gazetted release version.

Example Request:

curl -s "https://msp-benchmarks-api.vercel.app/v1/freshness"

Sample 200 OK Response Envelope:

{
  "success": true,
  "data": {
    "dataset_version": "2026.1.0",
    "last_snapshot_at": "2026-10-06T00:00:00.000Z",
    "upstream_source": "Commission for Agricultural Costs & Prices (CACP)",
    "latest_ccea_decision": "RMS 2027-28 (CCEA PIB ID 2060855)",
    "total_records": 476,
    "total_commodities": 28
  }
}

GET/health

Service Health & API Discovery

Returns system operational status, runtime info, and API discovery links for automated crawlers and health checkers.

Example Request:

curl -s "https://msp-benchmarks-api.vercel.app/health"

Sample 200 OK Response Envelope:

{
  "status": "ok",
  "service": "msp-benchmarks-api",
  "version": "1.0.0",
  "timestamp": "2026-10-06T12:00:00.000Z",
  "endpoints": {
    "current": "/v1/msp/current",
    "crops": "/v1/msp/crops",
    "seasons": "/v1/msp/seasons/:season",
    "compare": "/v1/msp/compare",
    "freshness": "/v1/freshness"
  }
}