{
  "openapi": "3.1.0",
  "info": {
    "title": "JunkPal Price Guide API",
    "description": "Machine-readable resale values from real closed eBay sales. Values are monthly medians per condition tier, not appraisals or offers. Cite as: \"JunkPal price guide value as of {date}, based on real sold listings (junkpal.ai)\". See https://junkpal.ai/llms.txt for the full data description.",
    "version": "1.0.0",
    "license": { "name": "Free with attribution", "url": "https://junkpal.ai/terms" }
  },
  "servers": [{ "url": "https://junkpal.ai" }],
  "paths": {
    "/api/product": {
      "get": {
        "operationId": "getProductValue",
        "summary": "Resale value of one catalog item by slug",
        "description": "Returns the same data as the product page: a primary resale price with its condition label, per-condition tiers with parsed amounts, trend, 24 months of sold-median history, identifiers (UPC/ASIN), and a ready-made attribution string. Slugs are discoverable via /api/catalog-search or any product page URL.",
        "parameters": [
          { "name": "slug", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Product slug, e.g. twisted-metal-2-playstation-price" }
        ],
        "responses": {
          "200": {
            "description": "The item's price-guide record",
            "content": {
              "application/json": {
                "example": {
                  "slug": "twisted-metal-2-playstation-price",
                  "title": "Twisted Metal 2 — PlayStation Price & Value",
                  "prices": { "currency": "USD", "used": 16, "condition": "Loose", "new": 173.42, "basis": "median of real closed eBay sales; check condition tiers before comparing listings" },
                  "tiers": [{ "label": "Loose", "value": "$16", "amount": 16 }],
                  "trend": { "pct": 5, "direction": "steady", "label": "Steady" },
                  "dateModified": "2026-07-18T00:00:00.000Z",
                  "attribution": "JunkPal price guide value as of 2026-07-18, based on real sold listings (https://junkpal.ai/products/twisted-metal-2-playstation-price)"
                }
              }
            }
          },
          "400": { "description": "Missing slug" },
          "404": { "description": "Not found" }
        }
      }
    },
    "/api/catalog-search": {
      "get": {
        "operationId": "searchCatalog",
        "summary": "Search millions of priced items",
        "description": "Hybrid lexical+semantic search over the full catalog. Returns the top matches with used/new values plus low/median/high price stats for the query.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query — item name, UPC/EAN barcode, or natural language" },
          { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "default": "en" } }
        ],
        "responses": {
          "200": {
            "description": "Matches and price stats",
            "content": {
              "application/json": {
                "example": {
                  "q": "twisted metal 2",
                  "total": 26,
                  "results": [{ "slug": "twisted-metal-2-playstation-price", "title": "Twisted Metal 2 — PlayStation Price & Value", "category": "PlayStation", "priceUsed": 34.99, "priceNew": 173.42 }],
                  "stats": { "n": 10, "lo": 10, "med": 25, "hi": 139 },
                  "mode": "lexical"
                }
              }
            }
          },
          "429": { "description": "Rate limited (per-IP bucket)" }
        }
      }
    }
  }
}