{
  "openapi": "3.1.0",
  "info": {
    "title": "Infuse private recipe API",
    "version": "1.0.0",
    "description": "Use an owner-issued expiring recipe key. No publishing, account access, or agent token issuance with this key. Do not send raw conversations as saved recipes. Saving a final structured recipe is explicitly private."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "security": [
    {
      "recipeKey": []
    }
  ],
  "paths": {
    "/api/recipes": {
      "get": {
        "operationId": "findRecipes",
        "summary": "Search your private collection; follow pagination until all results are retrieved.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "All query words must appear in recipe text; not a natural-language reasoning endpoint."
          },
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Repeat tag for AND matching. Exact normalized labels, including hidden attributes. Dietary labels may be supplied, not verified."
          },
          {
            "name": "maxMinutes",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Unknown times are excluded."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "Offset into matching results."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": "Maximum returned recipes."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching recipes, total count, pagination, and recurring collection categories.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "recipes": {
                      "type": "array",
                      "items": {
                        "allOf": [
                          {
                            "$ref": "#/components/schemas/RecipeContent"
                          },
                          {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "version": {
                                "type": "integer"
                              },
                              "visibility": {
                                "const": "private"
                              }
                            }
                          }
                        ]
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tag": {
                            "type": "string"
                          },
                          "count": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid, revoked, or expired key"
          },
          "403": {
            "description": "Read permission required"
          },
          "422": {
            "description": "Invalid filter"
          }
        }
      },
      "post": {
        "operationId": "saveRecipe",
        "summary": "Save a structured recipe privately. Requires recipes:write. Owner and visibility cannot be selected by the caller.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{1,100}$"
            },
            "description": "Use a stable key for retrying the same create request. Changed content with the same key returns 409."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecipeContent"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Recipe saved, including id and version"
          },
          "200": {
            "description": "Original create response replayed"
          },
          "409": {
            "description": "Key reused with different content"
          },
          "422": {
            "description": "Invalid recipe or collection quota"
          },
          "403": {
            "description": "Write permission required"
          }
        }
      }
    },
    "/api/recipes/draft": {
      "post": {
        "operationId": "draftRecipe",
        "summary": "Propose a transient draft from a final recipe or, when configured, a recipe conversation. Requires recipes:write. Never saves or publishes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 30000
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "recipe",
                      "conversation"
                    ],
                    "default": "recipe",
                    "description": "Conversation extraction is an explicit AI-provider opt-in. Text is sent to the configured extraction provider."
                  },
                  "clarification": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Answer to the previous focused question; resend the original conversation text."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "draft, warnings, and (for conversations) question. A non-null question requires clarification before treating the draft as final. Nothing is saved."
          },
          "422": {
            "description": "Invalid text"
          },
          "429": {
            "description": "Durable owner/global import budget or queue limit reached."
          },
          "502": {
            "description": "Model output was malformed or incomplete; do not save it."
          },
          "503": {
            "description": "Extraction is unconfigured, unavailable, or timed out. Final-recipe and manual input remain available."
          }
        }
      }
    },
    "/api/recipes/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "operationId": "getRecipe",
        "summary": "Read a private recipe and its immutable revisions. Requires recipes:read.",
        "responses": {
          "200": {
            "description": "Object containing recipe and revisions"
          },
          "404": {
            "description": "No accessible recipe with that id"
          }
        }
      },
      "put": {
        "operationId": "reviseRecipe",
        "summary": "Save a new version without overwriting history. Requires recipes:write. Reload on 409.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/RecipeContent"
                  },
                  {
                    "type": "object",
                    "required": [
                      "version"
                    ],
                    "properties": {
                      "version": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "Current version the edit is based on."
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "New current recipe revision"
          },
          "409": {
            "description": "Stale version; reload before merging changes"
          },
          "404": {
            "description": "No accessible recipe with that id"
          },
          "422": {
            "description": "Invalid recipe or quota"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "recipeKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Owner creates a connection in Connect your AI. recipes:read retrieves; recipes:write saves/updates. Max lifetime 30 days; revoke immediately from the UI."
      }
    },
    "schemas": {
      "RecipeContent": {
        "type": "object",
        "required": [
          "title",
          "ingredients",
          "steps"
        ],
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "ingredients": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1000
            }
          },
          "steps": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1000
            }
          },
          "tags": {
            "type": "array",
            "maxItems": 30,
            "items": {
              "type": "string",
              "maxLength": 60
            }
          },
          "totalMinutes": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 10080
          },
          "servings": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 1000
          },
          "notes": {
            "type": "string",
            "maxLength": 4000,
            "description": "Private personal notes; never published automatically."
          },
          "source": {
            "type": "string",
            "maxLength": 120,
            "description": "Supplied label, not verified platform provenance."
          }
        }
      }
    }
  }
}