{
  "openapi": "3.1.0",
  "info": {
    "title": "Stratify Pricing Index API",
    "version": "v1",
    "description": "The only real-time DTC pricing API. Track 50 brands across 5 verticals — coffee, skincare, supplements, apparel, and jewelry — with weekly price change data.",
    "contact": { "email": "api@stratifyagent.com" },
    "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }
  },
  "servers": [
    { "url": "https://stratifyagent.com", "description": "Production" }
  ],
  "tags": [
    { "name": "Movers", "description": "Top price movers across all verticals" },
    { "name": "Verticals", "description": "Brand-level prices and history per vertical" },
    { "name": "Key Management", "description": "Self-serve API key registration and management" }
  ],
  "paths": {
    "/api/pricing-index/v1/movers.json": {
      "get": {
        "tags": ["Movers"],
        "summary": "Top movers across all verticals",
        "description": "Returns this week's biggest price movers across all 5 verticals. Use this endpoint to power your alerts, dashboards, or feeds. Free tier serves cached data (24h lag); paid tiers get real-time.",
        "parameters": [
          {
            "name": "X-Stratify-Key",
            "in": "header",
            "description": "Your API key (email used at signup)",
            "schema": { "type": "string", "example": "you@example.com" }
          }
        ],
        "responses": {
          "200": {
            "description": "Top movers payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string", "example": "v1" },
                    "generated_at": { "type": "string", "format": "date-time" },
                    "week_start": { "type": "string", "format": "date" },
                    "verticals": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "vertical": { "type": "string", "enum": ["coffee","skincare","supplements","apparel","jewelry"] },
                          "top_movers": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "brand": { "type": "string" },
                                "old_price": { "type": "number" },
                                "new_price": { "type": "number" },
                                "change_pct": { "type": "number" },
                                "direction": { "type": "string", "enum": ["up","down"] },
                                "detected_at": { "type": "string", "format": "date-time" }
                              }
                            }
                          },
                          "wow_change_pct": { "type": "number" }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "schema_version": "v1",
                  "generated_at": "2026-05-26T14:00:00Z",
                  "week_start": "2026-05-25",
                  "verticals": [
                    {
                      "vertical": "coffee",
                      "top_movers": [
                        { "brand": "DTC Brand", "old_price": 28, "new_price": 22, "change_pct": -21.4, "direction": "down", "detected_at": "2026-05-26T09:00:00Z" }
                      ],
                      "wow_change_pct": -8.2
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/pricing-index/v1/vertical/{vertical}.json": {
      "get": {
        "tags": ["Verticals"],
        "summary": "Brand-level prices for a vertical",
        "description": "Returns all tracked brands for a vertical with current price, week-over-week delta, and an 8-week sparkline. Pass vertical as: coffee, skincare, supplements, apparel, or jewelry.",
        "parameters": [
          {
            "name": "vertical",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "enum": ["coffee","skincare","supplements","apparel","jewelry"] }
          },
          {
            "name": "X-Stratify-Key",
            "in": "header",
            "description": "Your API key",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Vertical detail payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "vertical": { "type": "string" },
                    "brands": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "brand": { "type": "string" },
                          "current_price": { "type": "number" },
                          "pct_change": { "type": "number" },
                          "old_price": { "type": "number" },
                          "snapshot_at": { "type": "string", "format": "date-time" }
                        }
                      }
                    },
                    "sparkline": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "week_start": { "type": "string", "format": "date" },
                          "avg_delta": { "type": "number" },
                          "movers": { "type": "integer" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid vertical",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/pricing-index/v1/history.json": {
      "get": {
        "tags": ["Verticals"],
        "summary": "Historical WoW deltas for a vertical",
        "description": "Returns week-over-week price change history for a vertical, up to 52 weeks back. Useful for charting price trends and building competitive analysis dashboards.",
        "parameters": [
          {
            "name": "vertical",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "enum": ["coffee","skincare","supplements","apparel","jewelry"] }
          },
          {
            "name": "weeks",
            "in": "query",
            "description": "Number of weeks to return (default 12, max 52)",
            "schema": { "type": "integer", "default": 12, "minimum": 1, "maximum": 52 }
          },
          {
            "name": "X-Stratify-Key",
            "in": "header",
            "description": "Your API key",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Historical data for vertical",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "schema_version": { "type": "string" },
                    "generated_at": { "type": "string", "format": "date-time" },
                    "vertical": { "type": "string" },
                    "weeks_requested": { "type": "integer" },
                    "history": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "week_start": { "type": "string", "format": "date" },
                          "avg_wow_pct": { "type": "number" },
                          "brands_with_delta": { "type": "integer" },
                          "mover_count": { "type": "integer" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/pricing-index/v1/dev-key": {
      "post": {
        "tags": ["Key Management"],
        "summary": "Get a free API key",
        "description": "Instantly issue a free-tier API key. Pass your email and receive a key (your email acts as the key). No credit card required.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": { "type": "string", "format": "email", "example": "you@example.com" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Key created",
            "content": {
              "application/json": {
                "example": {
                  "success": true,
                  "dev_key": "you@example.com",
                  "rate_limit": 1000,
                  "note": "Pass this email as the X-Stratify-Key request header to unlock 1 000 requests/hour."
                }
              }
            }
          },
          "400": {
            "description": "Invalid email",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "example": "Rate limit exceeded. Get a free dev key at /developers." }
        }
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "name": "X-Stratify-Key",
        "in": "header",
        "description": "Your Stratify API key. Free tier = 100 req/day. Dev tier ($49/mo) = 10K req/day. Commercial ($299/mo) = 100K req/day."
      }
    }
  },
  "security": [{ "ApiKey": [] }]
}