{
  "openapi": "3.1.0",
  "info": {
    "title": "Menumigo Public & Agent API",
    "version": "1.2.0",
    "summary": "Read-only public data, tool APIs, and Remote MCP server for Menumigo digital menus and restaurant tools.",
    "description": "An unauthenticated, read-only JSON & MCP API intended for AI agents, assistants, MCP clients, and integrators. It exposes restaurant search, digital menus (categories, items, prices, allergens), food cost calculation, Wi-Fi & review QR payloads, location/cuisine directories, and subscription plan limits. No personal data, account data, or analytics is exposed. Every failure returns a JSON Error object with a stable `error` code, an HTTP `status`, a human-readable `message`, and a `hint` describing the fix \u2014 an HTML error page is never returned from /api. Documentation: https://menumigo.com/developers.",
    "contact": {
      "name": "Menumigo",
      "url": "https://menumigo.com",
      "email": "contact@menumigo.com"
    },
    "license": {
      "name": "Data provided for informational use with attribution to menumigo.com"
    }
  },
  "servers": [
    {
      "url": "https://menumigo.com"
    }
  ],
  "paths": {
    "/api/public": {
      "get": {
        "operationId": "getApiIndex",
        "summary": "Index of the public API: every endpoint, its parameters, and the error format",
        "responses": {
          "200": {
            "description": "API index",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "operationId": "getMcpInfo",
        "summary": "Get Remote Model Context Protocol (MCP) server metadata",
        "responses": {
          "200": {
            "description": "MCP Server Metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "handleMcpJsonRpc",
        "summary": "Handle MCP JSON-RPC 2.0 requests (initialize, tools/list, tools/call, resources/list, resources/read)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "MCP JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/restaurants": {
      "get": {
        "operationId": "searchRestaurants",
        "summary": "Search active public restaurants by query, city, or cuisine",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search query or keyword",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "description": "Filter by city",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cuisine",
            "in": "query",
            "description": "Filter by cuisine",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Max results (1-50, default 20)",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of active matching restaurants",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/restaurants/{slug}": {
      "get": {
        "operationId": "getRestaurantMenu",
        "summary": "Get a restaurant's public profile and full menu",
        "description": "Returns the restaurant profile, contact details, opening hours and the complete menu: every visible category with its items, prices, currency, EU-14 allergen tags, dietary tags and available translations. The slug is the path segment used by the public menu page at https://menumigo.com/{slug}.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Restaurant slug, e.g. \"my-restaurant\".",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Restaurant and menu",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Restaurant"
                }
              }
            }
          },
          "404": {
            "description": "No active restaurant with that slug",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/tools/food-cost": {
      "get": {
        "operationId": "calculateFoodCostGet",
        "summary": "Calculate recipe food cost and suggested pricing via GET parameters",
        "parameters": [
          {
            "name": "cost",
            "in": "query",
            "description": "Total ingredient cost per portion",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "targetMargin",
            "in": "query",
            "description": "Target gross margin percentage (default 70)",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "price",
            "in": "query",
            "description": "Current selling price to calculate actual margin",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Calculated food cost analysis and suggested pricing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "calculateFoodCostPost",
        "summary": "Calculate recipe food cost and suggested pricing with detailed ingredient breakdowns",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculated food cost analysis and suggested pricing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "The request body could not be parsed as JSON (`invalid_json`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/tools/wifi-qr": {
      "get": {
        "operationId": "generateWifiQrPayload",
        "summary": "Generate Wi-Fi connection string and mobile QR setup instructions",
        "parameters": [
          {
            "name": "ssid",
            "in": "query",
            "required": true,
            "description": "Wi-Fi Network Name / SSID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "description": "Wi-Fi Password",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "encryption",
            "in": "query",
            "description": "Encryption: WPA, WEP, or nopass",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "hidden",
            "in": "query",
            "description": "Set to true if SSID is hidden",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wi-Fi connection payload and instructions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Required parameter `ssid` is missing or empty (`invalid_request`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/tools/review-qr": {
      "get": {
        "operationId": "generateReviewQrPayload",
        "summary": "Generate Google Review target URL payload and QR instructions",
        "parameters": [
          {
            "name": "placeId",
            "in": "query",
            "description": "Google Place ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "url",
            "in": "query",
            "description": "Direct Google review URL",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Review QR target URL and payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Neither `placeId` nor `url` was provided (`invalid_request`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/locations": {
      "get": {
        "operationId": "listLocations",
        "summary": "List countries and cities with digital-menu landing pages",
        "responses": {
          "200": {
            "description": "Countries and cities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "countries": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Country"
                      }
                    },
                    "cities": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/City"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/public/cuisines": {
      "get": {
        "operationId": "listCuisines",
        "summary": "List cuisine types with digital-menu landing pages",
        "responses": {
          "200": {
            "description": "Cuisine types",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "cuisines": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Cuisine"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/public/plans": {
      "get": {
        "operationId": "listPlans",
        "summary": "List Menumigo subscription plans and their limits",
        "description": "Authoritative plan and limit data, generated from the same constants the application enforces. A limit of null means unlimited.",
        "responses": {
          "200": {
            "description": "Plans",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pricingUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "signUpUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "trial": {
                      "type": "string"
                    },
                    "note": {
                      "type": "string"
                    },
                    "plans": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Plan"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "status",
          "message",
          "hint"
        ],
        "description": "Returned by every /api endpoint on failure, including requests to paths that do not exist.",
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable machine-readable failure class. Branch on this, not on `message`.",
            "enum": [
              "not_found",
              "invalid_request",
              "invalid_json",
              "method_not_allowed",
              "not_acceptable",
              "rate_limited",
              "internal_error"
            ]
          },
          "status": {
            "type": "integer",
            "description": "Repeated from the status line.",
            "examples": [
              404
            ]
          },
          "message": {
            "type": "string",
            "description": "Human-readable description of what failed."
          },
          "hint": {
            "type": "string",
            "description": "What to change to make the request succeed."
          },
          "documentation": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://menumigo.com/developers"
            ]
          },
          "specification": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://menumigo.com/openapi.json"
            ]
          },
          "availableEndpoints": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "description": "Present on 404s for unknown paths: endpoints worth trying instead."
          }
        }
      },
      "Restaurant": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "currency": {
            "type": "string",
            "examples": [
              "EUR"
            ]
          },
          "defaultLanguage": {
            "type": "string",
            "examples": [
              "en"
            ]
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cuisine": {
            "type": [
              "string",
              "null"
            ]
          },
          "contact": {
            "type": "object",
            "properties": {
              "phone": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "address": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "postalCode": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "latitude": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "longitude": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          },
          "openingHours": {
            "type": [
              "object",
              "null"
            ],
            "description": "Map of day abbreviation to opening range, e.g. { \"mon\": \"09:00-18:00\" }.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "images": {
            "type": "object",
            "properties": {
              "logo": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri"
              },
              "banner": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri"
              }
            }
          },
          "ratings": {
            "type": "object",
            "properties": {
              "google": {
                "$ref": "#/components/schemas/Rating"
              },
              "tripadvisor": {
                "$ref": "#/components/schemas/Rating"
              }
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Category"
            }
          }
        }
      },
      "Rating": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "rating": {
            "type": "number"
          },
          "reviewCount": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "Translations": {
        "type": "object",
        "description": "Keyed by language code, e.g. { \"pt\": { \"name\": \"...\", \"description\": \"...\" } }.",
        "additionalProperties": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "description": {
              "type": "string"
            }
          }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "translations": {
            "$ref": "#/components/schemas/Translations"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MenuItem"
            }
          }
        }
      },
      "MenuItem": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "translations": {
            "$ref": "#/components/schemas/Translations"
          },
          "price": {
            "type": "number"
          },
          "compareAtPrice": {
            "type": [
              "number",
              "null"
            ]
          },
          "currency": {
            "type": "string"
          },
          "imageUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "isAvailable": {
            "type": "boolean"
          },
          "badge": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Dietary/marketing tags, e.g. vegan, vegetarian, gluten-free, spicy."
          },
          "allergens": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "gluten",
                "crustaceans",
                "eggs",
                "fish",
                "peanuts",
                "soy",
                "milk",
                "nuts",
                "celery",
                "mustard",
                "sesame",
                "sulphites",
                "lupin",
                "molluscs"
              ]
            },
            "description": "EU 14 standard allergens present in the item."
          },
          "nutrition": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "variants": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "price": {
                  "type": "number"
                }
              }
            }
          }
        }
      },
      "Country": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "cities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "City": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "countryName": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "diningScene": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Cuisine": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "namePlural": {
            "type": "string"
          },
          "tagline": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Plan": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "free",
              "pro"
            ]
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "priceCurrency": {
            "type": "string",
            "examples": [
              "EUR"
            ]
          },
          "pricing": {
            "type": "object",
            "description": "Amounts in major units (EUR), not cents.",
            "properties": {
              "monthly": {
                "type": "number"
              },
              "yearly": {
                "type": "number"
              },
              "yearlyPerMonth": {
                "type": "number"
              },
              "lifetime": {
                "type": "number"
              }
            }
          },
          "limits": {
            "type": "object",
            "description": "null means unlimited.",
            "properties": {
              "restaurants": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "menuItems": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "languages": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "aiGenerationsPerMonth": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "aiTranslationsPerMonth": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            }
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "proOnlyFeatures": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "canRemoveMenumigoBranding": {
            "type": "boolean"
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Menumigo developer portal",
    "url": "https://menumigo.com/developers"
  }
}
