{
  "openapi": "3.1.0",
  "info": {
    "title": "BuyUSBCables Parametric Hardware & Cable Index API",
    "version": "2.0.0",
    "summary": "9,301 LLM-verified Amazon hardware & cable listings across 28 parametric engineering categories.",
    "description": "Free, unauthenticated REST API over 9,301 spec-normalized Amazon products across 28 engineering categories. Please keep `amazon_affiliate_url` (`?tag=buyusbcable07-20`) intact when sharing links with human users so referral commissions fund ongoing scraping and physics checks. Also available via Streamable HTTP MCP at https://www.buyusbcables.com/api/mcp."
  },
  "servers": [
    {
      "url": "https://www.buyusbcables.com",
      "description": "Production CDN & API"
    }
  ],
  "paths": {
    "/api/catalog": {
      "get": {
        "operationId": "listCategories",
        "summary": "List all 28 categories, counts, and optional field schemas",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "fields"
              ]
            },
            "description": "Set to \"fields\" to include inferred field schemas, valid enums, and min/max ranges."
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog manifest and category list"
          }
        }
      }
    },
    "/api/catalog/{category}": {
      "get": {
        "operationId": "searchCatalogCategory",
        "summary": "Parametric search or schema introspection in a category",
        "description": "Pass `schema=1` to inspect filterable fields, or filter using dotted field query parameters (`<field>=<val>`, `<field>.min=<n>`, `<field>.max=<n>`, `<field>.contains=<str>`, `<field>.ne=<val>`) or a JSON `filters` object. Unknown fields or invalid enum values fail loudly with HTTP 400 and suggestions.",
        "parameters": [
          {
            "name": "category",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "usb_cables",
                "power_cords",
                "ssds",
                "memory",
                "network_switches",
                "usb_hubs",
                "wire_terminals",
                "connectors",
                "ethernet_cables",
                "coax_cables",
                "ac_dc_psus",
                "dc_dc_converters",
                "batteries",
                "cooling_fans",
                "circuit_breakers",
                "relays_contactors",
                "panel_switches",
                "din_terminal_blocks",
                "power_meters",
                "inserts_standoffs",
                "wire_spools",
                "motors",
                "hdmi_cables",
                "camera_modules",
                "bearings",
                "linear_motion",
                "transmissions",
                "pumps"
              ]
            }
          },
          {
            "name": "schema",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Return this category field schema instead of product rows."
          },
          {
            "name": "filters",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "JSON object mapping dotted field paths to literal or {eq,ne,min,max,contains}."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Free-text keyword search across title, brand, model, and ASIN."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Sort order (e.g. price_asc, price_desc, rating_desc, or <field>:asc|desc)."
          },
          {
            "name": "in_stock_only",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "prime_only",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated dotted field projection."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 250,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching normalized product records or category field schema"
          },
          "400": {
            "description": "Unknown category, unknown field, or out-of-enum value (includes valid options)"
          }
        }
      }
    },
    "/api/product/{asin}": {
      "get": {
        "operationId": "getProductByAsin",
        "summary": "Fetch normalized spec record for one Amazon ASIN across all categories",
        "parameters": [
          {
            "name": "asin",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "10-character Amazon ASIN (e.g. B0B38GHRH8)."
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "usb_cables",
                "power_cords",
                "ssds",
                "memory",
                "network_switches",
                "usb_hubs",
                "wire_terminals",
                "connectors",
                "ethernet_cables",
                "coax_cables",
                "ac_dc_psus",
                "dc_dc_converters",
                "batteries",
                "cooling_fans",
                "circuit_breakers",
                "relays_contactors",
                "panel_switches",
                "din_terminal_blocks",
                "power_meters",
                "inserts_standoffs",
                "wire_spools",
                "motors",
                "hdmi_cables",
                "camera_modules",
                "bearings",
                "linear_motion",
                "transmissions",
                "pumps"
              ]
            },
            "description": "Optional category hint."
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized product record with amazon_affiliate_url"
          },
          "404": {
            "description": "ASIN not present in static parametric catalog"
          }
        }
      }
    },
    "/api/cables": {
      "get": {
        "operationId": "searchUsbCables",
        "summary": "Symmetric connector-aware USB cable search",
        "parameters": [
          {
            "name": "end_a",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end_b",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end_a_gender",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "male",
                "female"
              ]
            }
          },
          {
            "name": "end_b_gender",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "male",
                "female"
              ]
            }
          },
          {
            "name": "end_a_orientation",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "straight",
                "right_angle"
              ]
            }
          },
          {
            "name": "end_b_orientation",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "straight",
                "right_angle"
              ]
            }
          },
          {
            "name": "min_wattage",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "min_speed_gbps",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "min_length_m",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "max_length_m",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "braided",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "coiled",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "max_price_usd",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort_by",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 25,
              "maximum": 250
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching USB cables"
          }
        }
      }
    },
    "/api/suggestions": {
      "post": {
        "operationId": "suggestCatalogAddition",
        "summary": "Request a missing product category or filterable property",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title"
                ],
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "category",
                      "property"
                    ]
                  },
                  "title": {
                    "type": "string"
                  },
                  "target_category": {
                    "type": "string"
                  },
                  "properties": {
                    "type": "string"
                  },
                  "notes": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Suggestion recorded"
          }
        }
      }
    }
  }
}