{
 "openapi": "3.1.0",
 "info": {
  "title": "MadMax Trade Supply Parts API",
  "version": "1.0.0",
  "description": "Read-only, no key needed. Search in-stock replacement filters, alarms, batteries and parts, check what fits an OEM part number or filter size, and build a pre-filled cart link the buyer pays on (Stripe-hosted checkout). Nothing here charges a card.",
  "contact": {
   "email": "tamara@madmaxsupply.com",
   "url": "https://www.madmaxsupply.com/agents/"
  }
 },
 "servers": [
  {
   "url": "https://www.madmaxsupply.com"
  }
 ],
 "paths": {
  "/api/agent/search": {
   "get": {
    "operationId": "searchParts",
    "summary": "Search parts by keyword, OEM part number, size or brand",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "WF3CB"
     },
     {
      "name": "category",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "max_price",
      "in": "query",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 10,
       "maximum": 50
      }
     },
     {
      "name": "ship_to_state",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "example": "MN"
      },
      "description": "2-letter US state/territory code. Prices vary slightly by state (tax we pay is built in). Default MN."
     }
    ],
    "responses": {
     "200": {
      "description": "Matching items with prices"
     }
    }
   }
  },
  "/api/agent/product/{sku}": {
   "get": {
    "operationId": "getProduct",
    "summary": "Full details for one SKU",
    "parameters": [
     {
      "name": "sku",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "MM-RF-891B5F"
     },
     {
      "name": "ship_to_state",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "example": "MN"
      },
      "description": "2-letter US state/territory code. Prices vary slightly by state (tax we pay is built in). Default MN."
     }
    ],
    "responses": {
     "200": {
      "description": "Product"
     },
     "404": {
      "description": "Unknown SKU"
     }
    }
   }
  },
  "/api/agent/fit": {
   "get": {
    "operationId": "checkFit",
    "summary": "What we carry that replaces an OEM part number, fits a filter size or a model/system name",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "20x25x4"
     },
     {
      "name": "ship_to_state",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "example": "MN"
      },
      "description": "2-letter US state/territory code. Prices vary slightly by state (tax we pay is built in). Default MN."
     }
    ],
    "responses": {
     "200": {
      "description": "Matches and the basis of the match"
     }
    }
   }
  },
  "/api/agent/checkout-link": {
   "get": {
    "operationId": "createCheckoutLink",
    "summary": "Pre-filled cart URL (no charge; buyer pays on Stripe checkout)",
    "parameters": [
     {
      "name": "items",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "MM-RF-891B5F:1:6,MM-AF-7859F0:2",
      "description": "Comma-separated SKU:quantity[:auto_ship_months]"
     },
     {
      "name": "ship_to_state",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "example": "MN"
      },
      "description": "2-letter US state/territory code. Prices vary slightly by state (tax we pay is built in). Default MN."
     }
    ],
    "responses": {
     "200": {
      "description": "cart_url, lines, subtotal"
     }
    }
   },
   "post": {
    "operationId": "createCheckoutLinkPost",
    "summary": "Same as GET with a JSON body",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "items": {
          "type": "array",
          "items": {
           "type": "object",
           "properties": {
            "sku": {
             "type": "string"
            },
            "quantity": {
             "type": "integer"
            },
            "auto_ship_months": {
             "type": "integer"
            }
           }
          }
         },
         "ship_to_state": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "cart_url, lines, subtotal"
     }
    }
   }
  },
  "/api/agent/categories": {
   "get": {
    "operationId": "listCategories",
    "summary": "Category slugs and URLs",
    "responses": {
     "200": {
      "description": "Categories"
     }
    }
   }
  },
  "/api/agent/policies": {
   "get": {
    "operationId": "getPolicies",
    "summary": "Shipping, tax, payment, returns, subscriptions, contact",
    "responses": {
     "200": {
      "description": "Policies"
     }
    }
   }
  }
 }
}