{
  "openapi": "3.0.3",
  "info": {
    "title": "ShishApp Public API",
    "version": "1.0.1",
    "description": "Commercial Public API for third-party server-to-server integrations.\n\n## Authentication\n\nAll endpoints require the `X-API-Key` header. Never send the key as a query parameter, in the request body, or from a public frontend.\n\n## Capability tiers\n\n| Tier | Plans | Capabilities |\n| ---- | ----- | ------------ |\n| `.basic` | Starter | `catalog.brands.read`, `catalog.tobaccos.basic.read` |\n| `.enriched` | Pro, Business | All `.basic` plus `catalog.flavors.read`, `catalog.tobaccos.enriched.read`, `catalog.search` |\n\n`.basic` and `.enriched` are capability levels, not API versions. Authorization checks capabilities, not plan names.\n\n## Rate limits\n\nLimits apply per subscription (shared across API keys). Exceeding the limit returns **429** with rate-limit headers. There is no monthly request quota.\n\n| Plan | Requests per minute |\n| ---- | ------------------: |\n| Starter | 10 |\n| Pro | 60 |\n| Business | 300 |\n\n## Errors\n\nDocumented responses include **400** (validation), **401** (invalid/missing key), **402** (billing blocked), **403** (missing capability), and **429** (rate limit).\n\nSuccessful and 429 responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. 429 also includes `Retry-After`.\n"
  },
  "components": {
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Commercial Public API key (ska_v1_…)"
      }
    },
    "schemas": {}
  },
  "paths": {
    "/api/public/v1/brands": {
      "get": {
        "operationId": "listBrands",
        "summary": "List brands (.basic)",
        "tags": [
          "brand"
        ],
        "description": "Returns all tobacco brands in the catalog.\n\n**Capability:** `catalog.brands.read` (`.basic` — Starter+)\n\n```bash\ncurl -i -H \"X-API-Key: $API_KEY\" \\\n  \"https://api.shishapp.es/api/public/v1/brands\"\n```\n",
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-capabilityTier": "basic",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "brands": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "brandId": {
                            "type": "string",
                            "format": "uuid",
                            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                          },
                          "name": {
                            "type": "string"
                          },
                          "logoUrl": {
                            "nullable": true,
                            "type": "string"
                          }
                        },
                        "required": [
                          "brandId",
                          "name",
                          "logoUrl"
                        ],
                        "additionalProperties": false
                      },
                      "description": "Catalog brands"
                    }
                  },
                  "required": [
                    "brands"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "brands": [
                    {
                      "brandId": "11111111-1111-4111-8111-111111111111",
                      "name": "Example Brand",
                      "logoUrl": null
                    }
                  ]
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer",
                  "example": 10
                },
                "description": "Maximum requests per minute for this subscription."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer",
                  "example": 9
                },
                "description": "Remaining requests in the current minute window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer",
                  "example": 1710000060
                },
                "description": "Unix timestamp (seconds) when the current window resets."
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "Invalid or missing API key."
                }
              }
            }
          },
          "402": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "requiredRoles": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "challenge": {
                      "type": "string"
                    },
                    "maskedEmail": {
                      "type": "string"
                    },
                    "resendAvailableAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "429": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "retryAfter": {
                      "type": "integer",
                      "exclusiveMinimum": true,
                      "maximum": 9007199254740991
                    },
                    "resendAvailableAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "code": "RATE_LIMIT_EXCEEDED",
                  "message": "Rate limit exceeded for this subscription."
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer",
                  "example": 10
                },
                "description": "Maximum requests per minute for this subscription."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer",
                  "example": 9
                },
                "description": "Remaining requests in the current minute window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer",
                  "example": 1710000060
                },
                "description": "Unix timestamp (seconds) when the current window resets."
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "example": 42
                },
                "description": "Seconds until the client should retry (429 only)."
              }
            }
          },
          "500": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/brands/{brandId}/tobaccos": {
      "get": {
        "operationId": "listBrandTobaccos",
        "summary": "List tobaccos by brand (.basic)",
        "tags": [
          "tobacco"
        ],
        "description": "Returns tobacco products for a brand (basic product fields).\n\n**Capability:** `catalog.tobaccos.basic.read` (`.basic` — Starter+)\n\n```bash\ncurl -i -H \"X-API-Key: $API_KEY\" \\\n  \"https://api.shishapp.es/api/public/v1/brands/{brandId}/tobaccos\"\n```\n",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            "example": "11111111-1111-4111-8111-111111111111",
            "in": "path",
            "name": "brandId",
            "required": true,
            "description": "Brand UUID"
          }
        ],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-capabilityTier": "basic",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "productId": {
                            "type": "string",
                            "format": "uuid",
                            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                          },
                          "brandId": {
                            "type": "string",
                            "format": "uuid",
                            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                          },
                          "name": {
                            "type": "string"
                          },
                          "displayName": {
                            "nullable": true,
                            "type": "string"
                          },
                          "variants": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "grams": {
                                  "type": "integer",
                                  "exclusiveMinimum": true,
                                  "maximum": 5000
                                }
                              },
                              "required": [
                                "grams"
                              ],
                              "additionalProperties": false
                            },
                            "description": "Available grams"
                          }
                        },
                        "required": [
                          "productId",
                          "brandId",
                          "name",
                          "displayName",
                          "variants"
                        ],
                        "additionalProperties": false
                      },
                      "description": "Products (Tier 1: core catalog without flavors)"
                    }
                  },
                  "required": [
                    "products"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer",
                  "example": 10
                },
                "description": "Maximum requests per minute for this subscription."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer",
                  "example": 9
                },
                "description": "Remaining requests in the current minute window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer",
                  "example": 1710000060
                },
                "description": "Unix timestamp (seconds) when the current window resets."
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "Invalid or missing API key."
                }
              }
            }
          },
          "402": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "requiredRoles": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "challenge": {
                      "type": "string"
                    },
                    "maskedEmail": {
                      "type": "string"
                    },
                    "resendAvailableAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "404": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "429": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "retryAfter": {
                      "type": "integer",
                      "exclusiveMinimum": true,
                      "maximum": 9007199254740991
                    },
                    "resendAvailableAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "code": "RATE_LIMIT_EXCEEDED",
                  "message": "Rate limit exceeded for this subscription."
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer",
                  "example": 10
                },
                "description": "Maximum requests per minute for this subscription."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer",
                  "example": 9
                },
                "description": "Remaining requests in the current minute window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer",
                  "example": 1710000060
                },
                "description": "Unix timestamp (seconds) when the current window resets."
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "example": 42
                },
                "description": "Seconds until the client should retry (429 only)."
              }
            }
          },
          "500": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/flavors": {
      "get": {
        "operationId": "listFlavors",
        "summary": "List flavor tags (.enriched)",
        "tags": [
          "flavors"
        ],
        "description": "Returns all flavor tags.\n\n**Capability:** `catalog.flavors.read` (`.enriched` — Pro / Business)\n\n```bash\ncurl -i -H \"X-API-Key: $API_KEY\" \\\n  \"https://api.shishapp.es/api/public/v1/flavors\"\n```\n",
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-capabilityTier": "enriched",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "flavors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "names": {
                            "type": "object",
                            "additionalProperties": {
                              "type": "string"
                            },
                            "description": "Localized flavor names keyed by locale (es, en, …)"
                          },
                          "color": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "common",
                              "premium"
                            ]
                          }
                        },
                        "required": [
                          "slug",
                          "name",
                          "names",
                          "color",
                          "type"
                        ],
                        "additionalProperties": false
                      },
                      "description": "Flavor tags associated to products"
                    }
                  },
                  "required": [
                    "flavors"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer",
                  "example": 10
                },
                "description": "Maximum requests per minute for this subscription."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer",
                  "example": 9
                },
                "description": "Remaining requests in the current minute window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer",
                  "example": 1710000060
                },
                "description": "Unix timestamp (seconds) when the current window resets."
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "Invalid or missing API key."
                }
              }
            }
          },
          "402": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "requiredRoles": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "challenge": {
                      "type": "string"
                    },
                    "maskedEmail": {
                      "type": "string"
                    },
                    "resendAvailableAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "429": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "retryAfter": {
                      "type": "integer",
                      "exclusiveMinimum": true,
                      "maximum": 9007199254740991
                    },
                    "resendAvailableAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "code": "RATE_LIMIT_EXCEEDED",
                  "message": "Rate limit exceeded for this subscription."
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer",
                  "example": 10
                },
                "description": "Maximum requests per minute for this subscription."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer",
                  "example": 9
                },
                "description": "Remaining requests in the current minute window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer",
                  "example": 1710000060
                },
                "description": "Unix timestamp (seconds) when the current window resets."
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "example": 42
                },
                "description": "Seconds until the client should retry (429 only)."
              }
            }
          },
          "500": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/tobaccos/search": {
      "get": {
        "operationId": "searchTobaccos",
        "summary": "Search tobaccos (.enriched)",
        "tags": [
          "tobacco"
        ],
        "description": "Search tobacco products by name across brands. Returns enriched product data (variants and flavors) with pagination.\n\n**Capability:** `catalog.search` (`.enriched` — Pro / Business)\n\n**Query rules:** `q` must be 2–100 characters (trimmed). `grams` is optional. `page` defaults to 1; `pageSize` defaults to 20 (max 50).\n\n```bash\ncurl -i -H \"X-API-Key: $API_KEY\" \\\n  \"https://api.shishapp.es/api/public/v1/tobaccos/search?q=kent&grams=50&page=1&pageSize=20\"\n```\n",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 100
            },
            "example": "kent",
            "in": "query",
            "name": "q",
            "required": true,
            "description": "Search query (product name, 2–100 chars)"
          },
          {
            "schema": {
              "type": "integer",
              "exclusiveMinimum": true,
              "maximum": 9007199254740991
            },
            "example": 50,
            "in": "query",
            "name": "grams",
            "required": false,
            "description": "Optional: filter by grams"
          },
          {
            "schema": {
              "default": 1,
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "in": "query",
            "name": "page",
            "required": false,
            "description": "Page number (1-based)"
          },
          {
            "schema": {
              "default": 20,
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            },
            "in": "query",
            "name": "pageSize",
            "required": false,
            "description": "Results per page (max 50)"
          }
        ],
        "security": [
          {
            "apiKeyAuth": []
          }
        ],
        "x-capabilityTier": "enriched",
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "productId": {
                            "type": "string",
                            "format": "uuid",
                            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                          },
                          "brandId": {
                            "type": "string",
                            "format": "uuid",
                            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                          },
                          "name": {
                            "type": "string"
                          },
                          "displayName": {
                            "nullable": true,
                            "type": "string"
                          },
                          "variants": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "grams": {
                                  "type": "integer",
                                  "exclusiveMinimum": true,
                                  "maximum": 5000
                                }
                              },
                              "required": [
                                "grams"
                              ],
                              "additionalProperties": false
                            },
                            "description": "Available grams"
                          },
                          "flavors": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "slug": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string"
                                },
                                "names": {
                                  "type": "object",
                                  "additionalProperties": {
                                    "type": "string"
                                  },
                                  "description": "Localized flavor names keyed by locale (es, en, …)"
                                },
                                "color": {
                                  "type": "string"
                                },
                                "type": {
                                  "type": "string",
                                  "enum": [
                                    "common",
                                    "premium"
                                  ]
                                }
                              },
                              "required": [
                                "slug",
                                "name",
                                "names",
                                "color",
                                "type"
                              ],
                              "additionalProperties": false
                            }
                          }
                        },
                        "required": [
                          "productId",
                          "brandId",
                          "name",
                          "displayName",
                          "variants",
                          "flavors"
                        ],
                        "additionalProperties": false
                      },
                      "description": "Products (Tier 2: catalog intelligence incl. flavors)"
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer",
                          "exclusiveMinimum": true,
                          "maximum": 9007199254740991
                        },
                        "pageSize": {
                          "type": "integer",
                          "exclusiveMinimum": true,
                          "maximum": 9007199254740991
                        },
                        "total": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        },
                        "totalPages": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        }
                      },
                      "required": [
                        "page",
                        "pageSize",
                        "total",
                        "totalPages"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "products",
                    "pagination"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer",
                  "example": 10
                },
                "description": "Maximum requests per minute for this subscription."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer",
                  "example": 9
                },
                "description": "Remaining requests in the current minute window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer",
                  "example": 1710000060
                },
                "description": "Unix timestamp (seconds) when the current window resets."
              }
            }
          },
          "400": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "code": "UNAUTHORIZED",
                  "message": "Invalid or missing API key."
                }
              }
            }
          },
          "402": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "403": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "requiredRoles": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "challenge": {
                      "type": "string"
                    },
                    "maskedEmail": {
                      "type": "string"
                    },
                    "resendAvailableAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "429": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "retryAfter": {
                      "type": "integer",
                      "exclusiveMinimum": true,
                      "maximum": 9007199254740991
                    },
                    "resendAvailableAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "code": "RATE_LIMIT_EXCEEDED",
                  "message": "Rate limit exceeded for this subscription."
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer",
                  "example": 10
                },
                "description": "Maximum requests per minute for this subscription."
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer",
                  "example": 9
                },
                "description": "Remaining requests in the current minute window."
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer",
                  "example": 1710000060
                },
                "description": "Unix timestamp (seconds) when the current window resets."
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "example": 42
                },
                "description": "Seconds until the client should retry (429 only)."
              }
            }
          },
          "500": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.shishapp.es",
      "description": "Production"
    }
  ],
  "security": [
    {
      "apiKeyAuth": []
    }
  ]
}
