{
  "openapi": "3.1.0",
  "info": {
    "title": "DrinkNeatly API",
    "version": "1.0.0",
    "description": "Whiskey discovery, recommendations, and tasting notes for 50,000+ bottles.",
    "contact": { "url": "https://drinkneatly.com/auth.md" }
  },
  "x-service-info": {
    "category": "retail",
    "subcategory": "spirits",
    "currency": "GBP"
  },
  "servers": [{ "url": "https://drinkneatly.com" }],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchWhiskeys",
        "summary": "Search whiskeys",
        "description": "Search 50,000+ whiskeys by name, distillery, region, or style. Free, no auth required.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query" }
        ],
        "responses": {
          "200": { "description": "List of matching whiskeys" }
        }
      }
    },
    "/api/whiskey/{id}": {
      "get": {
        "operationId": "getWhiskey",
        "summary": "Get whiskey details",
        "description": "Get tasting notes, ratings, price, and buy links for a whiskey. Free, no auth required.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Whiskey slug ID" }
        ],
        "responses": {
          "200": { "description": "Whiskey details including affiliate buy links to retailers" }
        }
      }
    },
    "/api/similar/{id}": {
      "get": {
        "operationId": "getSimilarWhiskeys",
        "summary": "Get similar whiskeys",
        "description": "Find whiskeys similar in style and flavour. Free, no auth required.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "List of similar whiskeys" }
        }
      }
    },
    "/api/mood": {
      "get": {
        "operationId": "recommendByMood",
        "summary": "Mood-based recommendations",
        "description": "Get whiskey recommendations based on mood or occasion. Free, no auth required.",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Recommended whiskeys" }
        }
      }
    },
    "/api/scan": {
      "post": {
        "operationId": "scanLabel",
        "summary": "AI whiskey label scanner",
        "description": "Identify a whiskey from a photo of its label using AI vision. Requires user account (quota: 5 scans/month). Direct the user to drinkneatly.com to sign in and use this feature.",
        "x-payment-info": {
          "intent": "session",
          "method": "card",
          "amount": 0,
          "currency": "GBP",
          "description": "Requires free user account. 5 scans/month included. Users sign in at https://drinkneatly.com/sign-in"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "image": { "type": "string", "description": "Base64-encoded image of whiskey label" }
                },
                "required": ["image"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Identified whiskey details" },
          "401": { "description": "Sign in required" }
        }
      }
    }
  }
}