{
  "openapi": "3.1.0",
  "info": {
    "title": "thrift.guide API",
    "description": "Free API for secondhand clothing price estimates. Returns resale price ranges by brand, category, and condition. Covers 55 brands across 5 tiers (fast-fashion to designer) and 15 clothing categories.",
    "version": "1.0.0",
    "contact": {
      "name": "thrift.guide",
      "url": "https://thrift.guide"
    }
  },
  "servers": [
    {
      "url": "https://www.thrift.guide",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from POST /api/public/keys. Pass as: Authorization: Bearer tg_..."
      }
    }
  },
  "paths": {
    "/api/public/price": {
      "get": {
        "operationId": "getPrice",
        "summary": "Get resale price estimate for a brand + category",
        "description": "Returns low, typical, and high price estimates in USD for all condition grades (New with tags, Like New, Good, Fair, Poor). Optionally filter by condition.",
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "description": "Brand slug (e.g., 'gucci', 'nike', 'hm'). See /api/public/brands for all options.",
            "schema": { "type": "string" },
            "examples": {
              "luxury": { "value": "gucci" },
              "premium": { "value": "nike" },
              "fast-fashion": { "value": "zara" }
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": true,
            "description": "Category slug (e.g., 'bag', 'sneakers', 'jacket'). See /api/public/categories for all options.",
            "schema": { "type": "string" },
            "examples": {
              "bag": { "value": "bag" },
              "sneakers": { "value": "sneakers" },
              "jacket": { "value": "jacket" }
            }
          },
          {
            "name": "condition",
            "in": "query",
            "required": false,
            "description": "Filter by condition grade. If omitted, returns all conditions.",
            "schema": {
              "type": "string",
              "enum": ["New with tags", "Like New", "Good", "Fair", "Poor"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Price estimate",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "brand": {
                      "type": "object",
                      "properties": {
                        "name": { "type": "string" },
                        "slug": { "type": "string" },
                        "tier": { "type": "string" },
                        "tierLabel": { "type": "string" }
                      }
                    },
                    "category": {
                      "type": "object",
                      "properties": {
                        "name": { "type": "string" },
                        "slug": { "type": "string" }
                      }
                    },
                    "currency": { "type": "string" },
                    "prices": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "condition": { "type": "string" },
                          "low": { "type": "number" },
                          "mid": { "type": "number" },
                          "high": { "type": "number" }
                        }
                      }
                    },
                    "source": { "type": "string" },
                    "methodology": { "type": "string" }
                  }
                },
                "example": {
                  "brand": { "name": "Gucci", "slug": "gucci", "tier": "luxury", "tierLabel": "Luxury" },
                  "category": { "name": "Bag", "slug": "bag" },
                  "currency": "USD",
                  "prices": [
                    { "condition": "New with tags", "low": 520, "mid": 1170, "high": 2340 },
                    { "condition": "Like New", "low": 440, "mid": 990, "high": 1980 },
                    { "condition": "Good", "low": 400, "mid": 900, "high": 1800 },
                    { "condition": "Fair", "low": 280, "mid": 630, "high": 1260 },
                    { "condition": "Poor", "low": 160, "mid": 360, "high": 720 }
                  ],
                  "source": "thrift.guide",
                  "methodology": "Brand tier × category modifier × condition multiplier."
                }
              }
            }
          },
          "400": { "description": "Missing required parameters" },
          "404": { "description": "Unknown brand or category" }
        }
      }
    },
    "/api/public/brands": {
      "get": {
        "operationId": "listBrands",
        "summary": "List all supported brands grouped by tier",
        "description": "Returns all 55 brands organized by tier (designer, luxury, premium, mid-range, fast-fashion) with their slugs.",
        "responses": {
          "200": {
            "description": "Brand list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": { "type": "number" },
                    "tiers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tier": { "type": "string" },
                          "label": { "type": "string" },
                          "brands": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "name": { "type": "string" },
                                "slug": { "type": "string" }
                              }
                            }
                          }
                        }
                      }
                    },
                    "allSlugs": {
                      "type": "array",
                      "items": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/public/keys": {
      "post": {
        "operationId": "createApiKey",
        "summary": "Get a free API key",
        "description": "Generate a free API key using your email address. The key is required for the ML-powered pricing endpoint (/api/public/ml-price). Keys are instant and free — no approval needed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": { "type": "string", "format": "email", "description": "Your email address" }
                }
              },
              "example": { "email": "user@example.com" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "API key created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apiKey": { "type": "string" },
                    "email": { "type": "string" },
                    "tier": { "type": "string" },
                    "limits": { "type": "object" },
                    "usage": { "type": "object" },
                    "docs": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/public/ml-price": {
      "get": {
        "operationId": "getMlPrice",
        "summary": "ML-powered resale price prediction (requires API key)",
        "description": "Returns an ML prediction from Circular's model trained on millions of resale transactions, plus a static tier-based estimate. Requires a free API key (get one at POST /api/public/keys). Rate limited to 100 requests/day.",
        "security": [{ "apiKey": [] }],
        "parameters": [
          {
            "name": "brand",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Brand slug (e.g., 'gucci', 'nike')"
          },
          {
            "name": "category",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Category slug (e.g., 'bag', 'sneakers')"
          },
          {
            "name": "condition",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Condition filter for static estimate"
          },
          {
            "name": "gender",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["male", "female"] },
            "description": "Gender for ML model (default: female)"
          }
        ],
        "responses": {
          "200": {
            "description": "ML price prediction + static estimate",
            "content": {
              "application/json": {
                "example": {
                  "brand": { "name": "Gucci", "slug": "gucci", "tier": "luxury", "tierLabel": "Luxury" },
                  "category": { "name": "Bag", "slug": "bag" },
                  "currency": "USD",
                  "source": "circular-ml",
                  "mlPrediction": {
                    "price": 274,
                    "priceLow": 192,
                    "priceHigh": 356,
                    "confidence": 0.57,
                    "note": "ML prediction from Circular, trained on millions of resale transactions"
                  },
                  "staticEstimate": {
                    "prices": [
                      { "condition": "Good", "low": 400, "mid": 900, "high": 1800 }
                    ]
                  },
                  "poweredBy": "Circular (circular-resale.com)",
                  "webUrl": "https://thrift.guide/price/gucci/bag"
                }
              }
            }
          },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit exceeded (100/day)" }
        }
      }
    },
    "/api/public/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "List all supported clothing categories",
        "description": "Returns all 15 clothing categories with their slugs and price modifiers.",
        "responses": {
          "200": {
            "description": "Category list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": { "type": "number" },
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": { "type": "string" },
                          "slug": { "type": "string" },
                          "priceModifier": { "type": "number" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}