{
  "openapi": "3.1.0",
  "info": {
    "title": "ChipWorth API",
    "version": "1.0.0",
    "description": "Fair market pricing for GPUs and AI hardware. Estimates from public listings, not appraisals. US market only. No price prediction.",
    "contact": { "name": "ChipWorth", "email": "r@agran.co", "url": "https://chipworth.xyz" }
  },
  "servers": [
    { "url": "https://chipworth.xyz" }
  ],
  "paths": {
    "/api/cards": {
      "get": {
        "operationId": "listCards",
        "summary": "List all catalog cards",
        "responses": {
          "200": {
            "description": "List of catalog cards",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CardsResponse" },
                "example": {
                  "cards": [
                    { "slug": "rtx-4090", "name": "NVIDIA GeForce RTX 4090", "brand": "NVIDIA", "category": "gpu", "vram_gb": 24, "msrp_usd": 1599 }
                  ],
                  "disclaimer": "Estimated ranges from public listings, not appraisals. US market only. No price prediction.",
                  "attribution": {},
                  "as_of": "2026-09-21T00:00:00.000Z"
                }
              }
            }
          }
        }
      }
    },
    "/api/price": {
      "get": {
        "operationId": "getPrice",
        "summary": "Get a fair price for a card at a given condition",
        "parameters": [
          { "name": "card", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Free text card identifier, e.g. \"4090\" or \"rtx 5060 ti 16gb\"." },
          { "name": "condition", "in": "query", "required": false, "schema": { "type": "string", "enum": ["new", "open_box", "used", "refurbished"], "default": "used" } }
        ],
        "responses": {
          "200": {
            "description": "Resolved card and price figures",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PriceResponse" },
                "example": {
                  "card": { "slug": "rtx-4090", "name": "NVIDIA GeForce RTX 4090", "brand": "NVIDIA", "category": "gpu", "vram_gb": 24, "msrp_usd": 1599 },
                  "msrp": 1599,
                  "condition": "used",
                  "new": { "anchor": 2900, "source": "bestbuy", "url": "https://www.bestbuy.com/site/example" },
                  "figures": { "fair": 2350, "low": 2200, "high": 2550, "sample": 42, "confidence": "high", "source": "ebay", "url": "https://www.ebay.com/sch/i.html?_nkw=RTX%204090" },
                  "disclaimer": "Estimated ranges from public listings, not appraisals. US market only. No price prediction.",
                  "attribution": { "ebay": "https://www.ebay.com/sch/i.html?_nkw=RTX%204090" },
                  "as_of": "2026-09-21T00:00:00.000Z"
                }
              }
            }
          },
          "404": { "description": "Card could not be resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" }, "example": { "error": "Could not resolve \"rtx 9999\" to a known card.", "suggestions": ["rtx-4090", "rtx-4080-super", "rtx-4070-ti-super"] } } } }
        }
      }
    },
    "/api/check": {
      "get": {
        "operationId": "checkPrice",
        "summary": "Judge whether an asking price is a good deal",
        "parameters": [
          { "name": "card", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "condition", "in": "query", "required": false, "schema": { "type": "string", "enum": ["new", "open_box", "used", "refurbished"], "default": "used" } },
          { "name": "price", "in": "query", "required": true, "schema": { "type": "number" }, "description": "The asking price to judge, in USD." }
        ],
        "responses": {
          "200": {
            "description": "Verdict on the given price",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CheckResponse" },
                "example": {
                  "card": { "slug": "rtx-4090", "name": "NVIDIA GeForce RTX 4090", "brand": "NVIDIA", "category": "gpu", "vram_gb": 24, "msrp_usd": 1599 },
                  "msrp": 1599,
                  "condition": "used",
                  "price": 1400,
                  "figures": { "fair": 2500, "low": 2199, "high": 2800, "sample": 0, "confidence": "catalog_only", "source": "catalog" },
                  "range": { "low": 2199, "high": 2800 },
                  "verdict": "underpriced",
                  "summary": "At $1400, this is well below the typical range ($2199-$2800) — verify the listing is legitimate before buying.",
                  "disclaimer": "Estimated ranges from public listings, not appraisals. US market only. No price prediction.",
                  "attribution": {},
                  "as_of": "2026-09-21T00:00:00.000Z"
                }
              }
            }
          },
          "400": { "description": "Missing or invalid price", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Missing or invalid required parameter: price" } } } },
          "404": { "description": "Card could not be resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" }, "example": { "error": "Could not resolve \"rtx 9999\" to a known card.", "suggestions": ["rtx-4090", "rtx-4080-super", "rtx-4070-ti-super"] } } } }
        }
      }
    },
    "/api/sell": {
      "get": {
        "operationId": "getSellPrice",
        "summary": "Get suggested list and quick-sale prices for a card",
        "parameters": [
          { "name": "card", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "condition", "in": "query", "required": false, "schema": { "type": "string", "enum": ["used", "refurbished"], "default": "used" } }
        ],
        "responses": {
          "200": {
            "description": "Suggested sell prices",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SellResponse" },
                "example": {
                  "card": { "slug": "rtx-3080", "name": "NVIDIA GeForce RTX 3080", "brand": "NVIDIA", "category": "gpu" },
                  "condition": "used",
                  "range": { "fair": 340, "low": 300, "high": 400, "sample": 0, "confidence": "catalog_only" },
                  "list_price": 368,
                  "quick_sale_price": 276,
                  "disclaimer": "Estimated ranges from public listings, not appraisals. US market only. No price prediction.",
                  "attribution": {},
                  "as_of": "2026-09-21T00:00:00.000Z"
                }
              }
            }
          },
          "404": { "description": "Card could not be resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } }
        }
      }
    },
    "/api/value": {
      "get": {
        "operationId": "getBestValue",
        "summary": "Rank cards by performance per dollar under a budget",
        "parameters": [
          { "name": "max_price", "in": "query", "required": false, "schema": { "type": "number" } },
          { "name": "condition", "in": "query", "required": false, "schema": { "type": "string", "enum": ["new", "used"], "default": "new" } },
          { "name": "resolution", "in": "query", "required": false, "schema": { "type": "string", "enum": ["1080p", "1440p", "4k"], "default": "1440p" }, "description": "Only 1440p performance data is supported in v0; other values are accepted but the index shown remains 1440p-based." }
        ],
        "responses": {
          "200": {
            "description": "Top value picks",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ValueResponse" },
                "example": {
                  "condition": "new",
                  "resolution": "1440p",
                  "max_price": 600,
                  "results": [
                    { "slug": "rx-9060-xt-16gb", "name": "AMD Radeon RX 9060 XT 16GB", "price": 465, "perf_index": 48, "perf_per_dollar": 0.103 }
                  ],
                  "disclaimer": "Estimated ranges from public listings, not appraisals. US market only. No price prediction.",
                  "attribution": {},
                  "as_of": "2026-09-21T00:00:00.000Z"
                }
              }
            }
          }
        }
      }
    },
    "/api/refresh": {
      "get": {
        "operationId": "refreshSnapshot",
        "summary": "Rebuild the pricing snapshot (cron / internal use)",
        "parameters": [
          { "name": "secret", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Alternative to the Authorization header." }
        ],
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Snapshot rebuilt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshResponse" }, "example": { "ok": true, "cards_refreshed": 30, "blob_written": true, "disclaimer": "Estimated ranges from public listings, not appraisals. US market only. No price prediction.", "attribution": {}, "as_of": "2026-09-21T00:00:00.000Z" } } } },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "Unauthorized" } } } }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Check configured data sources and snapshot freshness",
        "responses": {
          "200": {
            "description": "Health status",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" },
                "example": {
                  "ok": true,
                  "keys": { "ebay": false, "bestbuy": false, "blob": false },
                  "snapshot_as_of": "2026-09-21T00:00:00.000Z",
                  "disclaimer": "Estimated ranges from public listings, not appraisals. US market only. No price prediction.",
                  "attribution": {},
                  "as_of": "2026-09-21T00:00:00.000Z"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer" }
    },
    "schemas": {
      "Card": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "brand": { "type": "string", "enum": ["NVIDIA", "AMD", "Intel"] },
          "category": { "type": "string", "enum": ["gpu", "ai"] },
          "vram_gb": { "type": "number" },
          "msrp_usd": { "type": "number" }
        }
      },
      "CardsResponse": {
        "type": "object",
        "properties": {
          "cards": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } },
          "disclaimer": { "type": "string" },
          "attribution": { "type": "object" },
          "as_of": { "type": "string", "format": "date-time" }
        }
      },
      "PriceFigures": {
        "type": "object",
        "nullable": true,
        "properties": {
          "fair": { "type": "number", "nullable": true },
          "price": { "type": "number", "nullable": true },
          "low": { "type": "number", "nullable": true },
          "high": { "type": "number", "nullable": true },
          "p25": { "type": "number", "nullable": true },
          "p50": { "type": "number", "nullable": true },
          "p75": { "type": "number", "nullable": true },
          "sample": { "type": "integer" },
          "confidence": { "type": "string", "enum": ["high", "low", "none", "catalog_only", "medium"] },
          "source": { "type": "string" },
          "url": { "type": "string", "nullable": true }
        }
      },
      "PriceResponse": {
        "type": "object",
        "properties": {
          "card": { "$ref": "#/components/schemas/Card" },
          "msrp": { "type": "number" },
          "condition": { "type": "string" },
          "new": { "$ref": "#/components/schemas/PriceFigures" },
          "figures": { "$ref": "#/components/schemas/PriceFigures" },
          "disclaimer": { "type": "string" },
          "attribution": { "type": "object" },
          "as_of": { "type": "string", "format": "date-time" }
        }
      },
      "CheckResponse": {
        "type": "object",
        "properties": {
          "card": { "$ref": "#/components/schemas/Card" },
          "msrp": { "type": "number" },
          "condition": { "type": "string" },
          "price": { "type": "number" },
          "figures": { "$ref": "#/components/schemas/PriceFigures" },
          "range": {
            "type": "object",
            "properties": { "low": { "type": "number", "nullable": true }, "high": { "type": "number", "nullable": true } }
          },
          "verdict": { "type": "string", "enum": ["underpriced", "good_deal", "fair", "slightly_high", "overpriced"], "nullable": true },
          "summary": { "type": "string" },
          "disclaimer": { "type": "string" },
          "attribution": { "type": "object" },
          "as_of": { "type": "string", "format": "date-time" }
        }
      },
      "SellResponse": {
        "type": "object",
        "properties": {
          "card": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "string" }, "category": { "type": "string" } } },
          "condition": { "type": "string" },
          "range": { "$ref": "#/components/schemas/PriceFigures" },
          "list_price": { "type": "number", "nullable": true },
          "quick_sale_price": { "type": "number", "nullable": true },
          "disclaimer": { "type": "string" },
          "attribution": { "type": "object" },
          "as_of": { "type": "string", "format": "date-time" }
        }
      },
      "ValueResult": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "price": { "type": "number" },
          "perf_index": { "type": "number" },
          "perf_per_dollar": { "type": "number" }
        }
      },
      "ValueResponse": {
        "type": "object",
        "properties": {
          "condition": { "type": "string" },
          "resolution": { "type": "string" },
          "max_price": { "type": "number", "nullable": true },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/ValueResult" } },
          "note": { "type": "string" },
          "disclaimer": { "type": "string" },
          "attribution": { "type": "object" },
          "as_of": { "type": "string", "format": "date-time" }
        }
      },
      "RefreshResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "cards_refreshed": { "type": "integer" },
          "blob_written": { "type": "boolean" },
          "disclaimer": { "type": "string" },
          "attribution": { "type": "object" },
          "as_of": { "type": "string", "format": "date-time" }
        }
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "keys": {
            "type": "object",
            "properties": { "ebay": { "type": "boolean" }, "bestbuy": { "type": "boolean" }, "blob": { "type": "boolean" } }
          },
          "snapshot_as_of": { "type": "string", "format": "date-time", "nullable": true },
          "disclaimer": { "type": "string" },
          "attribution": { "type": "object" },
          "as_of": { "type": "string", "format": "date-time" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": { "error": { "type": "string" } }
      },
      "NotFoundResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "suggestions": { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  }
}