{
  "openapi": "3.1.0",
  "info": {
    "title": "FoodCourts API",
    "description": "AI-native restaurant discovery and ordering platform. Search restaurants semantically, filter by cuisine and fulfillment, and place orders via x402 protocol.",
    "version": "1.0.0",
    "contact": {
      "name": "FoodCourts Support",
      "email": "corey@prospectbutcher.co",
      "url": "https://foodcourts.ai"
    }
  },
  "servers": [
    {
      "url": "https://foodcourts.ai",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/search": {
      "post": {
        "operationId": "searchRestaurants",
        "summary": "Search restaurants",
        "description": "Search for restaurants using natural language queries, filters, and location. Returns semantically ranked results when a query is provided.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              },
              "examples": {
                "semantic_search": {
                  "summary": "Semantic search for Thai food",
                  "value": {
                    "location": { "zipcode": "11238" },
                    "query": "spicy Thai noodles",
                    "limit": 5
                  }
                },
                "filtered_search": {
                  "summary": "Filter by cuisine and delivery",
                  "value": {
                    "location": { "zipcode": "11238" },
                    "filters": {
                      "cuisine": ["indian", "thai"],
                      "fulfillment": ["delivery"],
                      "minRating": 4.0
                    },
                    "limit": 10
                  }
                },
                "coords_search": {
                  "summary": "Search by coordinates",
                  "value": {
                    "location": { "coords": [40.6782, -73.9442] },
                    "query": "healthy lunch",
                    "limit": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Location required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocationRequiredResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "searchRestaurantsSimple",
        "summary": "Simple restaurant search",
        "description": "Simplified GET endpoint for basic searches. Use POST for full capabilities.",
        "parameters": [
          {
            "name": "zipcode",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "5-digit US zipcode",
            "example": "11238"
          },
          {
            "name": "q",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Natural language search query",
            "example": "spicy thai food"
          },
          {
            "name": "cuisine",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Comma-separated cuisine types",
            "example": "thai,indian"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 10, "maximum": 50 },
            "description": "Maximum results to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "required": ["location"],
        "properties": {
          "location": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "zipcode": { "type": "string", "pattern": "^\\d{5}$" }
                },
                "required": ["zipcode"]
              },
              {
                "type": "object",
                "properties": {
                  "coords": {
                    "type": "array",
                    "items": { "type": "number" },
                    "minItems": 2,
                    "maxItems": 2,
                    "description": "[latitude, longitude]"
                  }
                },
                "required": ["coords"]
              },
              {
                "type": "object",
                "properties": {
                  "city": { "type": "string" }
                },
                "required": ["city"]
              }
            ],
            "description": "Location to search. Required."
          },
          "query": {
            "type": "string",
            "description": "Natural language search query. When provided, results are ranked by semantic similarity.",
            "example": "healthy vegetarian lunch"
          },
          "filters": {
            "type": "object",
            "properties": {
              "cuisine": {
                "type": "array",
                "items": { "type": "string" },
                "description": "Cuisine types to include",
                "example": ["indian", "thai", "mexican"]
              },
              "fulfillment": {
                "type": "array",
                "items": { "type": "string", "enum": ["pickup", "delivery"] },
                "description": "Required fulfillment methods"
              },
              "openNow": {
                "type": "boolean",
                "description": "Only return currently open restaurants"
              },
              "minRating": {
                "type": "number",
                "minimum": 0,
                "maximum": 5,
                "description": "Minimum rating threshold"
              }
            }
          },
          "limit": {
            "type": "integer",
            "default": 10,
            "minimum": 1,
            "maximum": 50,
            "description": "Maximum results to return"
          },
          "offset": {
            "type": "integer",
            "default": 0,
            "minimum": 0,
            "description": "Number of results to skip (for pagination)"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["ok"] },
          "results": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Restaurant" }
          },
          "count": {
            "type": "integer",
            "description": "Number of results in this response"
          },
          "total": {
            "type": "integer",
            "description": "Total matching results"
          },
          "coverage": {
            "type": "object",
            "properties": {
              "searchedArea": { "type": "string" },
              "nearbyZipcodes": {
                "type": "array",
                "items": { "type": "string" }
              }
            }
          },
          "timing": {
            "type": "object",
            "properties": {
              "searchMs": { "type": "integer" },
              "embeddingMs": { "type": "integer" }
            }
          }
        }
      },
      "LocationRequiredResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["location_required"] },
          "message": { "type": "string" },
          "options": {
            "type": "object",
            "properties": {
              "zipcode": { "type": "string" },
              "coords": { "type": "string" },
              "city": { "type": "string" }
            }
          },
          "availableCoverage": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Zipcodes where we have restaurant coverage"
          }
        }
      },
      "Restaurant": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "cuisines": {
            "type": "array",
            "items": { "type": "string" }
          },
          "rating": { "type": "number" },
          "reviewCount": { "type": "integer" },
          "address": {
            "type": "object",
            "properties": {
              "formatted": { "type": "string" },
              "city": { "type": "string" },
              "state": { "type": "string" },
              "zip": { "type": "string" }
            }
          },
          "location": {
            "type": "object",
            "properties": {
              "lat": { "type": "number" },
              "lng": { "type": "number" }
            }
          },
          "fulfillment": {
            "type": "object",
            "properties": {
              "methods": {
                "type": "array",
                "items": { "type": "string", "enum": ["pickup", "delivery"] }
              },
              "deliveryFee": { "type": "number" }
            }
          },
          "hours": {
            "type": "object",
            "properties": {
              "timezone": { "type": "string" },
              "schedule": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "day": { "type": "string" },
                    "open": { "type": "string" },
                    "close": { "type": "string" },
                    "closed": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "photos": {
            "type": "array",
            "items": { "type": "string", "format": "uri" }
          },
          "ordering": {
            "type": "object",
            "properties": {
              "url": { "type": "string", "format": "uri" }
            },
            "description": "Online ordering link for this restaurant"
          },
          "qualityScore": {
            "type": "integer",
            "description": "Internal quality ranking (0-100)"
          },
          "distance": {
            "type": "number",
            "description": "Distance in miles (only when coords provided)"
          }
        }
      }
    }
  }
}