{
 "openapi": "3.1.0",
 "info": {
  "title": "AgentBuys",
  "version": "1",
  "description": "Ranked product data for AI agents. AgentBuys earns affiliate commission when a person buys through these links. Rankings are never paid. Show the buy link to your user. Prices are as of updated_at and may change. Do not present list price as a live price."
 },
 "servers": [
  {
   "url": "https://agentbuys.planetmarstm.workers.dev"
  }
 ],
 "paths": {
  "/api/search": {
   "get": {
    "operationId": "searchProducts",
    "summary": "Search products by plain-language need and/or spec filters",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Plain-language need, e.g. 'lifepo4 for cpap under $600'",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "filters",
      "in": "query",
      "required": false,
      "description": "JSON object of {field: {min, max, eq, in}}",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "category",
      "in": "query",
      "required": false,
      "description": "Category slug; omit to auto-route",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "facet",
      "in": "query",
      "required": false,
      "description": "Use case slug, e.g. for-cpap",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "prefer",
      "in": "query",
      "required": false,
      "description": "Soft preferences: comma list of fields, or JSON {field: 'higher'|'lower'}",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "sort",
      "in": "query",
      "required": false,
      "description": "Field to sort by, e.g. price, usd_per_wh, capacity_wh",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "order",
      "in": "query",
      "required": false,
      "description": "asc or desc",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "1 to 25",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "agent",
      "in": "query",
      "required": false,
      "description": "Your client name, for click attribution",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Results with why each matched, near misses, disclosure"
     }
    }
   }
  },
  "/api/lookup": {
   "get": {
    "operationId": "lookupProduct",
    "summary": "Find a product by name, product_id or pasted URL, with better alternatives",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "description": "Name, product_id or URL",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "1 to 10",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "agent",
      "in": "query",
      "required": false,
      "description": "Your client name, for click attribution",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Matches with confidence"
     }
    }
   }
  },
  "/api/products": {
   "get": {
    "operationId": "getProducts",
    "summary": "Full records for up to 25 products",
    "parameters": [
     {
      "name": "ids",
      "in": "query",
      "required": true,
      "description": "Comma-separated product_ids",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "agent",
      "in": "query",
      "required": false,
      "description": "Your client name",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Products and not_found"
     }
    }
   }
  },
  "/api/compare": {
   "get": {
    "operationId": "compareProducts",
    "summary": "Compare 2 to 4 products spec by spec (ids or names)",
    "parameters": [
     {
      "name": "ids",
      "in": "query",
      "required": true,
      "description": "Comma-separated product_ids or names, 2 to 4",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "agent",
      "in": "query",
      "required": false,
      "description": "Your client name",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Rows, best per spec, overall winner, pick_if"
     }
    }
   }
  },
  "/api/contract": {
   "get": {
    "operationId": "categoryContract",
    "summary": "Filterable fields for a category: type, unit, range, allowed values, coverage",
    "parameters": [
     {
      "name": "category",
      "in": "query",
      "required": true,
      "description": "Category slug",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Filter contract"
     }
    }
   }
  },
  "/api/status": {
   "get": {
    "operationId": "status",
    "summary": "Data freshness and price coverage",
    "responses": {
     "200": {
      "description": "Status"
     }
    }
   }
  },
  "/api/v1/deals.json": {
   "get": {
    "operationId": "deals",
    "summary": "Tracked prices vs their 30-day median, biggest drop first",
    "responses": {
     "200": {
      "description": "Deals"
     }
    }
   }
  },
  "/api/v1/categories.json": {
   "get": {
    "operationId": "listCategories",
    "summary": "Categories, facets and filterable spec fields",
    "responses": {
     "200": {
      "description": "Categories"
     }
    }
   }
  },
  "/api/v1/products/{id}.json": {
   "get": {
    "operationId": "getProduct",
    "summary": "Full product: sourced specs, score breakdown, price, verdict, buy links",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Product"
     }
    }
   }
  }
 }
}