{
  "openapi": "3.1.0",
  "info": {
    "title": "Aloha Fungi Public Agent API",
    "version": "1.0.0",
    "description": "Read-only API for AI agents and integrations. Search the live Aloha Fungi catalog, inspect a product, get goal-based recommendations and search educational content. Prices and availability must always be read live. Shopping actions that require customer confirmation are exposed separately through MCP. Major versions are encoded in the URL. Deprecated operations advertise Deprecation, Sunset and a policy link before removal.",
    "contact": {
      "name": "Aloha Fungi",
      "url": "https://alohafungi.com/developers",
      "email": "aloha@alohafungi.com"
    },
    "license": {
      "name": "Proprietary",
      "identifier": "LicenseRef-Proprietary"
    }
  },
  "servers": [{ "url": "https://alohafungi.com", "description": "Production" }],
  "externalDocs": {
    "description": "API versioning and deprecation policy",
    "url": "https://alohafungi.com/api-policy.md"
  },
  "x-deprecation-policy": "https://alohafungi.com/api-policy.md",
  "security": [],
  "tags": [
    { "name": "Discovery", "description": "API and capability discovery." },
    { "name": "Catalog", "description": "Live product catalog and availability." },
    {
      "name": "Recommendations",
      "description": "Deterministic product matching by declared goal."
    },
    { "name": "Knowledge", "description": "Search Aloha Fungi educational sources." }
  ],
  "paths": {
    "/api/v1": {
      "get": {
        "operationId": "discoverApi",
        "summary": "Discover public agent capabilities",
        "description": "Returns stable links to the OpenAPI document, MCP server and every public API resource.",
        "tags": ["Discovery"],
        "responses": {
          "200": {
            "description": "Service discovery document.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryResponse" } }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/products": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Search the live product catalog",
        "description": "Returns at most 10 products matching a phrase. Omit q or pass an empty value to list the first 10 products. Prices are expressed in PLN and availability is live at response time.",
        "tags": ["Catalog"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Product name, mushroom species, form or another catalog phrase.",
            "schema": { "type": "string", "maxLength": 120 },
            "example": "reishi"
          }
        ],
        "responses": {
          "200": {
            "description": "Matching products from the live catalog.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductListResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    },
    "/api/v1/products/{handle}": {
      "get": {
        "operationId": "getProduct",
        "summary": "Get a product and its variants",
        "description": "Returns current variants, SKUs, prices, availability and available educational product content for one canonical handle.",
        "tags": ["Catalog"],
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "description": "Canonical product handle returned by searchProducts.",
            "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" },
            "example": "reishi"
          }
        ],
        "responses": {
          "200": {
            "description": "Product details from the live catalog.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductDetailResponse" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    },
    "/api/v1/recommendations": {
      "get": {
        "operationId": "recommendProducts",
        "summary": "Match products to a declared goal",
        "description": "Returns a deterministic catalog match for one supported goal. This is product navigation, not medical advice or diagnosis.",
        "tags": ["Recommendations"],
        "parameters": [
          {
            "name": "goal",
            "in": "query",
            "required": true,
            "description": "Customer-declared shopping goal in Polish.",
            "schema": {
              "type": "string",
              "enum": ["sen", "skupienie", "energia", "odpornosc", "spokoj", "dlugowiecznosc"]
            },
            "example": "sen"
          }
        ],
        "responses": {
          "200": {
            "description": "Products mapped to the requested goal.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RecommendationResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    },
    "/api/v1/knowledge": {
      "get": {
        "operationId": "searchKnowledge",
        "summary": "Search educational Aloha Fungi sources",
        "description": "Searches published blog posts, product education and mushroom guides. Every result includes its source URL.",
        "tags": ["Knowledge"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Non-empty educational search phrase.",
            "schema": { "type": "string", "minLength": 1, "maxLength": 200 },
            "example": "beta-glukany"
          }
        ],
        "responses": {
          "200": {
            "description": "Matching educational sources.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeResponse" } }
            }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/UpstreamUnavailable" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "InvalidRequest": {
        "description": "The request is missing a required value or uses an unsupported value.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      },
      "NotFound": {
        "description": "The requested product handle does not exist in the current catalog.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      },
      "RateLimited": {
        "description": "The client exceeded the public fixed-window request quota.",
        "headers": {
          "Retry-After": {
            "description": "Seconds until the client should retry.",
            "schema": { "type": "integer", "minimum": 1 }
          },
          "RateLimit-Limit": {
            "description": "Maximum requests in the current window.",
            "schema": { "type": "integer", "minimum": 1 }
          },
          "RateLimit-Remaining": {
            "description": "Requests remaining in the current window.",
            "schema": { "type": "integer", "minimum": 0 }
          },
          "RateLimit-Reset": {
            "description": "Seconds until the current window resets.",
            "schema": { "type": "integer", "minimum": 1 }
          }
        },
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      },
      "UpstreamUnavailable": {
        "description": "The live catalog is temporarily unavailable. The client should retry and must not invent price or availability.",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      }
    },
    "schemas": {
      "DiscoveryResponse": {
        "type": "object",
        "required": ["data"],
        "properties": { "data": { "type": "object", "additionalProperties": true } }
      },
      "ProductSummary": {
        "type": "object",
        "additionalProperties": false,
        "required": ["title", "handle", "url", "minPrice", "availability"],
        "properties": {
          "title": { "type": "string" },
          "handle": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "minPrice": {
            "type": ["number", "null"],
            "minimum": 0,
            "description": "Lowest current price in PLN."
          },
          "availability": { "type": "string", "description": "Current catalog availability state." }
        }
      },
      "ProductListResponse": {
        "type": "object",
        "required": ["data"],
        "properties": {
          "data": {
            "type": "array",
            "maxItems": 10,
            "items": { "$ref": "#/components/schemas/ProductSummary" }
          }
        }
      },
      "Variant": {
        "type": "object",
        "description": "Live product variant with its current price and stock state.",
        "additionalProperties": false,
        "required": ["variantId", "title", "forma", "linia", "sku", "price", "available"],
        "properties": {
          "variantId": { "type": "string" },
          "title": { "type": "string" },
          "forma": { "type": ["string", "null"] },
          "linia": {
            "type": ["string", "null"],
            "enum": ["PRIME", "LONGEVITY", null]
          },
          "sku": { "type": ["string", "null"] },
          "price": {
            "type": ["number", "null"],
            "minimum": 0,
            "description": "Current price in PLN."
          },
          "available": { "type": "boolean" }
        }
      },
      "ProductDetail": {
        "type": "object",
        "additionalProperties": false,
        "required": ["title", "handle", "url", "variants"],
        "properties": {
          "title": { "type": "string" },
          "handle": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } },
          "content": {
            "type": "object",
            "additionalProperties": true,
            "description": "Optional educational content available for this product."
          }
        }
      },
      "ProductDetailResponse": {
        "type": "object",
        "required": ["data"],
        "properties": { "data": { "$ref": "#/components/schemas/ProductDetail" } }
      },
      "Recommendation": {
        "type": "object",
        "additionalProperties": false,
        "required": ["title", "handle", "url", "minPrice", "availability", "goals"],
        "properties": {
          "title": { "type": "string" },
          "handle": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "minPrice": {
            "type": ["number", "null"],
            "minimum": 0,
            "description": "Lowest current price in PLN."
          },
          "availability": { "type": "string" },
          "goals": { "type": "array", "items": { "type": "string" } }
        }
      },
      "RecommendationResponse": {
        "type": "object",
        "required": ["data"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" } }
        }
      },
      "KnowledgeItem": {
        "type": "object",
        "additionalProperties": true,
        "required": ["title", "description", "url", "source"],
        "properties": {
          "title": { "type": "string" },
          "description": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "source": { "type": "string", "enum": ["blog", "pdp", "guide"] }
        }
      },
      "KnowledgeResponse": {
        "type": "object",
        "required": ["data"],
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeItem" } }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": ["code", "message", "resolution", "docs"],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "INVALID_REQUEST",
                  "NOT_FOUND",
                  "METHOD_NOT_ALLOWED",
                  "RATE_LIMITED",
                  "UPSTREAM_UNAVAILABLE",
                  "INTERNAL_ERROR"
                ]
              },
              "message": { "type": "string" },
              "resolution": { "type": "string" },
              "docs": { "type": "string", "format": "uri" }
            }
          }
        }
      }
    }
  }
}