{
  "openapi": "3.1.0",
  "info": {
    "title": "cannastack",
    "version": "1.0.0",
    "description": "Agent-native cannabis data. Dispensary menus, prices, deals, and strain availability priced like an API call via x402. $0.02 per request, settled in USDC.",
    "contact": {
      "url": "https://cannastack.0x402.sh/docs"
    },
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://cannastack.0x402.sh"
    }
  ],
  "paths": {
    "/api/strain-finder": {
      "post": {
        "operationId": "strain_finder",
        "summary": "Search a strain across every dispensary menu within range. Sorted cheapest first.",
        "tags": [
          "cannastack"
        ],
        "x-cannastack-price-usdc": 0.02,
        "x-x402-price-usdc": 0.02,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "strain",
                  "location"
                ],
                "properties": {
                  "strain": {
                    "type": "string",
                    "description": "Strain name. Partial match supported.",
                    "example": "Blue Dream"
                  },
                  "location": {
                    "type": "string",
                    "description": "City, address, or \"City, ST\". US only.",
                    "example": "Denver, CO"
                  },
                  "radius": {
                    "type": "number",
                    "description": "Search radius in miles. Default 15, max 50.",
                    "example": 15
                  }
                },
                "example": {
                  "strain": "Blue Dream",
                  "location": "Denver, CO",
                  "radius": 15
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "ok": true,
                    "strain": "Blue Dream",
                    "location": {
                      "query": "Denver, CO",
                      "lat": 39.7392,
                      "lng": -104.9849,
                      "resolved": "Denver, Colorado, USA"
                    },
                    "source": "database",
                    "dispensaries_searched": 24,
                    "results": [
                      {
                        "dispensary": "Native Roots",
                        "rating": 4.6,
                        "reviews": 1248,
                        "address": "1146 Broadway, Denver, CO",
                        "url": "https://...",
                        "matches": [
                          {
                            "name": "Blue Dream",
                            "category": "flower",
                            "brand": "House",
                            "genetics": "hybrid",
                            "price": 28,
                            "orderable": true
                          }
                        ]
                      }
                    ],
                    "summary": "Searched 24 dispensaries near Denver, CO for \"Blue Dream\". Found 12 matches at 8 dispensaries. Cheapest: $28 at Native Roots.",
                    "response_ms": 612
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string",
                      "example": "Missing 'strain'"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/price-compare": {
      "post": {
        "operationId": "price_compare",
        "summary": "Compare prices for a category across every dispensary in range. Returns min/max/avg.",
        "tags": [
          "cannastack"
        ],
        "x-cannastack-price-usdc": 0.02,
        "x-x402-price-usdc": 0.02,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "category",
                  "location"
                ],
                "properties": {
                  "category": {
                    "type": "string",
                    "description": "flower, edibles, vape, concentrates, pre-rolls, drinks, tinctures, topicals, wellness",
                    "example": "flower"
                  },
                  "location": {
                    "type": "string",
                    "description": "City, address, or \"City, ST\". US only.",
                    "example": "Seattle, WA"
                  },
                  "genetics": {
                    "type": "string",
                    "description": "Filter by genetics: sativa, indica, hybrid",
                    "example": "sativa"
                  },
                  "radius": {
                    "type": "number",
                    "description": "Search radius in miles. Default 15, max 50.",
                    "example": 15
                  },
                  "limit": {
                    "type": "number",
                    "description": "Max products to return. Default 50, max 100.",
                    "example": 50
                  }
                },
                "example": {
                  "category": "flower",
                  "location": "Seattle, WA",
                  "genetics": "sativa",
                  "limit": 50
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "ok": true,
                    "category": "flower",
                    "genetics": "sativa",
                    "total_matches": 50,
                    "results": [
                      {
                        "name": "Sour Diesel",
                        "brand": "House",
                        "genetics": "sativa",
                        "price": 22,
                        "unit": "eighth",
                        "dispensary": "Have a Heart",
                        "orderable": true
                      }
                    ],
                    "stats": {
                      "min": 22,
                      "max": 65,
                      "avg": 41.3,
                      "count": 50
                    },
                    "summary": "Compared 50 flower (sativa) products across 18 dispensaries near Seattle, WA. Cheapest: $22. Average: $41.30.",
                    "response_ms": 290
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string",
                      "example": "Missing 'strain'"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/deal-scout": {
      "post": {
        "operationId": "deal_scout",
        "summary": "Find dispensaries with active deals. Optionally filter by category.",
        "tags": [
          "cannastack"
        ],
        "x-cannastack-price-usdc": 0.02,
        "x-x402-price-usdc": 0.02,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "location"
                ],
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "City, address, or \"City, ST\". US only.",
                    "example": "Las Vegas, NV"
                  },
                  "category": {
                    "type": "string",
                    "description": "Filter deals to one category (flower, vape, etc.)",
                    "example": "flower"
                  },
                  "radius": {
                    "type": "number",
                    "description": "Search radius in miles. Default 15, max 50.",
                    "example": 15
                  }
                },
                "example": {
                  "location": "Las Vegas, NV",
                  "category": "flower"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "ok": true,
                    "category": "flower",
                    "total_dispensaries": 32,
                    "deals_dispensaries": 18,
                    "results": [
                      {
                        "dispensary": "Planet 13",
                        "rating": 4.7,
                        "address": "2548 W Desert Inn Rd, Las Vegas, NV",
                        "deal_products": [
                          {
                            "name": "Sour Diesel",
                            "price": 18,
                            "brand": "House"
                          }
                        ]
                      }
                    ],
                    "summary": "18 of 32 dispensaries near Las Vegas, NV have active deals. Best value: Sour Diesel at $18 (Planet 13).",
                    "response_ms": 483
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string",
                      "example": "Missing 'strain'"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/price-history": {
      "post": {
        "operationId": "price_history",
        "summary": "Track price changes over time for a strain or dispensary. Returns trend up/down/stable.",
        "tags": [
          "cannastack"
        ],
        "x-cannastack-price-usdc": 0.02,
        "x-x402-price-usdc": 0.02,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [],
                "properties": {
                  "strain": {
                    "type": "string",
                    "description": "Strain name (provide this OR dispensary)",
                    "example": "Gelato 42"
                  },
                  "dispensary": {
                    "type": "string",
                    "description": "Dispensary name (provide this OR strain)",
                    "example": "Native Roots"
                  },
                  "location": {
                    "type": "string",
                    "description": "Optional: scope to a city",
                    "example": "Denver, CO"
                  },
                  "category": {
                    "type": "string",
                    "description": "Filter by category",
                    "example": "flower"
                  },
                  "days": {
                    "type": "number",
                    "description": "Lookback window in days. Default 30, max 365.",
                    "example": 30
                  }
                },
                "example": {
                  "strain": "Gelato 42",
                  "days": 30
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "ok": true,
                    "query": {
                      "strain": "Gelato 42",
                      "days": 30
                    },
                    "history": [
                      {
                        "item_name": "Gelato 42",
                        "dispensary_name": "Native Roots",
                        "price_eighth": 28,
                        "recorded_at": "2026-05-10T14:22:00Z"
                      }
                    ],
                    "stats": {
                      "current": 28,
                      "oldest": 32,
                      "change_pct": -12.5,
                      "trend": "down",
                      "data_points": 14
                    },
                    "summary": "14 price changes in the last 30 days. Current: $28. Trend: down (-12.5%).",
                    "response_ms": 81
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string",
                      "example": "Missing 'strain'"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/analytics": {
      "get": {
        "operationId": "analytics_summary",
        "summary": "Public analytics: total requests, USDC settled 24h, top endpoints and locations.",
        "tags": [
          "cannastack"
        ],
        "x-cannastack-price-usdc": 0,
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/crawl/status": {
      "get": {
        "operationId": "crawl_status",
        "summary": "Crawler health and recent runs across metros.",
        "tags": [
          "cannastack"
        ],
        "x-cannastack-price-usdc": 0,
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "x-x402": {
    "version": "1",
    "payment": {
      "protocol": "x402",
      "asset": "USDC"
    },
    "manifest": "https://cannastack.0x402.sh/.well-known/x402.json"
  }
}