{
  "openapi": "3.0.3",
  "info": {
    "title": "Closetta API",
    "description": "Public API for Closetta — live women's fashion sale data from 50+ North American brands. All endpoints are read-only and require no authentication. Data is updated daily.",
    "version": "1.0.0",
    "contact": {
      "url": "https://closetta.app"
    }
  },
  "servers": [
    {
      "url": "https://closetta.app",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/v1/sales": {
      "get": {
        "operationId": "getActiveSales",
        "summary": "Get active and recently ended sales",
        "description": "Returns all brands currently on sale (activeSales) and brands whose sales ended in the last 7 days (endedSales). Each sale includes brand name, discount percentage, sale type, and dates.",
        "responses": {
          "200": {
            "description": "Sales data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/brands": {
      "get": {
        "operationId": "getBrands",
        "summary": "List all tracked brands",
        "description": "Returns the full list of 50+ North American women's fashion brands that Closetta monitors for sales.",
        "responses": {
          "200": {
            "description": "List of brands",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "brands": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Brand"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of tracked brands"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/trends": {
      "get": {
        "operationId": "getTrends",
        "summary": "Get historical discount trends",
        "description": "Returns monthly discount history across all tracked brands, including average discount per month and per-brand peak discounts.",
        "responses": {
          "200": {
            "description": "Trends data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "history": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MonthlyTrend"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Brand": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique brand identifier (slug)"
          },
          "name": {
            "type": "string",
            "description": "Brand display name"
          },
          "url": {
            "type": "string",
            "description": "Brand website URL"
          }
        }
      },
      "Sale": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "brandId": {
            "type": "string",
            "description": "Brand identifier"
          },
          "brandName": {
            "type": "string",
            "description": "Brand display name"
          },
          "brandUrl": {
            "type": "string",
            "description": "Brand website URL"
          },
          "saleType": {
            "type": "string",
            "description": "Name of the sale event (e.g. 'Summer Sale', 'Member Days')"
          },
          "discount": {
            "type": "string",
            "description": "Discount description (e.g. 'Up to 50% off')"
          },
          "isOnSale": {
            "type": "boolean",
            "description": "Whether the sale is currently active"
          },
          "startDate": {
            "type": "string",
            "description": "Sale start date (ISO 8601)"
          },
          "endDate": {
            "type": "string",
            "description": "Sale end date (ISO 8601), if known"
          },
          "scrapedTimestamp": {
            "type": "string",
            "description": "When this data was last scraped"
          }
        }
      },
      "SalesResponse": {
        "type": "object",
        "properties": {
          "activeSales": {
            "type": "array",
            "description": "Brands currently on sale",
            "items": {
              "$ref": "#/components/schemas/Sale"
            }
          },
          "endedSales": {
            "type": "array",
            "description": "Sales that ended in the last 7 days",
            "items": {
              "$ref": "#/components/schemas/Sale"
            }
          },
          "updatedAt": {
            "type": "string",
            "description": "Timestamp of this response"
          }
        }
      },
      "MonthlyTrend": {
        "type": "object",
        "properties": {
          "month": {
            "type": "string",
            "description": "Month label (e.g. 'May 2026')"
          },
          "average": {
            "type": "number",
            "description": "Average peak discount across all brands that month"
          }
        },
        "additionalProperties": {
          "type": "number",
          "description": "Per-brand peak discount for that month (key is brand ID)"
        }
      }
    }
  }
}