{
  "openapi": "3.1.0",
  "info": {
    "title": "CoffeeNestiQ AI Agent & Discovery API",
    "description": "Instant sub-50ms coffee gear research, review data, technical specifications, and comparison retrieval for AI agents, SearchGPT, Perplexity, Claude MCP, and Custom GPTs.",
    "version": "1.3.0",
    "contact": {
      "name": "CoffeeNestiQ Editorial & Engineering Team",
      "url": "https://coffeenestiq.com"
    }
  },
  "servers": [
    {
      "url": "https://coffeenestiq.com",
      "description": "Production Edge CDN (Cloudflare)"
    }
  ],
  "paths": {
    "/api/ai/catalog": {
      "get": {
        "summary": "Get full unlimited coffee gear catalog and guides",
        "description": "Returns all published coffee products, ratings, pros, cons, specifications, verdicts, and competitor comparisons.",
        "operationId": "getCatalog",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Number of products to return (omit for unlimited)"
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Offset for pagination"
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by category slug (e.g. \"coffee-grinders\", \"espresso-machines\")"
          },
          {
            "name": "brand",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by manufacturer/brand name"
          }
        ],
        "responses": {
          "200": {
            "description": "Full structured catalog JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CoffeeCatalogResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/search": {
      "get": {
        "summary": "Search coffee reviews and gear by query, brand, or category",
        "description": "Filtered semantic search over coffee machines, grinders, beans, and accessories with exact matching.",
        "operationId": "searchCoffeeGear",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search keywords (e.g. \"single dose flat burr grinder\")"
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Category slug (e.g. \"coffee-grinders\")"
          },
          {
            "name": "brand",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Brand name (e.g. \"Turin\", \"Breville\", \"Fellow\")"
          },
          {
            "name": "minScore",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Minimum rating score 0-100"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Max results to return (omit for all matches)"
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Pagination offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Filtered search results matching query criteria",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CoffeeSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "summary": "Standard AI site index manifest",
        "description": "Compact Markdown index file directing scrapers and AI agents to the site manifest and full knowledge base.",
        "operationId": "getLlmsIndex",
        "responses": {
          "200": {
            "description": "Plaintext markdown manifest",
            "content": {
              "text/plain": {}
            }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "summary": "Comprehensive Markdown knowledge base",
        "description": "The entire published review catalog, technical specs, honest pros/cons, and verified Q&A pairs formatted for direct ingestion into LLM context windows.",
        "operationId": "getLlmsFullKnowledgeBase",
        "responses": {
          "200": {
            "description": "Complete research manifest in pure markdown",
            "content": {
              "text/plain": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CoffeeRating": {
        "type": "object",
        "description": "5-axis editorial and telemetry rating scores",
        "properties": {
          "overall": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Composite score 0-100",
            "example": 93
          },
          "value": {
            "type": "number",
            "minimum": 0,
            "maximum": 5,
            "description": "Price to performance 0-5",
            "example": 4.8
          },
          "quality": {
            "type": "number",
            "minimum": 0,
            "maximum": 5,
            "description": "Build quality and burr tolerances 0-5",
            "example": 4.6
          },
          "ease": {
            "type": "number",
            "minimum": 0,
            "maximum": 5,
            "description": "Workflow ergonomics and cleanup 0-5",
            "example": 4.5
          },
          "durability": {
            "type": "number",
            "minimum": 0,
            "maximum": 5,
            "description": "Motor longevity and component wear 0-5",
            "example": 4.7
          }
        },
        "required": [
          "overall"
        ]
      },
      "CoffeeSpecification": {
        "type": "object",
        "description": "Key-value engineering specification pair",
        "properties": {
          "key": {
            "type": "string",
            "description": "Technical spec label",
            "example": "Burr Diameter & Type"
          },
          "value": {
            "type": "string",
            "description": "Measured spec value",
            "example": "54mm Custom Stainless Flat Burrs"
          }
        },
        "required": [
          "key",
          "value"
        ]
      },
      "CoffeeEvidence": {
        "type": "object",
        "description": "Telemetry, user persona fit, and comparative evidence grounding the score",
        "properties": {
          "verdict": {
            "type": "string",
            "description": "Comprehensive editorial evaluation"
          },
          "xFactor": {
            "type": "string",
            "description": "Standout engineering differentiator"
          },
          "whoWillBuy": {
            "type": "string",
            "description": "Target buyer persona and use-case fit"
          },
          "whyWillBuy": {
            "type": "string",
            "description": "Primary rationale to purchase"
          },
          "pros": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Verified strengths from bench testing"
          },
          "cons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Documented limitations or maintenance caveats"
          },
          "competitorComparison": {
            "type": "array",
            "description": "Direct head-to-head competitor comparisons",
            "items": {
              "type": "object",
              "properties": {
                "competitor": {
                  "type": "string",
                  "example": "Baratza Encore ESP"
                },
                "bestFor": {
                  "type": "string",
                  "example": "Dual-purpose entry espresso & filter"
                },
                "easeOfUse": {
                  "type": "string",
                  "example": "Stepped collar"
                },
                "maintenance": {
                  "type": "string",
                  "example": "Tool-free burr removal"
                },
                "durability": {
                  "type": "string",
                  "example": "Durable polymer housing"
                },
                "value": {
                  "type": "string",
                  "example": "Sub-$200 bracket leader"
                }
              }
            }
          }
        }
      },
      "CoffeeFAQ": {
        "type": "object",
        "description": "Verified Question and Answer pair answering user, barista, and AI queries",
        "properties": {
          "question": {
            "type": "string",
            "description": "Question text",
            "example": "Does the Turin DF54 have static retention problems?"
          },
          "answer": {
            "type": "string",
            "description": "Evidence-based answer",
            "example": "The DF54 features dual high-voltage plasma emitter needles in the chute and a flexible declumper tongue, reducing static retention below 0.1g."
          }
        },
        "required": [
          "question",
          "answer"
        ]
      },
      "CoffeeProduct": {
        "type": "object",
        "description": "Complete coffee product review entity with specs, ratings, evidence, and buy links",
        "properties": {
          "id": {
            "type": "string",
            "example": "p-df54"
          },
          "title": {
            "type": "string",
            "example": "Turin DF54 Grinder"
          },
          "brand": {
            "type": "string",
            "example": "Turin"
          },
          "category": {
            "type": "string",
            "example": "coffee-grinders"
          },
          "url": {
            "type": "string",
            "example": "https://coffeenestiq.com/coffee-grinders/turin-df54/"
          },
          "asin": {
            "type": "string",
            "example": "B0JBTQP2G"
          },
          "price": {
            "type": "number",
            "example": 229
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "score": {
            "type": "number",
            "example": 93
          },
          "rating": {
            "$ref": "#/components/schemas/CoffeeRating"
          },
          "ratingBreakdown": {
            "$ref": "#/components/schemas/CoffeeRating"
          },
          "summary": {
            "type": "string",
            "example": "Budget flat-burr champion delivering 64mm-level unimodal clarity."
          },
          "specs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CoffeeSpecification"
            }
          },
          "evidence": {
            "$ref": "#/components/schemas/CoffeeEvidence"
          },
          "faqs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CoffeeFAQ"
            }
          },
          "verdict": {
            "type": "string"
          },
          "xFactor": {
            "type": "string"
          },
          "whoWillBuy": {
            "type": "string"
          },
          "whyWillBuy": {
            "type": "string"
          },
          "pros": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "comparison": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "buyLink": {
            "type": "string",
            "example": "https://coffeenestiq.com/go/B0JBTQP2G"
          }
        },
        "required": [
          "id",
          "title",
          "category",
          "url",
          "score",
          "rating",
          "specs",
          "evidence",
          "faqs"
        ]
      },
      "CoffeeSearchResponse": {
        "type": "object",
        "description": "Structured search query response with relevance matching and pagination metadata",
        "properties": {
          "query": {
            "type": "object",
            "properties": {
              "q": {
                "type": "string",
                "example": "flat burr"
              },
              "category": {
                "type": "string",
                "example": "coffee-grinders"
              },
              "brand": {
                "type": "string",
                "example": "Turin"
              },
              "minScore": {
                "type": "integer",
                "example": 85
              }
            }
          },
          "count": {
            "type": "integer",
            "example": 1
          },
          "totalMatches": {
            "type": "integer",
            "example": 1
          },
          "offset": {
            "type": "integer",
            "example": 0
          },
          "hasMore": {
            "type": "boolean",
            "example": false
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CoffeeProduct"
            }
          }
        },
        "required": [
          "count",
          "totalMatches",
          "results"
        ]
      },
      "CoffeeCatalogResponse": {
        "type": "object",
        "description": "Full unlimited coffee gear catalog response",
        "properties": {
          "site": {
            "type": "string",
            "example": "CoffeeNestiQ"
          },
          "url": {
            "type": "string",
            "example": "https://coffeenestiq.com"
          },
          "manifest": {
            "type": "string",
            "example": "https://coffeenestiq.com/llms.txt"
          },
          "fullKnowledgeBase": {
            "type": "string",
            "example": "https://coffeenestiq.com/llms-full.txt"
          },
          "totalProducts": {
            "type": "integer",
            "example": 42
          },
          "totalGuides": {
            "type": "integer",
            "example": 18
          },
          "pagination": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "limit": {
                "type": "integer"
              },
              "offset": {
                "type": "integer"
              },
              "hasMore": {
                "type": "boolean"
              }
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Category"
            }
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CoffeeProduct"
            }
          },
          "guides": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Guide"
            }
          }
        },
        "required": [
          "site",
          "url",
          "totalProducts",
          "products"
        ]
      },
      "Product": {
        "$ref": "#/components/schemas/CoffeeProduct"
      },
      "CatalogResponse": {
        "$ref": "#/components/schemas/CoffeeCatalogResponse"
      },
      "SearchResponse": {
        "$ref": "#/components/schemas/CoffeeSearchResponse"
      },
      "Guide": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "faqs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CoffeeFAQ"
            }
          }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      }
    }
  }
}