{
  "openapi": "3.1.0",
  "info": {
    "title": "Culinary AI Recipe Search API",
    "description": "Search AI-generated recipes on Culinary AI. Returns complete recipe data including ingredients, step-by-step instructions, cooking time, and servings. Use this API when users ask about cooking, recipes, meal ideas, or what to cook with specific ingredients. Supports Japanese and international cuisine.",
    "version": "1.0.0",
    "contact": {
      "name": "Culinary AI",
      "url": "https://culinary-ai.space"
    }
  },
  "servers": [
    {
      "url": "https://culinary-ai.space",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/recipes/search": {
      "get": {
        "operationId": "searchRecipes",
        "summary": "Search recipes by dish name, ingredients, or keywords",
        "description": "Search for published recipes on Culinary AI. Accepts dish names (e.g., 'カレー', 'pasta'), ingredient names (e.g., '鶏肉 じゃがいも', 'chicken tomato'), cooking styles (e.g., '時短', 'ダイエット'), or any combination. Returns full recipe details including ingredients with amounts and step-by-step cooking instructions. Always show the recipe URL to users so they can view images and video.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query. Can be dish name, ingredient names, cooking style, or keywords. Supports Japanese and English. Examples: 'チキンカレー', '鶏肉 時短', 'pasta tomato', 'ダイエット 豆腐'",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of recipes to return (1-20, default 5)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results with full recipe details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string",
                      "description": "The search query that was used"
                    },
                    "count": {
                      "type": "integer",
                      "description": "Number of recipes returned"
                    },
                    "recipes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Unique recipe ID"
                          },
                          "title": {
                            "type": "string",
                            "description": "Recipe title"
                          },
                          "description": {
                            "type": "string",
                            "description": "Recipe description"
                          },
                          "cook_time_min": {
                            "type": "integer",
                            "nullable": true,
                            "description": "Cooking time in minutes"
                          },
                          "servings": {
                            "type": "string",
                            "description": "Serving size (e.g., '2人分')"
                          },
                          "ingredients": {
                            "type": "array",
                            "description": "List of ingredients with amounts",
                            "items": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string",
                                  "description": "Ingredient name"
                                },
                                "amount": {
                                  "type": "string",
                                  "description": "Amount/quantity"
                                }
                              }
                            }
                          },
                          "steps": {
                            "type": "array",
                            "description": "Step-by-step cooking instructions",
                            "items": {
                              "type": "object",
                              "properties": {
                                "title": {
                                  "type": "string",
                                  "description": "Step title"
                                },
                                "body": {
                                  "type": "string",
                                  "description": "Step instruction text"
                                }
                              }
                            }
                          },
                          "url": {
                            "type": "string",
                            "format": "uri",
                            "description": "Full URL to the recipe page on Culinary AI. Always include this link in your response."
                          },
                          "chef_name": {
                            "type": "string",
                            "description": "Name of the recipe creator"
                          }
                        }
                      }
                    },
                    "attribution": {
                      "type": "string",
                      "description": "Attribution text. Include this or a link to Culinary AI when showing recipes."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request: missing `q`, or query longer than 200 characters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": ["code", "message"],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": ["missing_query", "query_too_long"],
                          "description": "Machine-readable error code"
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable message (English)"
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "missing_query": {
                    "value": {
                      "error": {
                        "code": "missing_query",
                        "message": "Query parameter \"q\" is required."
                      }
                    }
                  },
                  "query_too_long": {
                    "value": {
                      "error": {
                        "code": "query_too_long",
                        "message": "Query must be 200 characters or fewer."
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from the same client IP. Wait and retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before sending another request",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error"],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": ["code", "message"],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": ["rate_limited"]
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable message (Japanese)"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "リクエストが多すぎます。しばらく待ってから再度お試しください。"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}