{
  "openapi": "3.1.0",
  "info": {
    "title": "ProperMasala public recipe API",
    "version": "1.0.0",
    "description": "Public read-only static JSON exports of published recipes. No authentication, API key, account, or payment is required. Fetch the catalog and filter its recipes locally; query parameters and pagination are not supported. Unspecified metadata is omitted, never represented as zero or null. Source attribution and licenses apply per recipe, not to the entire API."
  },
  "servers": [{ "url": "https://propermasala.com" }],
  "security": [],
  "externalDocs": {
    "description": "Agent workflows, attribution, and access alternatives",
    "url": "https://propermasala.com/agent-instructions.md"
  },
  "paths": {
    "/api/recipes.json": {
      "get": {
        "operationId": "listRecipes",
        "summary": "Get the complete recipe catalog",
        "description": "Returns all published recipe summaries in one document. Filter the recipes array locally by title, description, cuisine slug, category, tags, or ingredients. Each record links to its full JSON, Markdown, and canonical page.",
        "responses": {
          "200": {
            "description": "Complete recipe catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["recipes"],
                  "properties": {
                    "recipes": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/RecipeSummary" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/recipes/{id}.json": {
      "get": {
        "operationId": "getRecipe",
        "summary": "Get a full recipe by exact catalog ID",
        "description": "Includes ingredient groups, recipe metadata, and the full Markdown body. When methodInBody is true, read the method from body; otherwise steps provides the structured method when present. Retain source attribution, license, and adaptation notes when reusing imported content.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Exact ID from the recipe catalog, without a .json suffix.",
            "schema": { "type": "string", "minLength": 1 },
            "example": "chicken-karahi"
          }
        ],
        "responses": {
          "200": {
            "description": "Full published recipe",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Recipe" }
              }
            }
          },
          "404": {
            "description": "No published recipe has this ID. The hosting platform may return an HTML error page; do not assume a JSON error body."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "IngredientGroup": {
        "type": "object",
        "required": ["items"],
        "properties": {
          "group": { "type": "string", "description": "Optional ingredient group heading." },
          "items": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Published ingredient quantities and units as text; preserve their wording and order."
          }
        }
      },
      "RecipeSource": {
        "type": "object",
        "description": "Present only for recipes with an imported-source record. Its license covers the source recipe text, not all site content or generated illustrations.",
        "required": ["name", "url", "author", "authorType", "license", "licenseUrl", "revisionUrl"],
        "properties": {
          "name": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "author": { "type": "string" },
          "authorType": { "type": "string", "enum": ["Person", "Organization"] },
          "authorUrl": { "type": "string", "format": "uri" },
          "license": { "type": "string" },
          "licenseUrl": { "type": "string", "format": "uri" },
          "revisionUrl": { "type": "string", "format": "uri" }
        }
      },
      "RecipeSummary": {
        "type": "object",
        "required": ["id", "title", "description", "cuisine", "cuisineLabel", "category", "tags", "url", "markdownUrl", "apiUrl", "ingredients", "imageGenerated"],
        "properties": {
          "id": { "type": "string", "description": "Stable recipe slug used in document URLs." },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "cuisine": { "type": "string", "description": "Cuisine slug, such as srilankan or pakistani." },
          "cuisineLabel": { "type": "string", "description": "Human-readable cuisine name." },
          "category": {
            "type": "string",
            "enum": ["biryani", "curry", "street-food", "dessert", "breakfast", "bread", "rice", "seafood", "drinks", "snacks", "main", "side", "sauce", "seasoning", "salad", "soup", "pasta"]
          },
          "tags": { "type": "array", "items": { "type": "string" } },
          "url": { "type": "string", "format": "uri", "description": "Canonical recipe page URL; use this for citations." },
          "markdownUrl": { "type": "string", "format": "uri" },
          "apiUrl": { "type": "string", "format": "uri" },
          "ingredients": { "type": "array", "items": { "$ref": "#/components/schemas/IngredientGroup" } },
          "prepTime": { "type": "integer", "minimum": 0, "description": "Minutes, omitted when unspecified." },
          "cookTime": { "type": "integer", "minimum": 0, "description": "Minutes, omitted when unspecified." },
          "totalTime": { "type": "integer", "minimum": 0, "description": "Sum of prepTime and cookTime in minutes; present only when both are supplied. Additional waiting may be excluded: read timingNote for rising, marinating, cooling or fermentation." },
          "timingEstimated": { "type": "boolean", "description": "True when published timings include editorial estimates. Read timingNote for assumptions and excluded cooling or resting." },
          "timingNote": { "type": "string", "description": "Published timing basis and any extra passive cooling, chilling or resting time." },
          "servings": { "type": "integer", "minimum": 1, "description": "Omitted when unspecified." },
          "recipeYield": { "type": "string", "description": "Published yield wording, omitted when unspecified." },
          "difficulty": { "type": "string", "enum": ["easy", "medium", "hard"], "description": "Omitted when unspecified." },
          "imageGenerated": { "type": "boolean", "description": "Whether the recipe hero illustration is AI-generated. An illustration is not evidence of kitchen testing." },
          "source": { "$ref": "#/components/schemas/RecipeSource" }
        }
      },
      "Recipe": {
        "allOf": [
          { "$ref": "#/components/schemas/RecipeSummary" },
          {
            "type": "object",
            "required": ["publishDate", "methodInBody", "body"],
            "properties": {
              "publishDate": { "type": "string", "format": "date-time" },
              "updatedDate": { "type": "string", "format": "date-time" },
              "steps": { "type": "array", "items": { "type": "string" }, "description": "Ordered structured method when published; optional." },
              "methodInBody": { "type": "boolean", "description": "When true, the published method is in body rather than a separate steps array." },
              "body": { "type": "string", "description": "Full recipe Markdown body with local links resolved to absolute public URLs. Read alongside ingredients, steps, and source metadata." }
            }
          }
        ]
      }
    }
  }
}
