{
  "openapi": "3.0.3",
  "info": {
    "title": "The Pulse Rolex Index API",
    "version": "1.0.0-beta",
    "description": "Read-only JSON access to The Pulse Rolex Index and per-reference market values for 14 benchmark Rolex references. Values are built from confirmed resale sales and refresh once daily. Every endpoint except /v1 requires an API key (Authorization: Bearer <key>, or ?key=). Free keys are issued instantly at https://www.thepulse.fun/watch-market-data/#start and allow 100 requests per UTC day on latest-value endpoints; the Developer tier allows 10,000 per day and unlocks history and movers. Display and redistribution are allowed with attribution to The Pulse (thepulse.fun).",
    "contact": { "name": "The Pulse", "email": "hello@thepulse.fun", "url": "https://www.thepulse.fun/api/" },
    "termsOfService": "https://www.thepulse.fun/compliance/"
  },
  "servers": [
    { "url": "https://www.thepulse.fun", "description": "Beta (static, daily refresh)" }
  ],
  "tags": [
    { "name": "index", "description": "The Pulse Rolex Index" },
    { "name": "prices", "description": "Per-reference market values" }
  ],
  "security": [ { "bearerKey": [] }, { "queryKey": [] } ],
  "paths": {
    "/v1": {
      "get": {
        "summary": "API discovery (no key required)",
        "tags": ["index"],
        "security": [],
        "responses": { "200": { "description": "Endpoint list, tiers and status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Root" } } } } }
      }
    },
    "/v1/index": {
      "get": {
        "summary": "Latest index print",
        "tags": ["index"],
        "responses": { "200": { "description": "Latest level, components and changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexLatest" } } } } }
      }
    },
    "/v1/index/history": {
      "get": {
        "summary": "Full daily history of the index",
        "tags": ["index"],
        "responses": { "200": { "description": "Parallel arrays keyed by dates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexHistory" } } } } }
      }
    },
    "/v1/references": {
      "get": {
        "summary": "All tracked references with latest market value",
        "tags": ["prices"],
        "responses": { "200": { "description": "Reference list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferenceList" } } } } }
      }
    },
    "/v1/prices/{reference}": {
      "get": {
        "summary": "Latest market value for one reference",
        "tags": ["prices"],
        "parameters": [ { "$ref": "#/components/parameters/reference" } ],
        "responses": {
          "200": { "description": "Latest market value and changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/UpgradeRequired" },
          "404": { "description": "Reference not tracked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/prices/{reference}/history": {
      "get": {
        "summary": "Daily market value history for one reference",
        "tags": ["prices"],
        "parameters": [ { "$ref": "#/components/parameters/reference" } ],
        "responses": {
          "200": { "description": "Dates and values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceHistory" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/UpgradeRequired" },
          "404": { "description": "Reference not tracked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/v1/movers": {
      "get": {
        "summary": "Top gainers and losers over 7 days",
        "tags": ["prices"],
        "responses": { "200": { "description": "Movers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Movers" } } } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerKey": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer pk_live_..." },
      "queryKey": { "type": "apiKey", "in": "query", "name": "key", "description": "Fallback when headers cannot be set." }
    },
    "responses": {
      "Unauthorized": { "description": "Missing, unknown or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "UpgradeRequired": { "description": "Endpoint not included in the key's tier (history and movers on Free)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Daily limit reached; see Retry-After and reset_in_seconds", "headers": { "Retry-After": { "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "parameters": {
      "reference": {
        "name": "reference", "in": "path", "required": true,
        "description": "Rolex reference number, upper case, no spaces. Example: 126610LN. See /v1/references for the tracked set.",
        "schema": { "type": "string", "example": "126610LN" }
      }
    },
    "schemas": {
      "Meta": {
        "type": "object",
        "properties": {
          "api_version": { "type": "string", "example": "v1" },
          "as_of": { "type": "string", "format": "date", "description": "Date of the latest confirmed print" },
          "generated_at": { "type": "string", "description": "Build timestamp (UTC)" },
          "source": { "type": "string", "example": "thepulse.fun" },
          "license": { "type": "string" },
          "docs": { "type": "string", "format": "uri" }
        }
      },
      "Root": {
        "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": {
          "name": { "type": "string" }, "status": { "type": "string", "example": "beta" }, "auth": { "type": "string" },
          "endpoints": { "type": "array", "items": { "type": "string" } }, "openapi": { "type": "string", "format": "uri" } } } ]
      },
      "IndexLatest": {
        "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": {
          "index": { "type": "object", "properties": {
            "name": { "type": "string", "example": "The Pulse Rolex Index" },
            "base_date": { "type": "string", "format": "date" },
            "base_value": { "type": "number", "example": 100 },
            "level": { "type": "number", "description": "Headline index level" },
            "average_watch": { "type": "number", "description": "Equal-weight average of tracked references vs base, unsmoothed" },
            "average_watch_smoothed": { "type": "number", "description": "Exponentially smoothed average_watch, half-life 3 days" },
            "activity": { "type": "number", "description": "Sales pace vs baseline (100 = baseline)" },
            "activity_smoothed": { "type": "number" },
            "total_return": { "type": "number", "description": "Price and liquidity composite" },
            "typical_sale_usd": { "type": "number", "description": "Median basket sale value, adjusted for the ask-to-sold gap" },
            "confirmed_sales": { "type": "integer", "description": "Sales verified across two consecutive sweeps" },
            "dollar_flow_usd": { "type": "number" } } },
          "change_pct": { "type": "object", "properties": {
            "level_1d": { "type": "number", "nullable": true }, "level_7d": { "type": "number", "nullable": true }, "level_30d": { "type": "number", "nullable": true },
            "average_watch_7d": { "type": "number", "nullable": true }, "typical_sale_usd_7d": { "type": "number", "nullable": true } } },
          "history_days": { "type": "integer" },
          "references_tracked": { "type": "integer", "example": 14 },
          "field_notes": { "type": "object", "additionalProperties": { "type": "string" } } } } ]
      },
      "IndexHistory": {
        "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": {
          "index": { "type": "string" },
          "dates": { "type": "array", "items": { "type": "string", "format": "date" } },
          "level": { "type": "array", "items": { "type": "number" } },
          "average_watch": { "type": "array", "items": { "type": "number" } },
          "average_watch_smoothed": { "type": "array", "items": { "type": "number" } },
          "activity": { "type": "array", "items": { "type": "number" } },
          "activity_smoothed": { "type": "array", "items": { "type": "number" } },
          "total_return": { "type": "array", "items": { "type": "number" } },
          "typical_sale_usd": { "type": "array", "items": { "type": "number" } },
          "confirmed_sales": { "type": "array", "items": { "type": "integer" } },
          "dollar_flow_usd": { "type": "array", "items": { "type": "number" } } } } ]
      },
      "Price": {
        "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": {
          "reference": { "type": "string", "example": "126610LN" },
          "model": { "type": "string", "example": "Submariner Date" },
          "brand": { "type": "string", "example": "Rolex" },
          "market_value_usd": { "type": "number", "description": "Current market value from confirmed sales, adjusted for the ask-to-sold gap" },
          "change_1d_pct": { "type": "number", "nullable": true },
          "change_7d_pct": { "type": "number", "nullable": true },
          "change_30d_pct": { "type": "number", "nullable": true },
          "relative_level": { "type": "number", "description": "This reference's own level vs base 100" },
          "as_of": { "type": "string", "format": "date" },
          "history_days": { "type": "integer" },
          "index": { "type": "string", "example": "The Pulse Rolex Index" } } } ]
      },
      "PriceHistory": {
        "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": {
          "reference": { "type": "string" }, "model": { "type": "string" }, "brand": { "type": "string" },
          "dates": { "type": "array", "items": { "type": "string", "format": "date" } },
          "market_value_usd": { "type": "array", "items": { "type": "number" } },
          "relative_level": { "type": "array", "items": { "type": "number" }, "nullable": true } } } ]
      },
      "ReferenceList": {
        "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": {
          "count": { "type": "integer" },
          "references": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } } } } ]
      },
      "Movers": {
        "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": {
          "window": { "type": "string", "example": "7d" },
          "gainers": { "type": "array", "items": { "$ref": "#/components/schemas/Mover" } },
          "losers": { "type": "array", "items": { "$ref": "#/components/schemas/Mover" } } } } ]
      },
      "Mover": {
        "type": "object",
        "properties": { "reference": { "type": "string" }, "model": { "type": "string" }, "market_value_usd": { "type": "number" }, "change_7d_pct": { "type": "number" } }
      },
      "Plan": {
        "type": "object",
        "description": "Appended to every successful response.",
        "properties": {
          "tier": { "type": "string", "enum": ["free", "developer", "enterprise"] },
          "daily_limit": { "type": "integer" },
          "remaining": { "type": "integer" },
          "reset_in_seconds": { "type": "integer" },
          "upgrade": { "type": "string", "format": "uri", "nullable": true }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "enum": ["missing_api_key", "invalid_api_key", "upgrade_required", "unknown_reference", "not_found", "rate_limited", "data_unavailable"] },
          "message": { "type": "string" },
          "limit": { "type": "integer", "nullable": true },
          "remaining": { "type": "integer", "nullable": true },
          "reset_in_seconds": { "type": "integer", "nullable": true },
          "upgrade": { "type": "string", "format": "uri", "nullable": true },
          "signup": { "type": "string", "format": "uri", "nullable": true },
          "docs": { "type": "string", "format": "uri", "nullable": true }
        }
      }
    }
  }
}