{ "openapi": "3.1.1", "info": { "title": "Garden Bed Planner API", "version": "1.0.0", "summary": "Lay out square-foot or row beds over three seasons, with sun, rotation, companions and a seed list.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://hearthgardenbeds.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Lay out square-foot or row beds over three seasons, with sun, rotation, companions and a seed list.", "description": "Plan vegetable beds in 30 cm squares or in rows for an early, main and late season. You get plants per crop from spacing data, checks for overlaps, crop rotation and sun hours behind obstacles, traditional companion pairs and the seeds, sets or plants to buy.\n\nMethodology:\n- Square beds are divided into 30 cm squares (columns × rows, rounded down). Plants per square come from our crop table, which follows common square-foot spacings: 16 carrots or radishes, 9 beans, beetroot or onions, 4 lettuces, 1 tomato, cabbage or pepper; large plants need several squares (courgette and squash 9, Brussels sprouts 4). Squares are numbered row by row from 1; plantings without numbers take the first free squares of their season.\n- Row beds: rows run along the bed; plants per row = bed length ÷ spacing in the row; the rows of a season need their row spacing each and must fit into the bed width.\n- Seasons early, main and late are separate layers of the same bed (for example spinach before, beans during and kale after the summer); overlaps are only checked within a season.\n- Sun: direct-sun hours on the 21st of each month at the bed (Hearth Sun Windows geometry: NOAA solar position every 15 minutes, obstacles as sectors with elevation atan(height ÷ distance)); the growing-season mean over April–September (October–March south of the equator) gives full sun (≥ 6 h), part sun (3–6 h) or shade. Crops marked “full sun” warn below 6 h.\n- Rotation follows the RHS groups — legumes, brassicas, potato family, onions and roots; cucurbits, salads, sweetcorn, peppers and herbs fit anywhere — and warns when a group grew in the same bed last year or two years ago. The next years follow the RHS four-year order legumes → brassicas → potatoes → onions and roots.\n- Companion pairs (tomato with basil, carrots with onions or leeks, the “three sisters” …) are shown as gardening tradition with weak evidence, not as a promised effect. Seeds to sow: plants × 1.5 for transplants, × 1.3 for large seeds, × 3 for fine seeds that are thinned, × 1 for tubers, sets and cloves.\n\nSpacing and sun needs are typical values; follow the seed packet for your variety. Companion planting is tradition, not proven science.", "tags": [ "apps" ], "x-mcp-tool": "hearth_garden_beds", "x-owner-app": "hearth", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HearthGardenBedsInput" }, "examples": { "example1": { "summary": "One raised bed over three seasons", "value": { "place": "52.52, 13.40", "year": 2027, "beds": [ { "name": "Bed 1", "width": 120, "length": 240, "method": "square", "lastYear": "potatoes", "twoYearsAgo": "legumes" } ], "plantings": [ { "bed": "Bed 1", "crop": "carrot", "season": "early", "count": 4 }, { "bed": "Bed 1", "crop": "lettuce", "season": "early", "count": 4 }, { "bed": "Bed 1", "crop": "tomato", "season": "main", "count": 4 }, { "bed": "Bed 1", "crop": "basil", "season": "main", "count": 2 }, { "bed": "Bed 1", "crop": "bush-bean", "season": "main", "count": 6 }, { "bed": "Bed 1", "crop": "spinach", "season": "late", "count": 6 } ] } }, "example2": { "summary": "Two beds, one in rows, a hedge to the south", "value": { "place": "48.14, 11.58", "year": 2027, "beds": [ { "name": "Square bed", "width": 120, "length": 120, "method": "square", "lastYear": "brassicas" }, { "name": "Row bed", "width": 150, "length": 400, "method": "rows", "lastYear": "onions-roots" } ], "plantings": [ { "bed": "Square bed", "crop": "zucchini", "season": "main", "count": 9 }, { "bed": "Square bed", "crop": "kale", "season": "main", "count": 4 }, { "bed": "Row bed", "crop": "pea", "season": "early", "count": 2 }, { "bed": "Row bed", "crop": "potato", "season": "main", "count": 2 } ], "obstacles": [ { "bed": "Square bed", "azimuth": 180, "width": 70, "height": 3, "distance": 4 } ] } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HearthGardenBedsResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "HearthGardenBedsInput": { "type": "object", "additionalProperties": false, "properties": { "place": { "title": "Place for sun hours (latitude, longitude, optional)", "description": "Empty = no sun hours.", "type": "string", "maxLength": 80, "default": "" }, "year": { "title": "Season (year of the spring frost)", "type": "integer", "minimum": 2000, "maximum": 2100, "default": 2027 }, "beds": { "title": "Beds", "type": "array", "minItems": 1, "maxItems": 12, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "title": "Bed", "type": "string", "maxLength": 40 }, "width": { "title": "Width (cm)", "type": "number", "minimum": 30, "maximum": 1200, "default": 120 }, "length": { "title": "Length (cm)", "type": "number", "minimum": 30, "maximum": 1200, "default": 240 }, "method": { "title": "Layout", "type": "string", "enum": [ "square", "rows" ], "default": "square" }, "lastYear": { "title": "Grown here last year", "type": "string", "enum": [ "none", "legumes", "brassicas", "potatoes", "onions-roots" ], "default": "none" }, "twoYearsAgo": { "title": "Two years ago", "type": "string", "enum": [ "none", "legumes", "brassicas", "potatoes", "onions-roots" ], "default": "none" } }, "required": [ "name" ] }, "default": [ { "name": "Bed 1", "width": 120, "length": 240, "method": "square", "lastYear": "potatoes", "twoYearsAgo": "legumes" } ] }, "plantings": { "title": "Plantings", "type": "array", "maxItems": 200, "items": { "type": "object", "additionalProperties": false, "properties": { "bed": { "title": "Bed", "type": "string", "maxLength": 40 }, "crop": { "title": "Crop", "type": "string", "enum": [ "tomato", "pepper", "eggplant", "potato", "cucumber", "zucchini", "squash", "melon", "sweetcorn", "bush-bean", "pole-bean", "pea", "broad-bean", "lettuce", "spinach", "chard", "beet", "carrot", "parsnip", "radish", "turnip", "onion", "spring-onion", "garlic", "leek", "cabbage", "broccoli", "cauliflower", "kale", "brussels-sprouts", "kohlrabi", "pak-choi", "rocket", "celery", "fennel", "parsley", "basil", "dill", "coriander", "chives" ], "default": "lettuce" }, "season": { "title": "Season", "type": "string", "enum": [ "early", "main", "late" ], "default": "main" }, "count": { "title": "Squares or rows", "type": "integer", "minimum": 0, "maximum": 400, "default": 1 }, "squares": { "title": "Square numbers (optional, e.g. 1-4, 9)", "type": "string", "maxLength": 200 } }, "required": [ "bed" ] }, "default": [ { "bed": "Bed 1", "crop": "carrot", "season": "early", "count": 4 }, { "bed": "Bed 1", "crop": "lettuce", "season": "early", "count": 4 }, { "bed": "Bed 1", "crop": "tomato", "season": "main", "count": 4 }, { "bed": "Bed 1", "crop": "basil", "season": "main", "count": 2 }, { "bed": "Bed 1", "crop": "bush-bean", "season": "main", "count": 6 }, { "bed": "Bed 1", "crop": "spinach", "season": "late", "count": 6 } ] }, "obstacles": { "title": "Obstacles that shade a bed (optional)", "type": "array", "maxItems": 40, "items": { "type": "object", "additionalProperties": false, "properties": { "bed": { "title": "Bed", "type": "string", "maxLength": 40 }, "azimuth": { "title": "Direction (degrees from north)", "type": "number", "minimum": 0, "maximum": 360, "default": 180 }, "width": { "title": "Angular width (degrees)", "type": "number", "minimum": 0, "maximum": 360, "default": 40 }, "height": { "title": "Height above the bed (m)", "type": "number", "minimum": 0, "maximum": 1000, "default": 4 }, "distance": { "title": "Distance (m)", "type": "number", "minimum": 0.01, "maximum": 10000, "default": 6 } }, "required": [ "bed" ] } } }, "required": [] }, "HearthGardenBedsResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "year", "place", "beds", "seeds", "totals", "issues", "notes" ], "properties": { "year": { "type": "integer" }, "place": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "lat", "lon" ], "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } } }, "beds": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "method", "cols", "rows", "squares", "areaM2", "seasons", "issues", "sun", "rotation" ], "properties": { "name": { "type": "string" }, "method": { "enum": [ "square", "rows" ] }, "cols": { "type": "integer" }, "rows": { "type": "integer" }, "squares": { "type": "integer" }, "areaM2": { "type": "number" }, "seasons": { "type": "object", "additionalProperties": false, "required": [ "early", "main", "late" ], "properties": { "early": { "type": "object", "additionalProperties": false, "required": [ "crops", "usedSquares", "freeSquares", "usedWidthCm" ], "properties": { "crops": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "crop", "squares", "rows", "plants", "areaM2" ], "properties": { "crop": { "type": "string" }, "squares": { "type": "integer" }, "rows": { "type": "integer" }, "plants": { "type": "integer" }, "areaM2": { "type": "number" } } } }, "usedSquares": { "type": "integer" }, "freeSquares": { "type": "integer" }, "usedWidthCm": { "type": "integer" } } }, "main": { "type": "object", "additionalProperties": false, "required": [ "crops", "usedSquares", "freeSquares", "usedWidthCm" ], "properties": { "crops": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "crop", "squares", "rows", "plants", "areaM2" ], "properties": { "crop": { "type": "string" }, "squares": { "type": "integer" }, "rows": { "type": "integer" }, "plants": { "type": "integer" }, "areaM2": { "type": "number" } } } }, "usedSquares": { "type": "integer" }, "freeSquares": { "type": "integer" }, "usedWidthCm": { "type": "integer" } } }, "late": { "type": "object", "additionalProperties": false, "required": [ "crops", "usedSquares", "freeSquares", "usedWidthCm" ], "properties": { "crops": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "crop", "squares", "rows", "plants", "areaM2" ], "properties": { "crop": { "type": "string" }, "squares": { "type": "integer" }, "rows": { "type": "integer" }, "plants": { "type": "integer" }, "areaM2": { "type": "number" } } } }, "usedSquares": { "type": "integer" }, "freeSquares": { "type": "integer" }, "usedWidthCm": { "type": "integer" } } } } }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "bed" ], "properties": { "code": { "type": "string" }, "bed": { "type": "string" }, "season": { "type": "string" }, "crop": { "type": "string" }, "other": { "type": "string" }, "n": { "type": "number" }, "need": { "type": "number" }, "group": { "type": "string" }, "years": { "type": "integer" }, "hours": { "type": "number" }, "note": { "type": "string" } } } }, "sun": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "months", "seasonMean", "sunClass" ], "properties": { "months": { "type": "array", "items": { "type": "number" } }, "seasonMean": { "type": "number" }, "sunClass": { "enum": [ "full", "part", "shade" ] } } }, "rotation": { "type": "object", "additionalProperties": false, "required": [ "thisYear", "suggested", "next", "history" ], "properties": { "thisYear": { "type": [ "string", "null" ] }, "suggested": { "type": [ "string", "null" ] }, "next": { "type": "array", "items": { "type": "string" } }, "history": { "type": "array", "items": { "type": "string" } } } } } } }, "seeds": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "crop", "plants", "kind", "toSow" ], "properties": { "crop": { "type": "string" }, "plants": { "type": "integer" }, "kind": { "enum": [ "transplant", "large", "small", "set" ] }, "toSow": { "type": "integer" } } } }, "totals": { "type": "object", "additionalProperties": false, "required": [ "beds", "areaM2", "plants", "crops" ], "properties": { "beds": { "type": "integer" }, "areaM2": { "type": "number" }, "plants": { "type": "integer" }, "crops": { "type": "integer" } } }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "bed" ], "properties": { "code": { "type": "string" }, "bed": { "type": "string" }, "season": { "type": "string" }, "crop": { "type": "string" }, "other": { "type": "string" }, "n": { "type": "number" }, "need": { "type": "number" }, "group": { "type": "string" }, "years": { "type": "integer" }, "hours": { "type": "number" }, "note": { "type": "string" } } } }, "notes": { "type": "array", "items": { "type": "string" } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }