{
  "openapi": "3.1.0",
  "info": {
    "title": "Farmland — USDA Land Values & Cash Rents API",
    "version": "1.1.0",
    "description": "Free USDA land data for people and AI agents: average farmland values per acre by state and average cash rents per acre by county, from the USDA NASS annual Land Values and Cash Rents surveys. All endpoints are GET, return JSON, and need no API key. The same data is available as an MCP server (3 tools) at https://land.morningbrief.link/mcp.",
    "contact": {
      "name": "Morning Brief",
      "url": "https://morningbrief.link/docs"
    }
  },
  "servers": [
    {
      "url": "https://land.morningbrief.link"
    }
  ],
  "tags": [
    {
      "name": "Status"
    },
    {
      "name": "Land"
    },
    {
      "name": "MCP"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": [
          "Status"
        ],
        "summary": "Service summary",
        "description": "Service name, version and endpoint list. (Browsers sending Accept: text/html get the HTML landing page instead.)",
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK — JSON object with the requested data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/status": {
      "get": {
        "tags": [
          "Status"
        ],
        "summary": "Coverage & deep health check",
        "description": "Row counts per dataset, year range, distinct states/counties, plus a deep health check against a known anchor row (Illinois land values); returns 503 when the anchor query fails.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK — JSON object with the requested data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/land/values": {
      "get": {
        "tags": [
          "Land"
        ],
        "summary": "Farmland values by state",
        "description": "Average farmland values in USD per acre (USDA NASS Land Values survey), newest year first.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Two-letter state code (case-insensitive), e.g. IL.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "county",
            "in": "query",
            "required": false,
            "description": "County name as stored (uppercase, e.g. HANCOCK). Meaningful for cash rents; land values are state-level rows with no county.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "description": "Survey year, e.g. 2026.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max rows to return (default 1000, max 1000).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK — JSON object with the requested data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/land/rents": {
      "get": {
        "tags": [
          "Land"
        ],
        "summary": "County cash rents",
        "description": "Average cash rents in USD per acre by county (USDA NASS Cash Rents survey), newest year first.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Two-letter state code (case-insensitive), e.g. IL.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "county",
            "in": "query",
            "required": false,
            "description": "County name as stored (uppercase, e.g. HANCOCK). Meaningful for cash rents; land values are state-level rows with no county.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "description": "Survey year, e.g. 2026.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max rows to return (default 1000, max 1000).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK — JSON object with the requested data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "tags": [
          "MCP"
        ],
        "summary": "MCP server endpoint (streamable HTTP)",
        "description": "Model Context Protocol endpoint — 3 tools: get_land_values, get_cash_rents, list_coverage. Send JSON-RPC 2.0 (initialize, tools/list, tools/call). No auth.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "JSON-RPC 2.0 request."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}