{
  "openapi": "3.1.0",
  "info": {
    "title": "CONNTEK Product API",
    "version": "1.0.0",
    "description": "Public REST API for the CONNTEK (昆泰芯微电子) magnetic-sensor product catalog: search by spec/use-case, product details, categories, and competitor cross-reference. Backed by the conntek-aibridge Cloudflare Worker. An MCP server with the same capabilities is described at /.well-known/mcp/server-card.json.",
    "contact": {
      "name": "CONNTEK Design Center",
      "url": "https://chat.connteck.com/"
    }
  },
  "servers": [
    { "url": "https://conntek-aibridge.liyandong0514.workers.dev", "description": "Production (Cloudflare Worker)" }
  ],
  "tags": [
    { "name": "products", "description": "Product catalog, search and details" },
    { "name": "cross-reference", "description": "Competitor part replacement" },
    { "name": "meta", "description": "Health and categories" }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "tags": ["meta"],
        "summary": "Health check",
        "operationId": "getHealth",
        "responses": { "200": { "description": "Service is healthy" } }
      }
    },
    "/api/v1/categories": {
      "get": {
        "tags": ["meta"],
        "summary": "List product categories",
        "operationId": "listCategories",
        "responses": { "200": { "description": "Array of category identifiers and labels" } }
      }
    },
    "/api/v1/products": {
      "get": {
        "tags": ["products"],
        "summary": "List all active products",
        "operationId": "listProducts",
        "parameters": [
          { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by category id (e.g. 3d_hall, linear_hall, tmr_angle, hall_switch_lv, amr_sensor, op_amp, temp_sensor)" },
          { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": ["zh", "en"], "default": "zh" } }
        ],
        "responses": { "200": { "description": "Array of product summaries" } }
      }
    },
    "/api/v1/products/search": {
      "get": {
        "tags": ["products"],
        "summary": "Search products by spec and/or use-case",
        "description": "Pass `application` for use-case recall (BM25-ranked) and/or structured fields for hard filtering. Combine both for 'use-case + spec constraint' queries.",
        "operationId": "searchProducts",
        "parameters": [
          { "name": "application", "in": "query", "schema": { "type": "string" }, "description": "Use-case keyword(s), e.g. joystick, 鼠标滚轮, 气缸位置" },
          { "name": "category", "in": "query", "schema": { "type": "string" } },
          { "name": "voltage", "in": "query", "schema": { "type": "number" }, "description": "Operating voltage in V; returns parts whose range covers it" },
          { "name": "interface", "in": "query", "schema": { "type": "string" }, "description": "spi | i2c | uart | analog | ab" },
          { "name": "package", "in": "query", "schema": { "type": "string" }, "description": "e.g. QFN3x3-16L" },
          { "name": "operating_temp_min", "in": "query", "schema": { "type": "integer" } },
          { "name": "operating_temp_max", "in": "query", "schema": { "type": "integer" } },
          { "name": "lang", "in": "query", "schema": { "type": "string", "enum": ["zh", "en"], "default": "zh" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": { "200": { "description": "Ranked array of matching products" } }
      }
    },
    "/api/v1/products/{part_number}": {
      "get": {
        "tags": ["products"],
        "summary": "Get full product details",
        "operationId": "getProduct",
        "parameters": [
          { "name": "part_number", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CONNTEK part number, e.g. KTH5772" },
          { "name": "lang", "in": "query", "schema": { "type": "string", "enum": ["zh", "en"], "default": "zh" } }
        ],
        "responses": {
          "200": { "description": "Full product record incl. specs, cross-references and datasheet links" },
          "404": { "description": "Unknown part number" }
        }
      }
    },
    "/api/v1/cross-reference": {
      "get": {
        "tags": ["cross-reference"],
        "summary": "Find CONNTEK replacement for a competitor part",
        "operationId": "crossReference",
        "parameters": [
          { "name": "competitor_part", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Competitor part number, e.g. TMAG5273, DRV5032, AS5600" },
          { "name": "competitor_brand", "in": "query", "schema": { "type": "string" } },
          { "name": "fuzzy", "in": "query", "schema": { "type": "boolean", "default": false } },
          { "name": "lang", "in": "query", "schema": { "type": "string", "enum": ["zh", "en"], "default": "zh" } }
        ],
        "responses": { "200": { "description": "CONNTEK equivalent part(s) with match grade" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Session bearer token — only required for protected /agent/* chat endpoints, not for the public read API above."
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key for protected /agent/* endpoints."
      }
    }
  }
}