{"openapi":"3.1.0","info":{"title":"Card Hedge API","description":"Unified public API service for Card Hedge","version":"v1"},"paths":{"/v1/cards/top-movers":{"get":{"tags":["Market Data"],"summary":"Get Top Movers","description":"Get cards with positive price changes over the last week.\n\nFetches top moving cards from CardHedge API and filters out unrealistic gains (>= 500%).\nRequests 5x the desired count from external API to ensure sufficient results after filtering.\nResults are cached for 1 hour to improve performance.\n\n**Example curl:**\n```bash\n# All categories\ncurl -H \"X-API-Key: your-api-key-here\" \\\n     \"https://api.cardhedger.com/v1/cards/top-movers?count=20\"\n\n# Baseball only\ncurl -H \"X-API-Key: your-api-key-here\" \\\n     \"https://api.cardhedger.com/v1/cards/top-movers?count=20&category=Baseball\"\n```\n\nReturns cards with realistic price increases (< 500% gain), limited to requested count.","operationId":"get_top_movers","parameters":[{"name":"count","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Number of cards to return","default":20,"title":"Count"},"description":"Number of cards to return"},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional category filter (e.g., 'Baseball', 'Basketball', 'Pokemon')","title":"Category"},"description":"Optional category filter (e.g., 'Baseball', 'Basketball', 'Pokemon')"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopMoversResponse"},"examples":{"default":{"summary":"Top movers response","value":{"cards":[{"description":"Shohei Ohtani 2018 Topps Chrome Baseball","player":"Shohei Ohtani","set":"2018 Topps Chrome Baseball","number":"150","variant":"Refractor","card_id":"1587446850514x224832321163624450","image":"//s3.amazonaws.com/appforest_uf/example.jpg","category":"Baseball","category_group":"Sports Cards","set_type":"Topps Chrome Baseball","30 Day Sales":45,"rookie":true,"gain":650.5,"prices":[{"grade":"PSA 10","price":"2500"},{"grade":"PSA 9","price":"850"}]}],"total_count":50,"filtered_count":1,"gain_threshold":500.0}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/card-search":{"post":{"tags":["Card Search"],"summary":"Search Cards","description":"Search for cards with flexible filtering options.\n\nSearches CardHedge database with optional filters for search query, set, category,\nplayer, and rookie status. Supports pagination to iterate through large result sets.\n\n**Response includes:**\n- `pages`: Total number of pages available\n- `count`: Total number of matching cards\n- `cards`: Array of card objects for the current page\n\n**Example curl:**\n```bash\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"search\": \"Shohei Ohtani\",\n       \"category\": \"Baseball\",\n       \"page\": 1,\n       \"page_size\": 20\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/card-search\"\n```\n\nReturns matching cards with pricing, sales data, and pagination metadata.","operationId":"search_cards","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardSearchRequest"},"examples":{"player_search":{"summary":"Search by player name","description":"Find Shohei Ohtani baseball cards","value":{"search":"Shohei Ohtani","category":"Baseball","page":1,"page_size":20}},"paginated_search":{"summary":"Paginated search","description":"Get page 2 of search results","value":{"search":"Mike Trout","category":"Baseball","page":2,"page_size":50}},"rookie_cards":{"summary":"Find rookie cards","description":"Search for rookie cards by player","value":{"search":"Mike Trout","category":"Baseball","rookie":"yes","page":1,"page_size":10}},"set_search":{"summary":"Search specific set","description":"Find cards from 2023 Topps Chrome","value":{"set":"2023 Topps Chrome","category":"Baseball","page":1,"page_size":50}},"raw_images":{"summary":"Cards with raw images only","description":"Search with only actual card photos","value":{"search":"Pikachu","raw_images_only":true,"page":1,"page_size":25}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardSearchResponse"},"examples":{"default":{"summary":"Card search response","value":{"pages":15,"count":742,"cards":[{"description":"Shohei Ohtani 2018 Topps Chrome Baseball","player":"Shohei Ohtani","set":"2018 Topps Chrome Baseball","number":"150","variant":"Base","card_id":"1587446850514x224832321163624450","image":"//s3.amazonaws.com/appforest_uf/example.jpg","category":"Baseball","category_group":"Sports Cards","set_type":"Topps Chrome Baseball","7 Day Sales":45,"30 Day Sales":187,"rookie":true,"gain":2.5,"prices":[{"grade":"PSA 10","price":"850"},{"grade":"PSA 9","price":"125"},{"grade":"Raw","price":"45.99"}]}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/card-match":{"post":{"tags":["Card Search"],"summary":"AI-powered card matching","description":"Match a natural language card description to the best card in the CardHedge database.\n\nUses AI to evaluate search results and return the single best match with a confidence score.\n\n**How it works:**\n1. Your query is sent to the card search API to find candidates\n2. An LLM evaluates each candidate against your description\n3. The best match is returned with a confidence score (0.0 - 1.0)\n\n**Confidence levels:**\n- **0.9 - 1.0**: Very high confidence — near-exact match\n- **0.7 - 0.9**: High confidence — likely correct match\n- **0.5 - 0.7**: Moderate confidence — possible match, verify manually\n- **Below 0.5**: No match returned (threshold not met)\n\n**Example curl:**\n```bash\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"query\": \"2025 Topps Chrome Cooper Flagg 251\",\n       \"category\": \"Basketball\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/card-match\"\n```","operationId":"match_card","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardMatchRequest"},"examples":{"specific_card":{"summary":"Specific card with number","description":"Match a card by set, player, and card number","value":{"query":"2018 Topps Chrome Shohei Ohtani #150","category":"Baseball","max_candidates":10}},"card_number_only":{"summary":"Set and card number","description":"Match using set name and card number","value":{"query":"2023 Topps Chrome #1 Mike Trout","category":"Baseball"}},"pokemon_with_number":{"summary":"Pokemon card with number","description":"Match a Pokemon card by name and set number","value":{"query":"Charizard VMAX #20 Darkness Ablaze","category":"Pokemon"}},"general_description":{"summary":"General description","description":"Match from a looser description without card number","value":{"query":"Pikachu VMAX rainbow rare Vivid Voltage","category":"Pokemon"}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardMatchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/set-search":{"post":{"tags":["Card Search"],"summary":"Search Card Sets","description":"Search for card sets with optional name and category filters.\n\nSearch the CardHedge database for sets by name and/or category. Useful for\npopulating set dropdowns, browsing available sets, or finding specific product lines.\n\n**Parameters:**\n- `search`: Optional text query matched against set names (e.g., \"Topps Chrome\", \"Pokemon 151\")\n- `category`: Optional category filter (e.g., \"Baseball\", \"Basketball\", \"Pokemon\", \"Football\")\n- `count`: Number of results to return (1-100, default: 25)\n\n**Response includes:**\n- `count`: Number of sets returned\n- `sets`: Array of set objects with name, year, category, image, and 30-day sales volume\n\n**Example curl:**\n```bash\n# Search by name\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"search\": \"Pokemon 151\",\n       \"count\": 10\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/set-search\"\n\n# Filter by category\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"category\": \"Baseball\",\n       \"count\": 25\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/set-search\"\n\n# Combined search + category\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"search\": \"Topps Chrome\",\n       \"category\": \"Baseball\",\n       \"count\": 50\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/set-search\"\n```\n\nReturns matching sets with metadata and sales data.","operationId":"search_sets","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetSearchRequest"},"examples":{"search_by_name":{"summary":"Search by set name","description":"Find sets matching a text query like 'Pokemon 151' or 'Topps Chrome'","value":{"search":"Pokemon 151","count":10}},"filter_by_category":{"summary":"Browse by category","description":"List sets in a specific category (e.g., Baseball, Basketball, Pokemon, Football)","value":{"category":"Baseball","count":25}},"combined_search":{"summary":"Name + category filter","description":"Search within a category for more precise results","value":{"search":"Topps Chrome","category":"Baseball","count":50}},"minimal_request":{"summary":"Browse all sets","description":"No filters — returns the first 25 sets (default count)","value":{}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetSearchResponse"},"examples":{"baseball_sets":{"summary":"Baseball set search results","value":{"count":3,"sets":[{"id":"1587446850514x224832321163624450","name":"2023 Topps Chrome Baseball","year":"2023","set_type":"Topps Chrome Baseball","description":"2023 Topps Chrome Baseball","category":"Baseball","image":"//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1724143874181x158765543979815900/crop_image","30 Day Sales":1250},{"id":"1684286084852x189232814543430100","name":"2024 Topps Chrome Baseball","year":"2024","set_type":"Topps Chrome Baseball","description":"2024 Topps Chrome Baseball","category":"Baseball","image":"//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1724143874181x158765543979815901/crop_image","30 Day Sales":2340},{"id":"1699670576265x928796749151534600","name":"2022 Topps Chrome Baseball","year":"2022","set_type":"Topps Chrome Baseball","description":"2022 Topps Chrome Baseball","category":"Baseball","image":"//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1724143874181x158765543979815902/crop_image","30 Day Sales":870}]}},"pokemon_sets":{"summary":"Pokemon set search results","value":{"count":2,"sets":[{"id":"1700000000001x100000000000000001","name":"2023 Pokemon 151","year":"2023","set_type":"Pokemon 151","description":"2023 Pokemon 151","category":"Pokemon","image":"//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1724143874181x158765543979815903/crop_image","30 Day Sales":3450},{"id":"1700000000002x100000000000000002","name":"2024 Pokemon 151 Japanese","year":"2024","set_type":"Pokemon 151","description":"2024 Pokemon 151 Japanese","category":"Pokemon","image":"//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1724143874181x158765543979815904/crop_image","30 Day Sales":1820}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/search-cards-wsort":{"post":{"tags":["Card Search"],"summary":"Search Cards with Sorting","description":"Search for cards from the database with full-text search, filtering, sorting, and pagination.\n\n**⚠️ Required:** At least one filter parameter (`search`, `set`, `category`, or `player`) is required.\n\n**Search Parameter:**\n- `search`: Full-text fuzzy search across card description and player names\n- Supports multiple keywords: \"Shohei Ohtani rookie\" matches cards containing all terms\n\n**Filter Parameters (exact match):**\n- `player`: Exact player name match (e.g., \"Mike Trout\")\n- `set`: Exact set name match (e.g., \"2018 Panini Prizm Basketball\")\n- `category`: Exact category match (e.g., \"Baseball\", \"Pokemon\", \"Basketball\")\n\n**Sorting Options:**\n- `sort_by`:\n  - `\"gain\"` - 7-day price change percentage\n  - `\"gain_30day\"` - 30-day price change percentage\n  - `\"sales_7day\"` - 7-day sales volume\n  - `\"sales_30day\"` - 30-day sales volume\n  - `\"sales\"` - alias for sales_30day (backwards compatible)\n  - `\"price\"` - current price\n  - `\"description\"` - alphabetical\n- `sort_order`: \"asc\" or \"desc\"\n\n**Other Options:**\n- `raw_images_only`: When true, returns raw card images instead of graded slab images\n- `page` / `page_size`: Pagination controls (max 100 per page)\n\n**Response:**\n- `pages`: Total pages available\n- `count`: Total matching cards\n- `cards`: Array of card objects including:\n  - `gain`: 7-day price change percentage\n  - `gain_30day`: 30-day price change percentage\n  - `7 Day Sales` / `30 Day Sales`: Sales volume\n  - `prices`: Array of grade/price pairs","operationId":"search_cards_sorted","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardSearchLocalRequest"},"examples":{"basic_search":{"summary":"Basic full-text search","description":"Search for cards using keywords. Uses PostgreSQL full-text search for fast, fuzzy matching.","value":{"search":"Shohei Ohtani","page":1,"page_size":20}},"search_with_category":{"summary":"Search within category","description":"Combine full-text search with exact category filter","value":{"search":"rookie chrome","category":"Baseball","page":1,"page_size":25,"sort_by":"sales_30day","sort_order":"desc"}},"exact_player_filter":{"summary":"Filter by exact player","description":"Find all cards for a specific player. Player name must match exactly.","value":{"player":"Mike Trout","search":"Topps","page":1,"page_size":20,"sort_by":"gain","sort_order":"desc"}},"exact_set_filter":{"summary":"Filter by exact set","description":"Find cards from a specific set. Set name must match exactly.","value":{"set":"2018 Panini Prizm Basketball","search":"Luka","page":1,"page_size":20,"sort_by":"price","sort_order":"desc"}},"pokemon_by_sales_30day":{"summary":"Pokemon sorted by 30-day sales","description":"Find popular Pokemon cards sorted by 30-day sales volume","value":{"search":"Charizard","category":"Pokemon","page":1,"page_size":50,"sort_by":"sales_30day","sort_order":"desc"}},"trending_7day":{"summary":"Trending cards (7-day sales)","description":"Find cards with high recent activity sorted by 7-day sales","value":{"category":"Baseball","page":1,"page_size":50,"sort_by":"sales_7day","sort_order":"desc"}},"raw_images":{"summary":"With raw images only","description":"Return raw card images instead of graded slab images","value":{"search":"Pikachu","category":"Pokemon","raw_images_only":true,"page":1,"page_size":20}},"highest_gainers_7day":{"summary":"Biggest 7-day price gainers","description":"Find cards with highest 7-day price gains","value":{"search":"prizm","category":"Basketball","sort_by":"gain","sort_order":"desc","page":1,"page_size":20}},"highest_gainers_30day":{"summary":"Biggest 30-day price gainers","description":"Find cards with highest 30-day price gains","value":{"search":"chrome","category":"Baseball","sort_by":"gain_30day","sort_order":"desc","page":1,"page_size":20}},"alphabetical_sort":{"summary":"Alphabetical sorting","description":"Sort cards alphabetically by description","value":{"category":"Pokemon","sort_by":"description","sort_order":"asc","page":1,"page_size":50}},"highest_priced":{"summary":"Most expensive cards","description":"Find the highest priced cards in a category","value":{"category":"Baseball","sort_by":"price","sort_order":"desc","page":1,"page_size":20}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardSearchLocalResponse"},"examples":{"default":{"summary":"Card search response","value":{"pages":15,"count":742,"cards":[{"description":"Shohei Ohtani 2024 Topps Chrome Baseball","player":"Shohei Ohtani","set":"2024 Topps Chrome Baseball","number":"150","variant":"Base","card_id":"1587446850514x224832321163624450","image":"https://example.com/card.jpg","category":"Baseball","category_group":"Sports Cards","set_type":"Topps Chrome Baseball","7 Day Sales":45,"30 Day Sales":187,"rookie":false,"gain":12.5,"gain_30day":18.3,"prices":[{"grade":"PSA 10","price":"850"},{"grade":"PSA 9","price":"125"},{"grade":"Raw","price":"45.99"}]}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/card-details":{"post":{"tags":["Card Details"],"summary":"Get Card Details by ID","description":"Get detailed information for a specific card by its ID.\n\nRequires a card_id. If you only have a card name/description, call `match_card` or\n`search_cards` first to get the card_id, then use it here.\n\nFetches card details from CardHedge database using the card's unique identifier.\nReturns the same data structure as card search endpoint.\n\n**Example curl:**\n```bash\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"card_id\": \"1586812246197x228181943611293700\"}' \\\n     \"https://api.cardhedger.com/v1/cards/card-details\"\n```\n\nReturns card with pricing, sales data, and metadata.","operationId":"get_card_details","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardDetailsRequest"},"examples":{"basic":{"summary":"Get card details","description":"Fetch details for a specific card","value":{"card_id":"1586812246197x228181943611293700"}},"with_raw_images":{"summary":"Get card with raw images only","description":"Fetch card details with only actual card photos","value":{"card_id":"1586812246197x228181943611293700","raw_images_only":true}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardSearchResponse"},"examples":{"default":{"summary":"Card details response","value":{"cards":[{"description":"Mike Trout 2011 Topps Update Baseball","player":"Mike Trout","set":"2011 Topps Update Baseball","number":"US175","variant":"Base","card_id":"1586812246197x228181943611293700","image":"//s3.amazonaws.com/appforest_uf/f1586812239788x796554493579861000/2011-Mike-Trout-Topps-Update-US175-Graded.jpg","category":"Baseball","category_group":"Sports Cards","set_type":"Topps Update Baseball","7 Day Sales":27,"30 Day Sales":103,"rookie":true,"gain":0.5,"prices":[{"grade":"PSA 10","price":"1000"},{"grade":"PSA 9","price":"319.99"},{"grade":"Raw","price":"269.39"}]}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/prices-by-cert":{"post":{"tags":["Pricing & Valuations"],"summary":"Get Card Prices by Certificate Number","description":"Get card information and pricing by grader certificate number.\n\nThis endpoint performs a multi-step lookup:\n1. Queries GemRate API to find certificate details and GemRate IDs\n2. Fetches card details from CardHedge using GemRate IDs\n3. Retrieves price history for the card at the specified grade\n\n**Example curl:**\n```bash\n# Default: 180 days of price history\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"cert\": \"76676185\",\n       \"grader\": \"PSA\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/prices-by-cert\"\n\n# Custom: 30 days of price history\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"cert\": \"76676185\",\n       \"grader\": \"PSA\",\n       \"days\": 30\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/prices-by-cert\"\n```\n\nReturns certificate info, card details, and price history (default: 180 days, max: 365 days).","operationId":"get_prices_by_cert","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertLookupRequest"},"examples":{"default_days":{"summary":"Default (180 days)","description":"Lookup PSA cert with default 180 days of price history","value":{"cert":"76676185","grader":"PSA"}},"custom_days":{"summary":"Custom duration (30 days)","description":"Lookup PSA cert with 30 days of price history","value":{"cert":"50000000","grader":"PSA","days":30}},"bgs_example":{"summary":"BGS certificate","description":"Lookup BGS graded card","value":{"cert":"12345678","grader":"BGS","days":90}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertLookupResponse"},"examples":{"default":{"summary":"Prices by certificate response","value":{"cert_info":{"grader":"psa","cert":"50000000","grade":"PSA 10","gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885","universal_gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885","description":"1999 Bowman Chrome C.C. Sabathia 344"},"card":{"card_id":"1699670576265x928796749151534600","description":"C.C. Sabathia 1999 Bowman Chrome Baseball","player":"C.C. Sabathia","set":"1999 Bowman Chrome Baseball","number":"344","variant":"Base","image":"https://942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1699670857725x475053799924132860/resized_20231111_024737.jpeg","category":"Baseball","category_group":"Sports Cards","set_type":"Bowman Chrome Baseball"},"prices":[{"closing_date":"2025-10-26T23:59:00.000Z","Grade":"PSA 10","card_id":"1699670576265x928796749151534600","price":"125.50"},{"closing_date":"2025-10-25T23:59:00.000Z","Grade":"PSA 10","card_id":"1699670576265x928796749151534600","price":"122.00"}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/batch-prices-by-cert":{"post":{"tags":["Pricing & Valuations"],"summary":"Get Best Price Estimates by Certificate Numbers (Batch)","description":"Get price estimates for multiple cards by their grader certificate numbers.\n\nFor each certificate, this endpoint:\n1. Queries GemRate API to find certificate details (grade, card identity)\n2. Fetches card details from CardHedge using GemRate IDs\n3. Calls the price estimation service for the card at the certificate's grade\n\nAll certificates are processed in parallel (max 20 concurrent) for optimal performance.\n\n**Example curl:**\n```bash\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"certs\": [\"76676185\", \"50000000\"],\n       \"grader\": \"PSA\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/batch-prices-by-cert\"\n```\n\nReturns certificate info, card details, and price estimates for each cert.\nMaximum 100 certificates per request.","operationId":"get_batch_prices_by_cert","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertPriceRequest"},"examples":{"multiple_psa":{"summary":"Multiple PSA certificates","description":"Lookup prices for multiple PSA graded cards","value":{"certs":["76676185","50000000","12345678"],"grader":"PSA"}},"single_cert":{"summary":"Single certificate","description":"Lookup price for a single certificate","value":{"certs":["50000000"],"grader":"PSA"}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertPriceResponse"},"examples":{"default":{"summary":"Batch price estimates by certificate","value":{"results":[{"cert_info":{"grader":"psa","cert":"50000000","grade":"PSA 10","gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885","universal_gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885","description":"1999 Bowman Chrome C.C. Sabathia 344"},"card":{"card_id":"1699670576265x928796749151534600","description":"C.C. Sabathia 1999 Bowman Chrome Baseball","player":"C.C. Sabathia","set":"1999 Bowman Chrome Baseball","number":"344","variant":"Base","image":"https://example.com/card.jpg","category":"Baseball","category_group":"Sports Cards","set_type":"Bowman Chrome Baseball"},"price":125.5,"price_low":110.0,"price_high":141.0,"confidence":0.3869,"method":"direct"}],"total_requested":2,"total_found":1}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/prices-by-cert-ocr":{"post":{"tags":["Image Search"],"summary":"Get Card Prices by Graded Card Image","description":"Extract grader and certificate number from a graded card image, then look up pricing.\n\nThis endpoint uses AI vision to read the grading label from a card image,\nextracts the grading company (PSA, BGS, CGC, etc.) and certificate number,\nthen performs the same lookup as `/prices-by-cert`.\n\nProvide either `image_url` (public URL) or `image_base64` (base64-encoded image).\n\n**Example curl:**\n```bash\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"image_url\": \"https://example.com/graded-card.jpg\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/prices-by-cert-ocr\"\n```\n\nReturns certificate info, card details, and price history (same as prices-by-cert).","operationId":"get_prices_by_cert_image_v1_cards_prices_by_cert_ocr_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageCertLookupRequest"},"examples":{"image_url":{"summary":"Image URL","description":"Lookup graded card from image URL","value":{"image_url":"https://example.com/graded-card.jpg","days":180}},"image_base64":{"summary":"Base64 image","description":"Lookup graded card from base64-encoded image","value":{"image_base64":"data:image/jpeg;base64,/9j/4AAQSkZJRg...","days":180}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertLookupResponse"},"examples":{"default":{"summary":"Prices by cert image response","value":{"cert_info":{"grader":"psa","cert":"50000000","grade":"PSA 10","gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885","universal_gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885","description":"1999 Bowman Chrome C.C. Sabathia 344"},"card":{"card_id":"1699670576265x928796749151534600","description":"C.C. Sabathia 1999 Bowman Chrome Baseball","player":"C.C. Sabathia","set":"1999 Bowman Chrome Baseball","number":"344","variant":"Base","image":"https://example.com/card.jpg","category":"Baseball","category_group":"Sports Cards","set_type":"Bowman Chrome Baseball"},"prices":[{"closing_date":"2025-10-26T23:59:00.000Z","Grade":"PSA 10","card_id":"1699670576265x928796749151534600","price":"125.50"}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/details-by-cert-ocr":{"post":{"tags":["Image Search"],"summary":"Get Card Details by Graded Card Image","description":"Extract grader and certificate number from a graded card image, then look up card details.\n\nThis endpoint uses AI vision to read the grading label from a card image,\nextracts the grading company (PSA, BGS, CGC, etc.) and certificate number,\nthen returns certificate info and card details (without price history).\n\nSame as `/details-by-certs` but accepts an image instead of certificate numbers.\n\nProvide either `image_url` (public URL) or `image_base64` (base64-encoded image).\n\n**Example curl:**\n```bash\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"image_url\": \"https://example.com/graded-card.jpg\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/details-by-cert-ocr\"\n```\n\nReturns certificate info and card details (no price history).","operationId":"get_details_by_cert_image_v1_cards_details_by_cert_ocr_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageCertDetailsRequest"},"examples":{"image_url":{"summary":"Image URL","description":"Get card details from graded card image URL","value":{"image_url":"https://example.com/graded-card.jpg"}},"image_base64":{"summary":"Base64 image","description":"Get card details from base64-encoded graded card image","value":{"image_base64":"data:image/jpeg;base64,/9j/4AAQSkZJRg..."}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleCertResult"},"examples":{"default":{"summary":"Card details from image","value":{"cert_info":{"grader":"psa","cert":"145110823","grade":"PSA 10","gemrate_id":"abc123","universal_gemrate_id":"abc123","description":"2025 Topps Cooper Flagg 201"},"card":{"card_id":"1699670576265x928796749151534600","description":"Cooper Flagg 2025 Topps Basketball","player":"Cooper Flagg","set":"2025 Topps Basketball","number":"201","variant":"Base","image":"https://example.com/flagg.jpg","category":"Basketball","category_group":"Sports Cards","set_type":"Topps Basketball"}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/details-by-certs":{"post":{"tags":["Pricing & Valuations"],"summary":"Get Card Details by Certificate Numbers (Batch)","description":"Get card details for multiple certificate numbers in a single request.\n\nThis endpoint performs batch lookups without price history:\n1. Queries GemRate API for each certificate to find certificate details and GemRate IDs\n2. Fetches card details from CardHedge using GemRate IDs\n3. Returns certificate info and card details (or null if not found in CardHedge)\n\n**Example curl:**\n```bash\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"certs\": [\"76676185\", \"50000000\", \"12345678\"],\n       \"grader\": \"PSA\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/details-by-certs\"\n```\n\nReturns card details for each certificate. Cards not found in CardHedge will have null card field.\nMaximum 100 certificates per request.","operationId":"get_details_by_certs","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCertLookupRequest"},"examples":{"example1":{"summary":"Multiple PSA certificates","description":"Lookup multiple PSA graded cards","value":{"certs":["76676185","50000000","12345678"],"grader":"PSA"}},"example2":{"summary":"Single BGS certificate","description":"Lookup a single BGS graded card","value":{"certs":["12345678"],"grader":"BGS"}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCertLookupResponse"},"examples":{"default":{"summary":"Batch certificate lookup response","value":{"results":[{"cert_info":{"grader":"psa","cert":"76676185","grade":"PSA 9","gemrate_id":"9f4cd2db01a0a873ba5da0feb23428686fd556ac","universal_gemrate_id":"9f4cd2db01a0a873ba5da0feb23428686fd556ac","description":"2000 Pokemon Japanese Neo Wooper 194"}},{"cert_info":{"grader":"psa","cert":"50000000","grade":"PSA 10","gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885","universal_gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885","description":"1999 Bowman Chrome C.C. Sabathia 344"},"card":{"card_id":"1699670576265x928796749151534600","description":"C.C. Sabathia 1999 Bowman Chrome Baseball","player":"C.C. Sabathia","set":"1999 Bowman Chrome Baseball","number":"344","variant":"Base","image":"https://942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1699670857725x475053799924132860/resized_20231111_024737.jpeg","category":"Baseball","category_group":"Sports Cards","set_type":"Bowman Chrome Baseball"}}],"total_requested":2,"total_found":1}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/prices-by-card":{"post":{"tags":["Pricing & Valuations"],"summary":"Get Card Prices by Card ID","description":"Get price history for a specific card and grade.\n\nRequires a card_id. If you only have a card name/description, call `match_card` or\n`search_cards` first to get the card_id, then use it here.\n\nRetrieves historical pricing data from CardHedge for a given card ID and grade.\nResults are cached for improved performance.\n\n**Example curl:**\n```bash\n# Default: 180 days of price history\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"card_id\": \"1587446850514x224832321163624450\",\n       \"grade\": \"PSA 9\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/prices-by-card\"\n\n# Custom: 30 days of price history\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"card_id\": \"1587446850514x224832321163624450\",\n       \"grade\": \"PSA 9\",\n       \"days\": 30\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/prices-by-card\"\n```\n\nReturns price history (default: 180 days, max: 365 days).","operationId":"get_price_history","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricesByCardRequest"},"examples":{"default_days":{"summary":"Default (180 days)","description":"Get price history with default 180 days","value":{"card_id":"1587446850514x224832321163624450","grade":"PSA 9"}},"custom_days":{"summary":"Custom duration (30 days)","description":"Get price history with 30 days","value":{"card_id":"1587446850514x224832321163624450","grade":"PSA 9","days":30}},"bgs_example":{"summary":"BGS graded card","description":"Get price history for BGS graded card","value":{"card_id":"1587446850514x224832321163624450","grade":"BGS 9.5","days":90}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricesByCardResponse"},"examples":{"default":{"summary":"Price history response","value":{"prices":[{"closing_date":"2025-10-26T23:59:00.000Z","Grade":"PSA 9","card_id":"1587446850514x224832321163624450","price":"337.67"},{"closing_date":"2025-10-25T23:59:00.000Z","Grade":"PSA 9","card_id":"1587446850514x224832321163624450","price":"337.00"},{"closing_date":"2025-10-24T23:59:00.000Z","Grade":"PSA 9","card_id":"1587446850514x224832321163624450","price":"331.29"}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/comps":{"post":{"tags":["Pricing & Valuations"],"summary":"Get Comparable Prices (COMPS)","description":"Get comparable prices (COMPS) for a card with anomaly filtering and optional time-weighting.\n\nRequires a card_id. If you only have a card name/description, call `match_card` or\n`search_cards` first to get the card_id, then use it here.\n\nThis endpoint:\n1. Fetches recent sales from CardHedge API (count + 2 to help preserve requested depth)\n2. Filters only statistical price anomalies using IQR fences (keeps non-anomalous highs/lows)\n3. Calculates comp price using either:\n   - Simple average (default)\n   - Weighted Moving Average (if time_weighted=True), giving recent sales more weight\n4. Returns low/high prices from the sales used in the comp\n5. Optionally returns raw price data (if include_raw_prices=True)\n\n**Time-Weighting Algorithm (WMA):**\nWhen time_weighted=True, recent sales are weighted more heavily:\n- Most recent sale: weight = n\n- Second most recent: weight = n-1\n- ...\n- Oldest sale: weight = 1\n- Formula: (P1*n + P2*(n-1) + ... + Pn*1) / (n + (n-1) + ... + 1)\n\n**Example curl:**\n```bash\n# Basic comp (simple average)\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"card_id\": \"1587446850514x224832321163624450\",\n       \"count\": 10,\n       \"grade\": \"PSA 9\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/comps\"\n\n# Time-weighted comp with raw prices\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"card_id\": \"1587446850514x224832321163624450\",\n       \"count\": 10,\n       \"grade\": \"PSA 10\",\n       \"time_weighted\": true,\n       \"include_raw_prices\": true\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/comps\"\n```\n\nReturns calculated comp price with anomaly-aware filtering.","operationId":"get_comps","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompsRequest"},"examples":{"basic_comp":{"summary":"Basic comp price","description":"Get simple average comp price for 10 sales","value":{"card_id":"1587446850514x224832321163624450","count":10,"grade":"PSA 9"}},"time_weighted":{"summary":"Time-weighted comp","description":"Get comp price with recent sales weighted more heavily","value":{"card_id":"1587446850514x224832321163624450","count":10,"grade":"PSA 10","time_weighted":true}},"with_raw_prices":{"summary":"Include raw prices","description":"Get comp with source price data included","value":{"card_id":"1587446850514x224832321163624450","count":20,"grade":"BGS 9.5","time_weighted":true,"include_raw_prices":true}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompsResponse"},"examples":{"with_raw_prices":{"summary":"Comp with raw sale prices","value":{"comp_price":336.0,"high":348.0,"low":325.0,"count_requested":5,"count_used":5,"time_weighted":true,"raw_prices":[{"price":325.0,"sale_date":"2025-10-26T13:00:00.000Z","price_source":"marketplace","card_id":"1587446850514x224832321163624450","price_history_id":"1761480061129x501444455762531900","grade":"PSA 9","sale_type":"Best Offer","title":"[listing title]","sale_url":"[sale url]","image":"[image url]"},{"price":348.0,"sale_date":"2025-10-26T03:36:00.000Z","price_source":"marketplace","card_id":"1587446850514x224832321163624450","price_history_id":"1761446206940x522975047258362750","grade":"PSA 9","sale_type":"Auction","title":"[listing title]","sale_url":"[sale url]","image":"[image url]"}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/all-prices-by-card":{"post":{"tags":["Pricing & Valuations"],"summary":"Get All Latest Prices By Card","description":"Get all latest prices for a card across all available grades.\n\nRequires a card_id. If you only have a card name/description, call `match_card` or\n`search_cards` first to get the card_id, then use it here.\n\nThis endpoint returns the most recent price for each grade/grader combination\navailable for the specified card. Includes prices from all major grading companies\n(PSA, BGS, SGC, CGC, CSG, HGA) plus raw (ungraded) prices.\n\nThe response includes:\n- Grade and grader information\n- Latest price for each grade\n- Display order for sorting grades consistently\n\n**Example curl:**\n```bash\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"card_id\": \"1586414093385x612765462196125700\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/all-prices-by-card\"\n```\n\nReturns all available grades with their latest prices for the card.","operationId":"get_all_prices","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllPricesByCardRequest"},"examples":{"default":{"summary":"Get all prices for a card","description":"Fetch latest prices across all grades","value":{"card_id":"1586414093385x612765462196125700"}},"example2":{"summary":"Different card","description":"Fetch prices for Ken Griffey Jr card","value":{"card_id":"1587446850514x224832321163624450"}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllPricesByCardResponse"},"examples":{"default":{"summary":"All latest prices by card response","value":{"prices":[{"card_id":"1586414093385x612765462196125700","grade":"Raw","grader":"Raw","price":"1299.99","display_order":"-1"},{"card_id":"1586414093385x612765462196125700","grade":"PSA 10","grader":"PSA","price":"16999.99","display_order":"1"},{"card_id":"1586414093385x612765462196125700","grade":"PSA 9","grader":"PSA","price":"3700.00","display_order":"2"},{"card_id":"1586414093385x612765462196125700","grade":"BGS 9.5","grader":"BGS","price":"5200.00","display_order":"323"}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/90day-prices-by-grade":{"post":{"tags":["Market Data"],"summary":"Get 90-Day Prices By Grade","description":"Get 90-day average prices for cards at a specific grade.\n\nThis endpoint returns paginated cards with their average price over the last 90 days\nfor a specified grade. Optionally filter by search query or category.\n\n**Parameters:**\n- `page`: Page number for pagination (default: 1)\n- `page_size`: Number of results per page (1-500, default: 100)\n- `grade`: Required. Card grade (e.g., 'PSA 10', 'SGC 10', 'BGS 9.5')\n- `search`: Optional search query for card name\n- `category`: Optional category filter (e.g., 'Pokemon', 'Baseball')\n\n**Example curl:**\n```bash\n# Get PSA 10 cards\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"page\": 1,\n       \"page_size\": 100,\n       \"grade\": \"PSA 10\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/90day-prices-by-grade\"\n\n# Search with filters\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"page\": 1,\n       \"page_size\": 50,\n       \"grade\": \"SGC 10\",\n       \"search\": \"Pikachu\",\n       \"category\": \"Pokemon\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/90day-prices-by-grade\"\n```\n\nReturns paginated cards with 90-day average price and sales count.","operationId":"get_prices_by_grade_v1_cards_90day_prices_by_grade_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceByGradeRequest"},"examples":{"psa_10":{"summary":"PSA 10 cards","description":"Get 90-day prices for PSA 10 graded cards","value":{"page":1,"page_size":100,"grade":"PSA 10"}},"sgc_10_pokemon":{"summary":"SGC 10 Pokemon cards","description":"Get 90-day prices for SGC 10 Pokemon cards","value":{"page":1,"page_size":50,"grade":"SGC 10","category":"Pokemon"}},"bgs_search":{"summary":"BGS 9.5 with search","description":"Search for Tom Brady BGS 9.5 cards","value":{"page":1,"page_size":100,"grade":"BGS 9.5","search":"Tom Brady 2000"}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceByGradeResponse"},"examples":{"default":{"summary":"Prices by grade response","value":{"page":1,"pages":17,"cards":[{"description":"Friends in Hisui 2023 Pokemon Crown Zenith Full Art","player":"Friends in Hisui","set":"2023 Pokemon Crown Zenith","number":"148","variant":"Full Art","card_id":"1684286084852x189232814543430100","image":"//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1724143874181x158765543979815900/crop_image","category":"Pokemon","category_group":"Trading Cards","set_type":"Pokemon Crown Zenith","90_day_sales":3,"grade":"SGC 10","price":"12.83"}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/card-request":{"post":{"tags":["Card Details"],"summary":"Create Card Request (requires commercial agreement)","description":"Submit a card request to CardHedge for processing.\n\n**Requires a commercial agreement with Card Hedge.** Contact Card Hedge to\nobtain your Client ID before using this endpoint.\n\nThis endpoint allows clients to submit new card requests with player,\nset, card number, and image information. The `token` field must contain\nyour Client ID provided by Card Hedge.\n\n**Example curl:**\n```bash\ncurl -X POST \"https://api.cardhedger.com/v1/cards/card-request\" \\\n     -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"player\": \"River\",\n       \"set\": \"2020 Panini Illusions\",\n       \"card_number\": \"44\",\n       \"subset\": \"\",\n       \"image_url\": \"https://i.ebayimg.com/images/g/LssAAOSwjl9h2Q16/s-l1600.jpg\",\n       \"external_id\": \"RiverTest1\",\n       \"token\": \"your-client-id\",\n       \"variant\": \"Blue\"\n     }'\n```\n\nReturns the request status and ID on success.","operationId":"create_card_request_v1_cards_card_request_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardRequestRequest"},"examples":{"basic_request":{"summary":"Basic card request","description":"Submit a card request with required fields","value":{"player":"River","set":"2020 Panini Illusions","card_number":"44","subset":"","image_url":"https://i.ebayimg.com/images/g/LssAAOSwjl9h2Q16/s-l1600.jpg","external_id":"RiverTest1","token":"your-client-id","variant":"Blue"}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardRequestResponse"},"examples":{"success":{"summary":"Request created successfully","value":{"status":"Success","message":"The request was created successfully.","id":"1766157241863x266716738264924480"}},"not_run":{"summary":"Request not processed","value":{"status":"NOT_RUN","message":"The condition for the workflow create-pub-card-request is not met. Workflow won't run"}}}}}},"422":{"description":"Validation Error - likely missing the `token` (Client ID) field. This endpoint requires a commercial agreement with Card Hedge. Contact Card Hedge to obtain your Client ID."}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/price-updates":{"post":{"tags":["Market Data"],"summary":"Get Price Updates (Delta Poll)","description":"Get price updates since a specified timestamp (delta polling).\n\nThis endpoint enables efficient **delta polling** - clients only request data that has\nchanged since their last request, rather than fetching the entire dataset each time.\n\n## How Delta Polling Works\n\n1. **Initial Request**: Make your first request with a timestamp from when you want to start tracking\n2. **Store the Latest Timestamp**: Save the `update_timestamp` from the most recent item in the response\n3. **Subsequent Requests**: Use that saved timestamp as the `since` parameter for your next request\n4. **Repeat**: Continue polling at your desired interval (e.g., every 5 seconds)\n\n## Polling Flow Example\n\n```\nPoll 1: since=\"2024-01-01T00:00:00.000Z\"\nResponse: 50 updates, latest: \"2024-01-01T01:30:00.000Z\"\n→ Save timestamp\n                ↓ (wait 5 sec)\nPoll 2: since=\"2024-01-01T01:30:00.000Z\"\nResponse: 3 updates, latest: \"2024-01-01T01:30:05.000Z\"\n→ Save timestamp\n                ↓ (wait 5 sec)\nPoll 3: since=\"2024-01-01T01:30:05.000Z\"\nResponse: 0 updates (no new data)\n→ Keep existing timestamp\n```\n\n## Parameters\n- `since`: ISO 8601 timestamp to fetch updates after (e.g., '2023-07-16T01:28:57.000Z')\n- `ignore_grades`: Optional list of grades to exclude (e.g., ['Raw'] to exclude ungraded cards)\n\n## Best Practices\n\n| Practice | Recommendation |\n|----------|----------------|\n| Poll Interval | 5-10 seconds for real-time updates |\n| Checkpoint Storage | Persist `last_timestamp` to disk/database to resume after restarts |\n| Empty Responses | Normal - means no new updates; keep your existing timestamp |\n| Error Handling | On failure, retry with the same timestamp (don't advance it) |\n| Grade Filtering | Use `ignore_grades` to reduce payload if you don't need all grades |\n\n## Example curl\n\n```bash\n# Get all updates since timestamp\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"since\": \"2023-07-16T01:28:57.000Z\"}' \\\n     \"https://api.cardhedger.com/v1/cards/price-updates\"\n\n# Exclude Raw grades\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"since\": \"2023-07-16T01:28:57.000Z\", \"ignore_grades\": [\"Raw\"]}' \\\n     \"https://api.cardhedger.com/v1/cards/price-updates\"\n```\n\n## Python Example\n\n```python\nimport requests\nimport time\nfrom datetime import datetime, timezone\n\nAPI_KEY = \"your-api-key\"\nBASE_URL = \"https://api.cardhedger.com/v1/cards/price-updates\"\n\n# Start from current time\nlast_timestamp = datetime.now(timezone.utc).strftime(\"%Y-%m-%dT%H:%M:%S.000Z\")\n\nwhile True:\n    response = requests.post(\n        BASE_URL,\n        headers={\"X-API-Key\": API_KEY, \"Content-Type\": \"application/json\"},\n        json={\"since\": last_timestamp, \"ignore_grades\": [\"Raw\"]}\n    )\n    data = response.json()\n\n    if data[\"count\"] > 0:\n        for update in data[\"updates\"]:\n            print(f\"{update['card_desc']} - {update['grade']}: ${update['price']}\")\n        # Update checkpoint to latest timestamp\n        last_timestamp = data[\"updates\"][-1][\"update_timestamp\"]\n\n    time.sleep(5)  # Poll every 5 seconds\n```\n\nReturns list of price updates with card details and timestamps.","operationId":"get_price_updates_v1_cards_price_updates_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceUpdatesRequest"},"examples":{"basic":{"summary":"Get all updates since timestamp","description":"Fetch all price updates since the specified time","value":{"since":"2023-07-16T01:28:57.000Z"}},"ignore_raw":{"summary":"Exclude Raw grades","description":"Fetch updates but exclude Raw (ungraded) cards","value":{"since":"2023-07-16T01:28:57.000Z","ignore_grades":["Raw"]}},"ignore_multiple":{"summary":"Exclude multiple grades","description":"Fetch updates excluding Raw and SGC grades","value":{"since":"2023-07-16T01:28:57.000Z","ignore_grades":["Raw","SGC 10","SGC 9.5"]}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceUpdatesResponse"},"examples":{"default":{"summary":"Price updates response","value":{"updates":[{"price":"53.88","sale_date":"2023-07-15","grade":"PSA 9","card_desc":"James Wood 2022 Bowman Chrome Prospects Sapphire Baseball","card_set":"2022 Bowman Chrome Prospects Sapphire Baseball","card_number":"BCP-108","player":"James Wood","variant":"Base","card_id":"1669693578344x525012276222885900","update_timestamp":"2023-07-16T01:29:01.227Z"},{"price":"116.5","sale_date":"2023-07-15","grade":"PSA 10","card_desc":"James Wood 2022 Bowman Chrome Prospects Sapphire Baseball","card_set":"2022 Bowman Chrome Prospects Sapphire Baseball","card_number":"BCP-108","player":"James Wood","variant":"Base","card_id":"1669693578344x525012276222885900","update_timestamp":"2023-07-16T01:29:02.774Z"}],"count":2}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/price-estimate":{"post":{"tags":["Pricing & Valuations"],"summary":"Get Price Estimate for a Card","description":"Get a price estimate for a card at a specific grade.\n\nRequires a card_id. If you only have a card name/description, call `match_card` or\n`search_cards` first to get the card_id, then use it here.\n\nThis endpoint uses CardHedge's correlated price estimation service to provide\nprice estimates with confidence intervals. The estimation can use either\ndirect sales data or correlated pricing from similar cards.\n\n**Response Fields:**\n- `price`: Estimated price in USD\n- `price_low`: Lower bound of price estimate\n- `price_high`: Upper bound of price estimate\n- `confidence`: Confidence score (0-1)\n- `method`: Estimation method used ('direct' or 'correlated')\n- `freshness_days`: Age of data used for estimation in days\n- `support_grades`: Number of supporting grade data points\n- `grade_label`: Grade label used for estimation\n- `provider`: Grading provider (e.g., 'PSA', 'BGS')\n- `grade_value`: Numeric grade value\n\n**Example curl:**\n```bash\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"card_id\": \"1586812246197x228181943611293700\",\n       \"grade\": \"PSA 9\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/price-estimate\"\n```\n\nReturns price estimate with confidence bounds and metadata.","operationId":"estimate_price","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceEstimateRequest"},"examples":{"mike_trout_psa9":{"summary":"Mike Trout PSA 9","description":"Get price estimate for Mike Trout 2011 Topps Update rookie card in PSA 9","value":{"card_id":"1586812246197x228181943611293700","grade":"PSA 9"}},"mike_trout_psa10":{"summary":"Mike Trout PSA 10","description":"Get price estimate for Mike Trout 2011 Topps Update rookie card in PSA 10","value":{"card_id":"1586812246197x228181943611293700","grade":"PSA 10"}},"griffey_bgs95":{"summary":"Ken Griffey Jr. BGS 9.5","description":"Get price estimate for Ken Griffey Jr. 1989 Upper Deck in BGS 9.5","value":{"card_id":"1587446850514x224832321163624450","grade":"BGS 9.5"}},"raw_card":{"summary":"Raw (ungraded) card","description":"Get price estimate for an ungraded card","value":{"card_id":"1586812246197x228181943611293700","grade":"Raw"}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceEstimateResponse"},"examples":{"direct_method":{"summary":"Direct estimation (recent sales data)","description":"Price estimate using direct sales data from recent transactions","value":{"price":349.99,"price_low":329.2,"price_high":370.78,"confidence":0.3869,"method":"direct","freshness_days":0,"support_grades":1,"grade_label":"PSA 9","provider":"PSA","grade_value":9.0}},"correlated_method":{"summary":"Correlated estimation (inferred from similar grades)","description":"Price estimate using correlated pricing from other grades when direct data is limited","value":{"price":1250.0,"price_low":1100.0,"price_high":1400.0,"confidence":0.25,"method":"correlated","freshness_days":5,"support_grades":3,"grade_label":"PSA 10","provider":"PSA","grade_value":10.0}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/batch-price-estimate":{"post":{"tags":["Pricing & Valuations"],"summary":"Get Batch Price Estimates for Multiple Cards","description":"Get price estimates for multiple cards in a single request.\n\nThis endpoint allows batch processing of up to 100 card/grade combinations\nusing CardHedge's correlated price estimation service.\n\n**Request Format:**\n```json\n{\n  \"items\": [\n    {\"card_id\": \"abc123\", \"grade\": \"PSA 10\"},\n    {\"card_id\": \"abc123\", \"grade\": \"PSA 9\"},\n    {\"card_id\": \"xyz789\", \"grade\": \"BGS 9.5\"}\n  ]\n}\n```\n\n**Response Fields (per item):**\n- `card_id`: Card identifier from request\n- `grade`: Grade from request\n- `price`: Estimated price in USD (null if error)\n- `price_low`: Lower bound of price estimate\n- `price_high`: Upper bound of price estimate\n- `confidence`: Confidence score (0-1)\n- `method`: Estimation method ('direct' or 'correlated')\n- `freshness_days`: Age of data used for estimation\n- `support_grades`: Number of supporting grade data points\n- `grade_label`: Grade label used for estimation\n- `provider`: Grading provider (e.g., 'PSA', 'BGS')\n- `grade_value`: Numeric grade value\n- `error`: Error message if estimation failed for this item\n\n**Example curl:**\n```bash\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"items\": [\n         {\"card_id\": \"1586812246197x228181943611293700\", \"grade\": \"PSA 10\"},\n         {\"card_id\": \"1586812246197x228181943611293700\", \"grade\": \"PSA 9\"}\n       ]\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/batch-price-estimate\"\n```\n\nReturns batch results with individual success/error status per item.\nMaximum 100 items per request.","operationId":"get_batch_price_estimate_v1_cards_batch_price_estimate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPriceEstimateRequest"},"examples":{"grade_comparison":{"summary":"Compare grades for same card","description":"Get PSA 10 and PSA 9 estimates for Mike Trout 2011 Topps Update to compare values","value":{"items":[{"card_id":"1586812246197x228181943611293700","grade":"PSA 10"},{"card_id":"1586812246197x228181943611293700","grade":"PSA 9"}]}},"portfolio_valuation":{"summary":"Portfolio valuation","description":"Value multiple cards in a collection at once","value":{"items":[{"card_id":"1586812246197x228181943611293700","grade":"PSA 10"},{"card_id":"1587446850514x224832321163624450","grade":"PSA 9"},{"card_id":"1587446850514x224832321163624450","grade":"BGS 9.5"},{"card_id":"1586812246197x228181943611293700","grade":"Raw"}]}},"grader_comparison":{"summary":"Compare grading companies","description":"Compare PSA vs BGS values for the same card","value":{"items":[{"card_id":"1587446850514x224832321163624450","grade":"PSA 10"},{"card_id":"1587446850514x224832321163624450","grade":"BGS 10"},{"card_id":"1587446850514x224832321163624450","grade":"BGS 9.5"},{"card_id":"1587446850514x224832321163624450","grade":"SGC 10"}]}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchPriceEstimateResponse"},"examples":{"successful_batch":{"summary":"Successful batch estimation","description":"All items estimated successfully with direct pricing data","value":{"results":[{"card_id":"1586812246197x228181943611293700","grade":"PSA 10","price":795.0,"price_low":747.79,"price_high":842.21,"confidence":0.3869,"method":"direct","freshness_days":0,"support_grades":1,"grade_label":"PSA 10","provider":"PSA","grade_value":10.0},{"card_id":"1586812246197x228181943611293700","grade":"PSA 9","price":349.99,"price_low":329.2,"price_high":370.78,"confidence":0.3869,"method":"direct","freshness_days":0,"support_grades":1,"grade_label":"PSA 9","provider":"PSA","grade_value":9.0}],"total_requested":2,"total_successful":2}},"partial_success":{"summary":"Partial success with error","description":"Some items failed estimation due to insufficient data","value":{"results":[{"card_id":"1586812246197x228181943611293700","grade":"PSA 10","price":795.0,"price_low":747.79,"price_high":842.21,"confidence":0.3869,"method":"direct","freshness_days":0,"support_grades":1,"grade_label":"PSA 10","provider":"PSA","grade_value":10.0},{"card_id":"invalid_card_id","grade":"PSA 9","error":"Card not found"}],"total_requested":2,"total_successful":1}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/subscribe-price-updates":{"post":{"tags":["Market Data"],"summary":"Subscribe to Price Updates","description":"Subscribe to price updates for one or more cards. Each subscription triggers price tracking for the given card and grade combination.\n\n- **external_id** defaults to the `card_id` when omitted.\n- Subscriptions are processed in parallel for speed.\n- Individual failures do not affect other subscriptions — the response always returns HTTP 200 with per-item success/failure status.","operationId":"subscribe_price_updates_v1_cards_subscribe_price_updates_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribePriceUpdatesRequest"},"examples":{"watchlist_batch":{"summary":"Watchlist batch","description":"Subscribe to price updates for multiple cards at once","value":{"client_id":"your_client_id","subscriptions":[{"card_id":"1586812246197x228181943611293700","grade":"PSA 10","external_id":"test_123"},{"card_id":"1699670576265x928796749151534600","grade":"PSA 9"}]}},"single_card":{"summary":"Single card","description":"Subscribe to price updates for a single card","value":{"client_id":"your_client_id","subscriptions":[{"card_id":"1586812246197x228181943611293700","grade":"PSA 10"}]}}}}},"required":true},"responses":{"200":{"description":"Subscription results (always returned, even on partial failure)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribePriceUpdatesResponse"},"examples":{"all_successful":{"summary":"All subscriptions succeeded","value":{"results":[{"card_id":"1586812246197x228181943611293700","grade":"PSA 10","external_id":"test_123","success":true},{"card_id":"1699670576265x928796749151534600","grade":"PSA 9","external_id":"1699670576265x928796749151534600","success":true}],"total_requested":2,"total_successful":2}},"partial_failure":{"summary":"One subscription failed","value":{"results":[{"card_id":"1586812246197x228181943611293700","grade":"PSA 10","external_id":"my_ref_123","success":true},{"card_id":"invalid_card_id","grade":"PSA 9","external_id":"invalid_card_id","success":false,"error":"CardHedge API returned 404"}],"total_requested":2,"total_successful":1}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/90day-prices-by-grade-search":{"post":{"tags":["Market Data"],"summary":"Search Cards with 90-Day Prices By Grade","description":"Search cards via Typesense (relevancy-ranked), then fetch 90-day prices for matched cards.\n\nUses Typesense for full-text search with relevancy ranking, then merges 90-day\nprice data from the CardHedge API. Results are returned in Typesense relevancy order.\nCards without price data for the specified grade are included with null price fields.\n\n**Parameters:**\n- `search`: Required. Search query (e.g., 'Mike Trout 2011 Topps Update')\n- `grade`: Required. Card grade (e.g., 'PSA 10', 'SGC 10', 'BGS 9.5')\n- `page`: Page number for pagination (default: 1)\n- `page_size`: Number of results per page (1-100, default: 50)\n\n**Example curl:**\n```bash\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"search\": \"Mike Trout 2011 Topps Update\",\n       \"grade\": \"PSA 10\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/90day-prices-by-grade-search\"\n```\n\nReturns cards in Typesense relevancy order with 90-day average price and sales count.","operationId":"search_with_90day_prices_v1_cards_90day_prices_by_grade_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchWith90DayPricesRequest"},"examples":{"basic_search":{"summary":"Basic search","description":"Search for Mike Trout PSA 10 cards with 90-day prices","value":{"search":"Mike Trout 2011 Topps Update","grade":"PSA 10"}},"paginated_search":{"summary":"Paginated search","description":"Search with custom page size","value":{"search":"Charizard","grade":"PSA 10","page":1,"page_size":25}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchWith90DayPricesResponse"},"examples":{"default":{"summary":"Search with prices response","value":{"page":1,"pages":5,"found":234,"search_time_ms":12,"cards":[{"card_id":"1586812246197x228181943611293700","description":"Mike Trout 2011 Topps Update Base","search_text":"Mike Trout 2011 Topps Update Base US175","text_match_score":578730089005449217,"player":"Mike Trout","set":"2011 Topps Update","number":"US175","variant":"Base","image":"https://example.com/image.jpg","category":"Baseball","category_group":"Trading Cards","set_type":"Topps Update","90_day_sales":45,"grade":"PSA 10","price":"1250.00"}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/additions-summary":{"post":{"tags":["Market Data"],"summary":"Get Additions Summary","description":"Get a summary of cards added to the system over time.\n\nReturns daily counts grouped by category, set, and subset.\nData is refreshed daily.\n\n**Example curl:**\n```bash\n# Cards added since March 1st\ncurl -X POST \"https://api.cardhedger.com/v1/cards/additions-summary\" \\\n     -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"start_date\": \"2026-03-01\"}'\n\n# Baseball cards added in a date range\ncurl -X POST \"https://api.cardhedger.com/v1/cards/additions-summary\" \\\n     -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"start_date\": \"2026-03-01\", \"end_date\": \"2026-03-15\", \"category\": \"Baseball\"}'\n```","operationId":"get_additions_summary_v1_cards_additions_summary_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdditionsSummaryRequest"},"examples":{"since_date":{"summary":"Cards added since a date","description":"Get all cards added since March 1st","value":{"start_date":"2026-03-01"}},"date_range_with_category":{"summary":"Date range with category filter","description":"Baseball cards added in a specific date range","value":{"start_date":"2026-03-01","end_date":"2026-03-15","category":"Baseball"}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdditionsSummaryResponse"},"examples":{"default":{"summary":"Additions summary response","value":{"data":[{"category":"Baseball","set_name":"2024 Topps Chrome Baseball","subset":"Base Set","variants":"Base, Gold, Refractor","added_date":"2026-03-15","card_count":42}],"page":1,"page_size":50}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/total-sales-by-player":{"post":{"tags":["Market Data"],"summary":"Get Total Sales Count by Player","description":"Get total sales count per player/character from the Typesense price_history index.\n\nSearches the `description` field of the `price_history` collection for each\nplayer name, filtered to the last N days. Returns the count of matching\nsales records without transferring document data.\n\n**Parameters:**\n- `players`: List of player/character names (max 25)\n- `days`: Look-back window in days (default: 30, max: 365)","operationId":"get_total_sales_by_player","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TotalSalesByPlayerRequest"},"examples":{"single_player":{"summary":"Single player","description":"Get total sales for Mike Trout in the last 30 days","value":{"players":["Mike Trout"],"days":30}},"multiple_players":{"summary":"Multiple players","description":"Compare sales volume across players","value":{"players":["Mike Trout","Shohei Ohtani","Aaron Judge","Charizard"],"days":30}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TotalSalesByPlayerResponse"},"example":{"results":[{"player":"Mike Trout","total_sales":12809,"search_time_ms":391},{"player":"Shohei Ohtani","total_sales":87192,"search_time_ms":618}],"days":30}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/sales-stats-by-player":{"post":{"tags":["Market Data"],"summary":"Get Bucketed Sales Stats by Player (count, total, average)","description":"Return sales statistics per player — **count**, **total amount (USD)**, and\n**mean sale price** — bucketed by day, week, or calendar month. Useful for\ntrend charts, period-over-period comparisons, and tracking how a player's\nmarket is moving over time.\n\n### How buckets are aligned\n\nAll buckets are calendar-aligned in UTC:\n\n- **`day`** — midnight-to-midnight UTC.\n- **`week`** — ISO week, Monday → Sunday.\n- **`month`** — first → last calendar day of the month.\n\n### Current (in-progress) period\n\nBy default (`include_current: true`) the newest bucket is the in-progress\nperiod (month-to-date, week-to-date, or today so far) and is flagged with\n`partial: true` so clients can render it differently — e.g. a dashed line\non a chart. Set `include_current: false` to return only fully-closed\nperiods, which is the right choice for clean trend lines.\n\nThe `periods` value is the **total** number of buckets returned, regardless\nof whether the newest is partial. Requesting `periods=12, interval=week`\nwith the default flag returns 11 closed weeks + 1 partial (week-to-date).\n\n### Caps and rate considerations\n\n`periods` is capped per interval to keep request fan-out reasonable:\n\n| Interval | Max periods |\n|----------|-------------|\n| `day`    | 90          |\n| `week`   | 52          |\n| `month`  | 24          |\n\nEach (player × bucket) is one upstream search; closed buckets are cached\nserver-side for 24 hours, so repeat calls for the same player/interval are\nnear-instant. The partial bucket is never cached and is recomputed on every\nrequest.\n\n### Field meanings\n\n- `count` — number of sales matching the player name in the bucket window.\n- `total_amount` — sum of sale prices in USD.\n- `average_sale` — arithmetic mean (sum ÷ count). Note that the underlying\n  data includes some very low-value sales (e.g. bulk lots), which can pull\n  the mean down for high-volume players.\n- `partial` — `true` only for the in-progress current bucket.\n\nBuckets are returned **oldest → newest**.","operationId":"get_sales_stats_by_player","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesStatsByPlayerRequest"},"examples":{"weekly_default":{"summary":"Weekly trend, 12 weeks (default)","description":"Returns the last 11 fully-closed weeks plus the current week-to-date as the newest bucket (`partial: true`).","value":{"players":["Mike Trout"],"interval":"week","periods":12}},"monthly_compare":{"summary":"Monthly comparison across players","description":"Six months of sales volume for multiple players. The newest bucket is month-to-date.","value":{"players":["Mike Trout","Shohei Ohtani","Aaron Judge"],"interval":"month","periods":6}},"closed_only":{"summary":"Closed periods only (no partial bucket)","description":"Set `include_current: false` to exclude the in-progress period — useful for trend charts where a half-finished bucket would distort the line.","value":{"players":["Shohei Ohtani"],"interval":"month","periods":12,"include_current":false}},"daily_short":{"summary":"Daily breakdown over the last 14 days","value":{"players":["Charizard"],"interval":"day","periods":14}}}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesStatsByPlayerResponse"},"example":{"interval":"week","periods":4,"results":[{"player":"Mike Trout","buckets":[{"start":"2026-03-23","end":"2026-03-29","count":2841,"total_amount":218394.55,"average_sale":76.87,"partial":false},{"start":"2026-03-30","end":"2026-04-05","count":3102,"total_amount":245118.2,"average_sale":79.02,"partial":false},{"start":"2026-04-06","end":"2026-04-12","count":3070,"total_amount":250383.46,"average_sale":81.56,"partial":false},{"start":"2026-04-13","end":"2026-04-15","count":1124,"total_amount":92011.3,"average_sale":81.86,"partial":true}]}]}}}},"422":{"description":"Invalid request — most commonly `periods` exceeds the cap for the requested `interval` (day≤90, week≤52, month≤24)."},"502":{"description":"Upstream Typesense error."},"503":{"description":"Typesense is not configured on the server."}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/image-search":{"post":{"tags":["Image Search"],"summary":"Search cards by image","description":"Upload an image or provide an image URL to find visually similar cards","operationId":"image_search_v1_cards_image_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageSearchRequest"},"examples":{"url":{"summary":"Search by URL","description":"Provide a public URL to a card image","value":{"image_url":"https://example.com/card.jpg","k":10}},"base64":{"summary":"Search by base64","description":"Provide a base64-encoded image","value":{"image_base64":"data:image/jpeg;base64,/9j/4AAQSkZJRg...","k":5}}}}},"required":true},"responses":{"200":{"description":"Successful search with results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageSearchResponse"},"example":{"success":true,"results":[{"similarity":"95.23","distance":0.0477,"ximilar_id":"xim_abc123","product_id":"1587446850514x224832321163624450","card_data":{"card_id":"1587446850514x224832321163624450","description":"Ken Griffey Jr. 1989 Upper Deck Baseball","player":"Ken Griffey Jr.","set":"1989 Upper Deck Baseball","number":"1"}}],"total_results":5,"query_id":"query_abc123","has_cardhedge_matches":true}}}},"400":{"description":"Bad request - missing image input"},"413":{"description":"Image too large (max 10MB)"},"502":{"description":"External API error"},"503":{"description":"Image search service not configured"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/issues":{"post":{"tags":["Card Issues"],"summary":"Submit a card data issue","description":"Report a data issue for a specific card. Use this endpoint to flag problems such as incorrect prices,\nwrong variants, missing data, or date errors. Issues are tracked and resolved by our data team.\n\n**Requires Enterprise tier.** Returns 403 for Free and Pro tier API keys.\n\n**Status lifecycle:** `new` &rarr; `in_progress` &rarr; `resolved`\n\n**Example curl:**\n```bash\ncurl -X POST -H \"X-API-Key: your-api-key-here\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"card_id\": \"1587446850514x224832321163624450\",\n       \"card_title\": \"2018 Topps Chrome Shohei Ohtani #150 Refractor\",\n       \"issue_description\": \"PSA 10 price showing $250 but recent comps are consistently $2,500+\"\n     }' \\\n     \"https://api.cardhedger.com/v1/cards/issues\"\n```","operationId":"create_card_issue_v1_cards_issues_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardIssueCreate"},"examples":{"wrong_price":{"summary":"Wrong price","description":"Report an incorrect price for a card","value":{"card_id":"1587446850514x224832321163624450","card_title":"2018 Topps Chrome Shohei Ohtani #150 Refractor","issue_description":"PSA 10 price showing $250 but recent comps are consistently $2,500+"}},"wrong_variant":{"summary":"Incorrect variant","description":"Report a card with the wrong variant listed","value":{"card_id":"1587446850514x998877665544332211","issue_description":"Card is listed as Base but should be Refractor variant based on the image and cert lookup"}},"missing_data":{"summary":"Missing data","description":"Report missing information on a card","value":{"card_id":"1587446850514x112233445566778899","card_title":"2023 Panini Prizm Victor Wembanyama #1","issue_description":"Card is missing the rookie designation flag — this is a verified rookie card"}}}}}},"responses":{"201":{"description":"Issue created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardIssueResponse"},"example":{"id":42,"status":"new","created_at":"2026-03-22T12:00:00Z"}}}},"403":{"description":"Enterprise tier required","content":{"application/json":{"example":{"detail":"Card issue reporting is only available to Enterprise tier subscribers"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]},"get":{"tags":["Card Issues"],"summary":"List your card issues","description":"List all card data issues submitted by your API key, ordered by most recent first.\n\nOptionally filter by status to see only issues in a specific state.\n\n**Requires Enterprise tier.** Returns 403 for Free and Pro tier API keys.\n\n**Available statuses:** `new`, `in_progress`, `resolved`\n\n**Example curl:**\n```bash\n# List all issues\ncurl -H \"X-API-Key: your-api-key-here\" \\\n     \"https://api.cardhedger.com/v1/cards/issues\"\n\n# Filter by status\ncurl -H \"X-API-Key: your-api-key-here\" \\\n     \"https://api.cardhedger.com/v1/cards/issues?status=new\"\n```","operationId":"list_card_issues_v1_cards_issues_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by status (e.g. new, in_progress, resolved)","title":"Status"},"description":"Filter by status (e.g. new, in_progress, resolved)"}],"responses":{"200":{"description":"List of issues with total count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardIssueListResponse"},"example":{"issues":[{"id":42,"card_id":"1587446850514x224832321163624450","card_title":"2018 Topps Chrome Shohei Ohtani #150 Refractor","issue_description":"PSA 10 price showing $250 but recent comps are consistently $2,500+","customer_id":7,"status":"new","created_at":"2026-03-22T12:00:00Z","updated_at":"2026-03-22T12:00:00Z"}],"total_count":1}}}},"403":{"description":"Enterprise tier required","content":{"application/json":{"example":{"detail":"Card issue reporting is only available to Enterprise tier subscribers"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/cards/issues/{issue_id}":{"get":{"tags":["Card Issues"],"summary":"Get issue by ID","description":"Retrieve the full details of a card issue by its ID. Only returns issues that belong to your API key.\n\n**Requires Enterprise tier.** Returns 403 for Free and Pro tier API keys.\n\n**Example curl:**\n```bash\ncurl -H \"X-API-Key: your-api-key-here\" \\\n     \"https://api.cardhedger.com/v1/cards/issues/42\"\n```","operationId":"get_card_issue_v1_cards_issues__issue_id__get","parameters":[{"name":"issue_id","in":"path","required":true,"schema":{"type":"integer","title":"Issue Id"}}],"responses":{"200":{"description":"Issue details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardIssueDetail"},"example":{"id":42,"card_id":"1587446850514x224832321163624450","card_title":"2018 Topps Chrome Shohei Ohtani #150 Refractor","issue_description":"PSA 10 price showing $250 but recent comps are consistently $2,500+","customer_id":7,"status":"resolved","resolution_description":"Price corrected to $2,450 based on latest 30-day sales data","date_fixed":"2026-03-25T15:30:00Z","created_at":"2026-03-22T12:00:00Z","updated_at":"2026-03-25T15:30:00Z"}}}},"403":{"description":"Enterprise tier required","content":{"application/json":{"example":{"detail":"Card issue reporting is only available to Enterprise tier subscribers"}}}},"404":{"description":"Issue not found or does not belong to your API key","content":{"application/json":{"example":{"detail":"Issue not found"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/download/daily-price-export/{file_date}":{"get":{"tags":["Downloads & Exports"],"summary":"Download Daily Price Export (Enterprise only)","description":"Downloads a CSV file from the 'daily-price-export' Supabase storage bucket for a specified date. **This endpoint is restricted to customers on the Enterprise subscription tier.** Requests authenticated with a Free or Pro API key will receive a 403 Forbidden response.","operationId":"download_daily_price_export_v1_download_daily_price_export__file_date__get","parameters":[{"name":"file_date","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the export file to download, in YYYY-MM-DD format.","title":"File Date"},"description":"The date of the export file to download, in YYYY-MM-DD format."}],"responses":{"200":{"description":"The file is successfully downloaded.","content":{"application/json":{"schema":{}},"text/csv":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid date format provided."},"401":{"description":"Authentication failed or API key is invalid."},"403":{"description":"API key does not belong to an Enterprise-tier customer."},"404":{"description":"The requested file was not found in the storage bucket."},"500":{"description":"An unexpected error occurred on the server."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}}},"components":{"schemas":{"AIFallbackInfo":{"properties":{"card_name":{"type":"string","title":"Card Name","description":"Identified card name from AI"},"card_type":{"type":"string","title":"Card Type","description":"Card type: 'sports' or 'tcg'"},"confidence":{"type":"number","title":"Confidence","description":"Identification confidence score (0-100)"},"source":{"type":"string","title":"Source","description":"Data source identifier","default":"ximilar"}},"type":"object","required":["card_name","card_type","confidence"],"title":"AIFallbackInfo","description":"Card identification data from AI fallback (when no CardHedge match)."},"AdditionsSummaryRequest":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date","description":"Start date (inclusive) for the summary, e.g. 2026-01-01"},"end_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"End Date","description":"End date (inclusive). Defaults to today if omitted."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Optional category filter (e.g., 'Baseball', 'Pokemon')"},"set_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set Name","description":"Optional set name filter"},"page":{"type":"integer","minimum":1.0,"title":"Page","description":"Page number","default":1},"page_size":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Page Size","description":"Rows per page","default":50}},"type":"object","required":["start_date"],"title":"AdditionsSummaryRequest","description":"Request parameters for the card additions summary endpoint."},"AdditionsSummaryResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AdditionsSummaryRow"},"type":"array","title":"Data","description":"Summary rows"},"page":{"type":"integer","title":"Page","description":"Current page number"},"page_size":{"type":"integer","title":"Page Size","description":"Number of rows per page"}},"type":"object","required":["data","page","page_size"],"title":"AdditionsSummaryResponse","description":"Response model for the card additions summary endpoint.","examples":[{"data":[{"added_date":"2026-03-15","card_count":42,"category":"Baseball","set_name":"2024 Topps Chrome Baseball","subset":"Base Set","variants":"Base, Gold, Refractor"},{"added_date":"2026-03-14","card_count":18,"category":"Pokemon","set_name":"2024 Pokemon Prismatic Evolutions","subset":"Illustration Rare","variants":"Base"}],"page":1,"page_size":50}]},"AdditionsSummaryRow":{"properties":{"category":{"type":"string","title":"Category","description":"Card category (e.g., 'Baseball', 'Pokemon')"},"set_name":{"type":"string","title":"Set Name","description":"Card set name"},"subset":{"type":"string","title":"Subset","description":"Card subset (defaults to 'Base Set' if not specified)"},"variants":{"type":"string","title":"Variants","description":"Comma-separated list of distinct variants in this group"},"added_date":{"type":"string","format":"date","title":"Added Date","description":"Date cards were added"},"card_count":{"type":"integer","title":"Card Count","description":"Number of cards added in this group on this date"}},"type":"object","required":["category","set_name","subset","variants","added_date","card_count"],"title":"AdditionsSummaryRow","description":"A single row in the card additions summary."},"AllPricesByCardRequest":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier","examples":["1586414093385x612765462196125700"]}},"type":"object","required":["card_id"],"title":"AllPricesByCardRequest","description":"Request parameters for all latest prices by card endpoint.","examples":[{"card_id":"1586414093385x612765462196125700"}]},"AllPricesByCardResponse":{"properties":{"prices":{"items":{"$ref":"#/components/schemas/GradePrice"},"type":"array","title":"Prices","description":"Latest prices across all available grades"}},"type":"object","required":["prices"],"title":"AllPricesByCardResponse","description":"Response model for all latest prices by card endpoint.","examples":[{"prices":[{"card_id":"1586414093385x612765462196125700","display_order":"-1","grade":"Raw","grader":"Raw","price":"1299.99"},{"card_id":"1586414093385x612765462196125700","display_order":"1","grade":"PSA 10","grader":"PSA","price":"16999.99"},{"card_id":"1586414093385x612765462196125700","display_order":"2","grade":"PSA 9","grader":"PSA","price":"3700.00"},{"card_id":"1586414093385x612765462196125700","display_order":"323","grade":"BGS 9.5","grader":"BGS","price":"5200.00"}]}]},"BatchCertLookupRequest":{"properties":{"certs":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Certs","description":"List of certificate numbers to lookup (max 100)","examples":[["76676185","50000000","12345678"]]},"grader":{"type":"string","title":"Grader","description":"Grading company (defaults to PSA)","default":"PSA","examples":["PSA"]}},"type":"object","required":["certs"],"title":"BatchCertLookupRequest","description":"Request parameters for batch certificate lookup endpoint.","examples":[{"certs":["76676185","50000000","12345678"],"grader":"PSA"}]},"BatchCertLookupResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/SingleCertResult"},"type":"array","title":"Results","description":"List of certificate lookup results"},"total_requested":{"type":"integer","title":"Total Requested","description":"Total number of certificates requested"},"total_found":{"type":"integer","title":"Total Found","description":"Number of cards found in database with pricing data"}},"type":"object","required":["results","total_requested","total_found"],"title":"BatchCertLookupResponse","description":"Response model for batch certificate lookup endpoint.","examples":[{"results":[{"cert_info":{"cert":"76676185","description":"2000 Pokemon Japanese Neo Wooper 194","gemrate_id":"9f4cd2db01a0a873ba5da0feb23428686fd556ac","grade":"PSA 9","grader":"psa","universal_gemrate_id":"9f4cd2db01a0a873ba5da0feb23428686fd556ac"}},{"card":{"card_id":"1699670576265x928796749151534600","category":"Baseball","category_group":"Sports Cards","description":"C.C. Sabathia 1999 Bowman Chrome Baseball","image":"https://942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1699670857725x475053799924132860/resized_20231111_024737.jpeg","number":"344","player":"C.C. Sabathia","set":"1999 Bowman Chrome Baseball","set_type":"Bowman Chrome Baseball","variant":"Base"},"cert_info":{"cert":"50000000","description":"1999 Bowman Chrome C.C. Sabathia 344","gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885","grade":"PSA 10","grader":"psa","universal_gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885"}}],"total_found":1,"total_requested":2}]},"BatchPriceEstimateRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/PriceEstimateItem"},"type":"array","maxItems":100,"minItems":1,"title":"Items","description":"List of card/grade combinations to estimate (max 100)"}},"type":"object","required":["items"],"title":"BatchPriceEstimateRequest","description":"Request parameters for batch price estimation endpoint."},"BatchPriceEstimateResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/BatchPriceEstimateResultItem"},"type":"array","title":"Results","description":"List of estimation results"},"total_requested":{"type":"integer","title":"Total Requested","description":"Number of items requested"},"total_successful":{"type":"integer","title":"Total Successful","description":"Number of successful estimations"}},"type":"object","required":["results","total_requested","total_successful"],"title":"BatchPriceEstimateResponse","description":"Response model for batch price estimation endpoint.","examples":[{"results":[{"card_id":"1586812246197x228181943611293700","confidence":0.45,"freshness_days":1,"grade":"PSA 10","grade_label":"PSA 10","grade_value":10.0,"method":"direct","price":1250.0,"price_high":1325.0,"price_low":1175.0,"provider":"PSA","support_grades":2},{"card_id":"1586812246197x228181943611293700","confidence":0.3809,"freshness_days":2,"grade":"PSA 9","grade_label":"PSA 9","grade_value":9.0,"method":"direct","price":385.0,"price_high":407.92,"price_low":362.08,"provider":"PSA","support_grades":1}],"total_requested":2,"total_successful":2}]},"BatchPriceEstimateResultItem":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"Card identifier from request"},"grade":{"type":"string","title":"Grade","description":"Grade from request"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price","description":"Estimated price in USD"},"price_low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Low","description":"Lower bound of price estimate"},"price_high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price High","description":"Upper bound of price estimate"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","description":"Confidence score (0-1)"},"method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Method","description":"Estimation method used (e.g., 'direct', 'correlated')"},"freshness_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Freshness Days","description":"Age of data used for estimation in days"},"support_grades":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Support Grades","description":"Number of supporting grade data points"},"grade_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Grade Label","description":"Grade label used for estimation"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider","description":"Grading provider (e.g., 'PSA', 'BGS')"},"grade_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Grade Value","description":"Numeric grade value"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if estimation failed for this item"}},"type":"object","required":["card_id","grade"],"title":"BatchPriceEstimateResultItem","description":"Single result item from batch price estimation."},"CardData":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier"},"description":{"type":"string","title":"Description","description":"Full card description"},"player":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Player","description":"Player or character name"},"set":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set","description":"Card set name"},"number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Number","description":"Card number in set"},"variant":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant","description":"Card variant"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image","description":"Card image URL"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Card category"},"category_group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category Group","description":"Category group"},"set_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set Type","description":"Set type"}},"type":"object","required":["card_id","description"],"title":"CardData","description":"Full card data from CardHedge database."},"CardDetails":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Full card description"},"player":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Player","description":"Player or character name"},"set":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set","description":"Card set name"},"number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Number","description":"Card number in set"},"variant":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant","description":"Card variant (e.g., Base, Refractor, Prizm)"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image","description":"Card image URL"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Card category (e.g., Baseball, Basketball, Pokemon)"},"category_group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category Group","description":"Category group"},"set_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set Type","description":"Set type"}},"additionalProperties":true,"type":"object","required":["card_id"],"title":"CardDetails","description":"Detailed card information and metadata."},"CardDetailsRequest":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier from CardHedge"},"raw_images_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Raw Images Only","description":"If true, only include raw images (actual card photos) in results, excluding stock/placeholder images"}},"type":"object","required":["card_id"],"title":"CardDetailsRequest","description":"Request parameters for card details endpoint."},"CardIssueCreate":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"The unique card ID from CardHedge (e.g. from card-search or card-details)","example":"1587446850514x224832321163624450"},"card_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Title","description":"Optional card title for context (e.g. '2018 Topps Chrome Shohei Ohtani #150 Refractor')"},"issue_description":{"type":"string","minLength":10,"title":"Issue Description","description":"Detailed description of the data issue — what is wrong and what the correct value should be (minimum 10 characters)","example":"PSA 10 price showing $250 but recent comps are consistently $2,500+"}},"type":"object","required":["card_id","issue_description"],"title":"CardIssueCreate","description":"Request body for submitting a card data issue."},"CardIssueDetail":{"properties":{"id":{"type":"integer","title":"Id","description":"Unique issue ID"},"card_id":{"type":"string","title":"Card Id","description":"The card ID this issue relates to"},"card_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Title","description":"Card title (if provided at submission)"},"issue_description":{"type":"string","title":"Issue Description","description":"Description of the reported issue"},"customer_id":{"type":"integer","title":"Customer Id","description":"ID of the customer who submitted the issue"},"status":{"type":"string","title":"Status","description":"Current status: `new` (submitted), `in_progress` (being reviewed), or `resolved` (fixed)"},"resolution_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Description","description":"Description of how the issue was resolved (populated when status is 'resolved')"},"date_fixed":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Date Fixed","description":"Timestamp when the issue was resolved (null until fixed)"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the issue was submitted"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the issue was last updated"}},"type":"object","required":["id","card_id","issue_description","customer_id","status","created_at","updated_at"],"title":"CardIssueDetail","description":"Full card issue details including resolution information."},"CardIssueListResponse":{"properties":{"issues":{"items":{"$ref":"#/components/schemas/CardIssueDetail"},"type":"array","title":"Issues","description":"List of card issues, ordered by most recent first"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of issues matching the query"}},"type":"object","required":["issues","total_count"],"title":"CardIssueListResponse","description":"Paginated list of card issues for the authenticated API key."},"CardIssueResponse":{"properties":{"id":{"type":"integer","title":"Id","description":"Unique issue ID — use this to check status later"},"status":{"type":"string","title":"Status","description":"Issue status (always 'new' on creation)"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the issue was created"}},"type":"object","required":["id","status","created_at"],"title":"CardIssueResponse","description":"Response returned after successfully creating a card issue."},"CardMatchRequest":{"properties":{"query":{"type":"string","maxLength":500,"minLength":3,"title":"Query","description":"Natural language description of the card to match (e.g., '2018 Topps Chrome Shohei Ohtani rookie base')"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Optional category filter to narrow search (e.g., 'Baseball', 'Pokemon')"},"max_candidates":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Max Candidates","description":"Number of search results to evaluate (1-10, more = slower but potentially more accurate)","default":10},"raw_images_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Raw Images Only","description":"If true, only return actual card photos (not graded slab images). Defaults to true.","default":true}},"type":"object","required":["query"],"title":"CardMatchRequest","description":"Request parameters for AI-powered card matching."},"CardMatchResponse":{"properties":{"match":{"anyOf":[{"$ref":"#/components/schemas/CardMatchResult"},{"type":"null"}],"description":"Best matching card with confidence score, or null if no confident match found"},"candidates_evaluated":{"type":"integer","title":"Candidates Evaluated","description":"Number of candidate cards evaluated by the AI"},"search_query_used":{"type":"string","title":"Search Query Used","description":"The search query that was sent to the card search API"}},"type":"object","required":["candidates_evaluated","search_query_used"],"title":"CardMatchResponse","description":"Response model for AI-powered card matching.","examples":[{"candidates_evaluated":10,"match":{"card_id":"1587446850514x224832321163624450","category":"Baseball","confidence":0.95,"description":"Shohei Ohtani 2018 Topps Chrome Baseball","image":"//s3.amazonaws.com/appforest_uf/example.jpg","number":"150","player":"Shohei Ohtani","prices":[{"grade":"PSA 10","price":"850"},{"grade":"PSA 9","price":"125"}],"reasoning":"Exact match on player (Shohei Ohtani), year (2018), set (Topps Chrome), and variant (Base). This is the most commonly referenced version of this card.","set":"2018 Topps Chrome Baseball","variant":"Base"},"search_query_used":"Shohei Ohtani 2018 Topps Chrome"}]},"CardMatchResult":{"properties":{"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"Confidence score from 0.0 to 1.0 that this is the correct card"},"reasoning":{"type":"string","title":"Reasoning","description":"Brief explanation of why this card was selected as the best match"},"description":{"type":"string","title":"Description","description":"Full card description"},"player":{"type":"string","title":"Player","description":"Player or character name"},"set":{"type":"string","title":"Set","description":"Card set name"},"number":{"type":"string","title":"Number","description":"Card number in set"},"variant":{"type":"string","title":"Variant","description":"Card variant (e.g., 'Base', 'Reverse Foil')"},"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier"},"image":{"type":"string","title":"Image","description":"Card image URL"},"category":{"type":"string","title":"Category","description":"Card category"},"prices":{"items":{"$ref":"#/components/schemas/CardPrice"},"type":"array","title":"Prices","description":"Price information at different grades"}},"type":"object","required":["confidence","reasoning","description","player","set","number","variant","card_id","image","category"],"title":"CardMatchResult","description":"The top matched card with confidence score."},"CardPrice":{"properties":{"grade":{"type":"string","title":"Grade","description":"Card grade (e.g., 'Raw', 'PSA 10')"},"price":{"type":"string","title":"Price","description":"Price in string format"}},"type":"object","required":["grade","price"],"title":"CardPrice","description":"Price information for a card at different grades."},"CardRequestRequest":{"properties":{"player":{"type":"string","title":"Player","description":"Player or character name"},"set":{"type":"string","title":"Set","description":"Card set name (e.g., '2020 Panini Illusions')"},"card_number":{"type":"string","title":"Card Number","description":"Card number in set"},"subset":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subset","description":"Card subset (optional)"},"image_url":{"type":"string","title":"Image Url","description":"URL to card image"},"external_id":{"type":"string","title":"External Id","description":"Your reference ID for tracking. This ID will be included in the webhook response when the card is added."},"token":{"type":"string","title":"Token","description":"Your Client ID provided by Card Hedge. This endpoint requires a commercial agreement — contact Card Hedge to obtain your Client ID."},"variant":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant","description":"Card variant (e.g., 'Blue', 'Refractor')"}},"type":"object","required":["player","set","card_number","image_url","external_id","token"],"title":"CardRequestRequest","description":"Request parameters for card request endpoint."},"CardRequestResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Request status ('Success' or 'NOT_RUN')"},"message":{"type":"string","title":"Message","description":"Status message"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Card request ID (only on success)"}},"type":"object","required":["status","message"],"title":"CardRequestResponse","description":"Response model for card request endpoint.","examples":[{"id":"1766157241863x266716738264924480","message":"The request was created successfully.","status":"Success"},{"message":"The condition for the workflow create-pub-card-request is not met. Workflow won't run","status":"NOT_RUN"}]},"CardSearchCard":{"properties":{"description":{"type":"string","title":"Description","description":"Full card description"},"player":{"type":"string","title":"Player","description":"Player or character name"},"set":{"type":"string","title":"Set","description":"Card set name"},"number":{"type":"string","title":"Number","description":"Card number in set"},"variant":{"type":"string","title":"Variant","description":"Card variant (e.g., 'Base', 'Reverse Foil')"},"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier"},"image":{"type":"string","title":"Image","description":"Card image URL"},"category":{"type":"string","title":"Category","description":"Card category"},"category_group":{"type":"string","title":"Category Group","description":"Category group"},"set_type":{"type":"string","title":"Set Type","description":"Set type"},"7 Day Sales":{"type":"integer","title":"7 Day Sales","description":"Sales in last 7 days"},"30 Day Sales":{"type":"integer","title":"30 Day Sales","description":"Sales in last 30 days"},"rookie":{"type":"boolean","title":"Rookie","description":"Whether the card is a rookie card"},"gain":{"type":"number","title":"Gain","description":"Price gain percentage"},"prices":{"items":{"$ref":"#/components/schemas/CardPrice"},"type":"array","title":"Prices","description":"Price information at different grades"}},"type":"object","required":["description","player","set","number","variant","card_id","image","category","category_group","set_type","7 Day Sales","30 Day Sales","rookie","gain","prices"],"title":"CardSearchCard","description":"Card information from search results."},"CardSearchLocalCard":{"properties":{"description":{"type":"string","title":"Description","description":"Full card description"},"player":{"type":"string","title":"Player","description":"Player or character name"},"set":{"type":"string","title":"Set","description":"Card set name"},"number":{"type":"string","title":"Number","description":"Card number in set"},"variant":{"type":"string","title":"Variant","description":"Card variant (e.g., 'Base', 'Gold', 'Refractor')"},"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier"},"image":{"type":"string","title":"Image","description":"Card image URL"},"category":{"type":"string","title":"Category","description":"Card category (e.g., 'Baseball', 'Pokemon')"},"category_group":{"type":"string","title":"Category Group","description":"Category group (e.g., 'Sports Cards', 'Trading Cards')"},"set_type":{"type":"string","title":"Set Type","description":"Set type"},"7 Day Sales":{"type":"integer","title":"7 Day Sales","description":"Sales volume in last 7 days"},"30 Day Sales":{"type":"integer","title":"30 Day Sales","description":"Sales volume in last 30 days"},"rookie":{"type":"boolean","title":"Rookie","description":"Whether the card is a rookie card"},"gain":{"type":"number","title":"Gain","description":"Price gain percentage (7-day)"},"gain_30day":{"type":"number","title":"Gain 30Day","description":"Price gain percentage (30-day)"},"stats_grade":{"type":"string","title":"Stats Grade","description":"Primary grade (e.g., 'PSA 10', 'BGS 9.5')"},"prices":{"items":{"$ref":"#/components/schemas/CardPrice"},"type":"array","title":"Prices","description":"Price information at different grades"}},"type":"object","required":["description","player","set","number","variant","card_id","image","category","category_group","set_type","7 Day Sales","30 Day Sales","rookie","gain","gain_30day","stats_grade","prices"],"title":"CardSearchLocalCard","description":"Card information from local database search results."},"CardSearchLocalRequest":{"properties":{"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Full-text search query for fuzzy matching on card description/player (e.g., 'Trout rookie')"},"set":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set","description":"Filter by exact set name (e.g., '2024 Topps Chrome Baseball')"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Filter by exact category (e.g., 'Baseball', 'Pokemon', 'Basketball')"},"player":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Player","description":"Filter by exact player name (e.g., 'Mike Trout', 'Shohei Ohtani')"},"raw_images_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Raw Images Only","description":"If true, use raw card images instead of graded images"},"sort_by":{"type":"string","enum":["gain","gain_30day","sales","sales_7day","sales_30day","price","description"],"title":"Sort By","description":"Field to sort by: gain (7-day price change %), gain_30day (30-day price change %), sales_7day (7-day volume), sales_30day or sales (30-day volume), price (current price), description (alphabetical)","default":"gain"},"sort_order":{"type":"string","enum":["asc","desc"],"title":"Sort Order","description":"Sort order: asc (ascending) or desc (descending)","default":"desc"},"page":{"type":"integer","minimum":1.0,"title":"Page","description":"Page number for pagination","default":1},"page_size":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Page Size","description":"Number of results per page (1-100)","default":50}},"type":"object","title":"CardSearchLocalRequest","description":"Request parameters for local card search endpoint (Supabase-backed)."},"CardSearchLocalResponse":{"properties":{"pages":{"type":"integer","title":"Pages","description":"Total number of pages available","default":1},"count":{"type":"integer","title":"Count","description":"Total number of matching cards","default":0},"cards":{"items":{"$ref":"#/components/schemas/CardSearchLocalCard"},"type":"array","title":"Cards","description":"List of matching cards"}},"type":"object","title":"CardSearchLocalResponse","description":"Response model for local card search endpoint.","examples":[{"cards":[{"30 Day Sales":187,"7 Day Sales":45,"card_id":"1587446850514x224832321163624450","category":"Baseball","category_group":"Sports Cards","description":"Shohei Ohtani 2024 Topps Chrome Baseball","gain":12.5,"gain_30day":18.3,"image":"https://example.com/card.jpg","number":"150","player":"Shohei Ohtani","prices":[{"grade":"PSA 10","price":"850"},{"grade":"PSA 9","price":"125"},{"grade":"Raw","price":"45.99"}],"rookie":false,"set":"2024 Topps Chrome Baseball","set_type":"Topps Chrome Baseball","stats_grade":"PSA 10","variant":"Base"}],"count":742,"pages":15}]},"CardSearchRequest":{"properties":{"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Search query for card name/description"},"set":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set","description":"Filter by set name (e.g., '2025 Topps Baseball')"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Filter by category (e.g., 'Baseball', 'Basketball')"},"player":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Player","description":"Filter by player name"},"rookie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rookie","description":"Filter by rookie status (e.g., 'Rookie')"},"page":{"type":"integer","minimum":1.0,"title":"Page","description":"Page number for pagination","default":1},"page_size":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Page Size","description":"Number of results per page (1-100)","default":50},"raw_images_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Raw Images Only","description":"If true, only include raw images (actual card photos) in results, excluding stock/placeholder images"}},"type":"object","title":"CardSearchRequest","description":"Request parameters for card search endpoint."},"CardSearchResponse":{"properties":{"pages":{"type":"integer","title":"Pages","description":"Total number of pages available","default":1},"count":{"type":"integer","title":"Count","description":"Total number of matching cards","default":0},"cards":{"items":{"$ref":"#/components/schemas/CardSearchCard"},"type":"array","title":"Cards","description":"List of matching cards"}},"type":"object","required":["cards"],"title":"CardSearchResponse","description":"Response model for card search endpoint.","examples":[{"cards":[{"30 Day Sales":187,"7 Day Sales":45,"card_id":"1587446850514x224832321163624450","category":"Baseball","category_group":"Sports Cards","description":"Shohei Ohtani 2018 Topps Chrome Baseball","gain":2.5,"image":"//s3.amazonaws.com/appforest_uf/example.jpg","number":"150","player":"Shohei Ohtani","prices":[{"grade":"PSA 10","price":"850"},{"grade":"PSA 9","price":"125"},{"grade":"Raw","price":"45.99"}],"rookie":true,"set":"2018 Topps Chrome Baseball","set_type":"Topps Chrome Baseball","variant":"Base"}],"count":742,"pages":15}]},"CertLookupRequest":{"properties":{"cert":{"type":"string","title":"Cert","description":"Certificate number to lookup","examples":["76676185"]},"grader":{"type":"string","title":"Grader","description":"Grading company (defaults to PSA)","default":"PSA","examples":["PSA"]},"days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Days","description":"Number of days of price history to retrieve (1-365, defaults to 180)","default":180,"examples":[180]}},"type":"object","required":["cert"],"title":"CertLookupRequest","description":"Request parameters for certificate lookup endpoint.","examples":[{"cert":"76676185","days":180,"grader":"PSA"}]},"CertLookupResponse":{"properties":{"cert_info":{"$ref":"#/components/schemas/GemRateCertInfo","description":"Certificate verification details including grade and card description"},"card":{"anyOf":[{"$ref":"#/components/schemas/CardDetails"},{"type":"null"}],"description":"Card details and metadata (null if not found in database)"},"prices":{"items":{"$ref":"#/components/schemas/PriceHistory"},"type":"array","title":"Prices","description":"Daily price history for the card"}},"type":"object","required":["cert_info"],"title":"CertLookupResponse","description":"Response model for certificate lookup endpoint.","examples":[{"card":{"card_id":"1699670576265x928796749151534600","category":"Baseball","category_group":"Sports Cards","description":"C.C. Sabathia 1999 Bowman Chrome Baseball","image":"https://942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1699670857725x475053799924132860/resized_20231111_024737.jpeg","number":"344","player":"C.C. Sabathia","set":"1999 Bowman Chrome Baseball","set_type":"Bowman Chrome Baseball","variant":"Base"},"cert_info":{"cert":"50000000","description":"1999 Bowman Chrome C.C. Sabathia 344","gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885","grade":"PSA 10","grader":"psa","universal_gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885"},"prices":[{"Grade":"PSA 10","card_id":"1699670576265x928796749151534600","closing_date":"2025-10-26T23:59:00.000Z","price":"125.50"},{"Grade":"PSA 10","card_id":"1699670576265x928796749151534600","closing_date":"2025-10-25T23:59:00.000Z","price":"122.00"}]}]},"CertPriceRequest":{"properties":{"certs":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Certs","description":"List of certificate numbers to lookup (max 100)","examples":[["76676185","50000000"]]},"grader":{"type":"string","title":"Grader","description":"Grading company (defaults to PSA)","default":"PSA","examples":["PSA"]}},"type":"object","required":["certs"],"title":"CertPriceRequest","description":"Request parameters for batch cert-to-price endpoint.","examples":[{"certs":["76676185","50000000"],"grader":"PSA"}]},"CertPriceResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/CertPriceResult"},"type":"array","title":"Results","description":"List of cert price results"},"total_requested":{"type":"integer","title":"Total Requested","description":"Number of certificates requested"},"total_found":{"type":"integer","title":"Total Found","description":"Number of certificates with a price estimate"}},"type":"object","required":["results","total_requested","total_found"],"title":"CertPriceResponse","description":"Response model for batch cert-to-price endpoint.","examples":[{"results":[{"card":{"card_id":"1699670576265x928796749151534600","category":"Baseball","category_group":"Sports Cards","description":"C.C. Sabathia 1999 Bowman Chrome Baseball","image":"https://example.com/card.jpg","number":"344","player":"C.C. Sabathia","set":"1999 Bowman Chrome Baseball","set_type":"Bowman Chrome Baseball","variant":"Base"},"cert_info":{"cert":"50000000","description":"1999 Bowman Chrome C.C. Sabathia 344","gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885","grade":"PSA 10","grader":"psa","universal_gemrate_id":"25783324b9710f1366ca4d54f3dd4689c02b6885"},"confidence":0.3869,"method":"direct","price":125.5,"price_high":141.0,"price_low":110.0}],"total_found":1,"total_requested":2}]},"CertPriceResult":{"properties":{"cert_info":{"$ref":"#/components/schemas/GemRateCertInfo","description":"Certificate verification details including grade and card description"},"card":{"anyOf":[{"$ref":"#/components/schemas/CardDetails"},{"type":"null"}],"description":"Card details and metadata (null if not found in database)"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price","description":"Estimated price in USD (null if unavailable)"},"price_low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Low","description":"Lower bound of price estimate (null if unavailable)"},"price_high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price High","description":"Upper bound of price estimate (null if unavailable)"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","description":"Confidence score (0-1, null if unavailable)"},"method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Method","description":"Estimation method used (e.g., 'direct', 'correlated')"}},"type":"object","required":["cert_info"],"title":"CertPriceResult","description":"Single result from batch cert-to-price lookup."},"CompsRequest":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"Card ID"},"count":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Count","description":"Number of comp prices (1-100)"},"grade":{"type":"string","title":"Grade","description":"Card grade (e.g., 'PSA 10', 'BGS 9.5')"},"time_weighted":{"type":"boolean","title":"Time Weighted","description":"If true, weight recent sales more heavily using WMA algorithm","default":false},"include_raw_prices":{"type":"boolean","title":"Include Raw Prices","description":"If true, include raw price data in response","default":false}},"type":"object","required":["card_id","count","grade"],"title":"CompsRequest","description":"Request schema for getting comp prices."},"CompsResponse":{"properties":{"comp_price":{"type":"number","title":"Comp Price","description":"Calculated comparable price (after anomaly filtering)"},"high":{"type":"number","title":"High","description":"Highest sale price used in comp calculation"},"low":{"type":"number","title":"Low","description":"Lowest sale price used in comp calculation"},"count_requested":{"type":"integer","title":"Count Requested","description":"Number of prices requested"},"count_used":{"type":"integer","title":"Count Used","description":"Number of prices used in calculation (after anomaly filtering)"},"time_weighted":{"type":"boolean","title":"Time Weighted","description":"Whether time-weighted algorithm was used"},"raw_prices":{"anyOf":[{"items":{"$ref":"#/components/schemas/RawSale"},"type":"array"},{"type":"null"}],"title":"Raw Prices","description":"Raw price data (only included if include_raw_prices=true)"}},"type":"object","required":["comp_price","high","low","count_requested","count_used","time_weighted"],"title":"CompsResponse","description":"Response schema for comp prices.","examples":[{"comp_price":336.0,"count_requested":5,"count_used":5,"high":348.0,"low":325.0,"raw_prices":[{"card_id":"1587446850514x224832321163624450","grade":"PSA 9","image":"[image url]","price":325.0,"price_history_id":"1761480061129x501444455762531900","price_source":"marketplace","sale_date":"2025-10-26T13:00:00.000Z","sale_type":"Best Offer","sale_url":"[sale url]","title":"[listing title]"},{"card_id":"1587446850514x224832321163624450","grade":"PSA 9","image":"[image url]","price":348.0,"price_history_id":"1761446206940x522975047258362750","price_source":"marketplace","sale_date":"2025-10-26T03:36:00.000Z","sale_type":"Auction","sale_url":"[sale url]","title":"[listing title]"}],"time_weighted":true}]},"GemRateCertInfo":{"properties":{"grader":{"type":"string","title":"Grader","description":"Grading company (e.g., PSA, BGS, CGC)"},"cert":{"type":"string","title":"Cert","description":"Certificate number"},"grade":{"type":"string","title":"Grade","description":"Card grade (e.g., PSA 10, BGS 9.5)"},"gemrate_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gemrate Id","description":"Unique card identifier"},"universal_gemrate_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Universal Gemrate Id","description":"Universal card identifier"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Card description from certificate"}},"additionalProperties":true,"type":"object","required":["grader","cert","grade"],"title":"GemRateCertInfo","description":"Certificate verification information."},"GradePrice":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier"},"grade":{"type":"string","title":"Grade","description":"Card grade (e.g., PSA 10, BGS 9.5, Raw)"},"grader":{"type":"string","title":"Grader","description":"Grading company (e.g., PSA, BGS, SGC, CGC)"},"price":{"type":"string","title":"Price","description":"Latest price for this grade"},"display_order":{"type":"string","title":"Display Order","description":"Display order for sorting grades"}},"type":"object","required":["card_id","grade","grader","price","display_order"],"title":"GradePrice","description":"Price information for a specific grade."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ImageCertDetailsRequest":{"properties":{"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"Public URL of the graded card image"},"image_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Base64","description":"Base64-encoded image of the graded card (with or without data URI prefix)"}},"type":"object","title":"ImageCertDetailsRequest","description":"Request parameters for image-based certificate details endpoint (no price history).","examples":[{"image_url":"https://example.com/graded-card.jpg"}]},"ImageCertLookupRequest":{"properties":{"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"Public URL of the graded card image"},"image_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Base64","description":"Base64-encoded image of the graded card (with or without data URI prefix)"},"days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Days","description":"Number of days of price history to retrieve (1-365, defaults to 180)","default":180,"examples":[180]}},"type":"object","title":"ImageCertLookupRequest","description":"Request parameters for image-based certificate lookup endpoint.","examples":[{"days":180,"image_url":"https://example.com/graded-card.jpg"}]},"ImageSearchRequest":{"properties":{"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"Public URL to card image"},"image_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Base64","description":"Base64-encoded image data (with or without data URI prefix)"},"k":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"K","description":"Number of similar results to return (max: 50)","default":10}},"type":"object","title":"ImageSearchRequest","description":"Request model for image search endpoint.","examples":[{"image_url":"https://example.com/card.jpg","k":10},{"image_base64":"data:image/jpeg;base64,/9j/4AAQSkZJRg...","k":5}]},"ImageSearchResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the search was successful"},"results":{"items":{"$ref":"#/components/schemas/ImageSearchResultItem"},"type":"array","title":"Results","description":"List of similar cards found"},"total_results":{"type":"integer","title":"Total Results","description":"Total number of results returned"},"query_id":{"type":"string","title":"Query Id","description":"Ximilar query record ID for tracking"},"has_cardhedge_matches":{"type":"boolean","title":"Has Cardhedge Matches","description":"Whether any results have CardHedge data"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Additional information about the search"}},"type":"object","required":["success","results","total_results","query_id","has_cardhedge_matches"],"title":"ImageSearchResponse","description":"Response model for image search endpoint.","examples":[{"has_cardhedge_matches":true,"message":"Results include CardHedge data where available, AI identification as fallback","query_id":"query_abc123","results":[{"card_data":{"card_id":"1587446850514x224832321163624450","category":"Baseball","description":"Ken Griffey Jr. 1989 Upper Deck Baseball","image":"https://example.com/card.jpg","number":"1","player":"Ken Griffey Jr.","set":"1989 Upper Deck Baseball","variant":"Rookie Card"},"distance":0.0477,"product_id":"1587446850514x224832321163624450","similarity":"95.23","ximilar_id":"xim_abc123"}],"success":true,"total_results":5}]},"ImageSearchResultItem":{"properties":{"similarity":{"type":"string","title":"Similarity","description":"Similarity percentage (e.g., '95.23')"},"distance":{"type":"number","title":"Distance","description":"Distance score from Ximilar (0-1, lower is better)"},"ximilar_id":{"type":"string","title":"Ximilar Id","description":"Ximilar record ID"},"product_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Id","description":"CardHedge product ID if available"},"card_data":{"anyOf":[{"$ref":"#/components/schemas/CardData"},{"type":"null"}],"description":"Full card data from CardHedge"},"ai_fallback_info":{"anyOf":[{"$ref":"#/components/schemas/AIFallbackInfo"},{"type":"null"}],"description":"AI fallback identification when no CardHedge match"}},"type":"object","required":["similarity","distance","ximilar_id"],"title":"ImageSearchResultItem","description":"Individual image search result.","examples":[{"card_data":{"card_id":"1587446850514x224832321163624450","category":"Baseball","category_group":"Sports Cards","description":"Ken Griffey Jr. 1989 Upper Deck Baseball","image":"https://example.com/card.jpg","number":"1","player":"Ken Griffey Jr.","set":"1989 Upper Deck Baseball","set_type":"Upper Deck Baseball","variant":"Rookie Card"},"distance":0.0477,"product_id":"1587446850514x224832321163624450","similarity":"95.23","ximilar_id":"xim_abc123"},{"ai_fallback_info":{"card_name":"2018 Panini Prizm Luka Doncic #280 Rookie Card","card_type":"sports","confidence":87.65,"source":"ximilar"},"distance":0.1235,"similarity":"87.65","ximilar_id":"xim_xyz789"}]},"PlayerSalesResult":{"properties":{"player":{"type":"string","title":"Player","description":"Player/character name searched"},"total_sales":{"type":"integer","title":"Total Sales","description":"Total number of sales found"},"search_time_ms":{"type":"integer","title":"Search Time Ms","description":"Typesense search time in ms"}},"type":"object","required":["player","total_sales","search_time_ms"],"title":"PlayerSalesResult"},"PlayerSalesStats":{"properties":{"player":{"type":"string","title":"Player","description":"Player or character name searched."},"buckets":{"items":{"$ref":"#/components/schemas/SalesStatsBucket"},"type":"array","title":"Buckets","description":"Buckets ordered oldest to newest."}},"type":"object","required":["player","buckets"],"title":"PlayerSalesStats"},"PriceByGradeCard":{"properties":{"description":{"type":"string","title":"Description","description":"Full card description"},"player":{"type":"string","title":"Player","description":"Player or character name"},"set":{"type":"string","title":"Set","description":"Card set name"},"number":{"type":"string","title":"Number","description":"Card number in set"},"variant":{"type":"string","title":"Variant","description":"Card variant"},"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier"},"gemrate_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gemrate Id","description":"GemRate card identifier"},"image":{"type":"string","title":"Image","description":"Card image URL"},"category":{"type":"string","title":"Category","description":"Card category"},"category_group":{"type":"string","title":"Category Group","description":"Category group"},"set_type":{"type":"string","title":"Set Type","description":"Set type"},"90_day_sales":{"type":"integer","title":"90 Day Sales","description":"Number of sales in last 90 days"},"grade":{"type":"string","title":"Grade","description":"Card grade"},"price":{"type":"string","title":"Price","description":"Average price for the grade"}},"type":"object","required":["description","player","set","number","variant","card_id","image","category","category_group","set_type","90_day_sales","grade","price"],"title":"PriceByGradeCard","description":"Card with 90-day price for a specific grade."},"PriceByGradeRequest":{"properties":{"page":{"type":"integer","minimum":1.0,"title":"Page","description":"Page number for pagination","default":1},"page_size":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Page Size","description":"Number of results per page","default":100},"grade":{"type":"string","title":"Grade","description":"Card grade (e.g., 'PSA 10', 'SGC 10', 'BGS 9.5')"},"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Optional search query for card name"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Optional category filter (e.g., 'Pokemon', 'Baseball')"}},"type":"object","required":["grade"],"title":"PriceByGradeRequest","description":"Request model for 90-day price by grade endpoint."},"PriceByGradeResponse":{"properties":{"page":{"type":"integer","title":"Page","description":"Current page number","default":1},"pages":{"type":"integer","title":"Pages","description":"Total number of pages","default":1},"cards":{"items":{"$ref":"#/components/schemas/PriceByGradeCard"},"type":"array","title":"Cards","description":"List of cards with price data"}},"type":"object","title":"PriceByGradeResponse","description":"Response model for 90-day price by grade endpoint."},"PriceEstimateItem":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier from CardHedge"},"grade":{"type":"string","title":"Grade","description":"Card grade (e.g., 'PSA 9', 'PSA 10', 'BGS 9.5')"}},"type":"object","required":["card_id","grade"],"title":"PriceEstimateItem","description":"Single item for batch price estimation."},"PriceEstimateRequest":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier from CardHedge"},"grade":{"type":"string","title":"Grade","description":"Card grade (e.g., 'PSA 9', 'PSA 10', 'BGS 9.5')"}},"type":"object","required":["card_id","grade"],"title":"PriceEstimateRequest","description":"Request parameters for price estimation endpoint."},"PriceEstimateResponse":{"properties":{"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price","description":"Estimated price in USD (null when no data available)"},"price_low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Low","description":"Lower bound of price estimate (null when no data available)"},"price_high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price High","description":"Upper bound of price estimate (null when no data available)"},"confidence":{"type":"number","title":"Confidence","description":"Confidence score (0-1)"},"method":{"type":"string","title":"Method","description":"Estimation method used (e.g., 'direct', 'correlated', 'segment_fallback')"},"freshness_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Freshness Days","description":"Age of data used for estimation in days (null for fallback methods)"},"support_grades":{"type":"integer","title":"Support Grades","description":"Number of supporting grade data points"},"grade_label":{"type":"string","title":"Grade Label","description":"Grade label used for estimation"},"provider":{"type":"string","title":"Provider","description":"Grading provider (e.g., 'PSA', 'BGS', 'AGS')"},"grade_value":{"type":"number","title":"Grade Value","description":"Numeric grade value"}},"type":"object","required":["confidence","method","support_grades","grade_label","provider","grade_value"],"title":"PriceEstimateResponse","description":"Response model for price estimation endpoint.","examples":[{"confidence":0.3809,"freshness_days":2,"grade_label":"PSA 9","grade_value":9.0,"method":"direct","price":385.0,"price_high":407.92,"price_low":362.08,"provider":"PSA","support_grades":1}]},"PriceHistory":{"properties":{"closing_date":{"type":"string","title":"Closing Date","description":"Date of the price point"},"Grade":{"type":"string","title":"Grade","description":"Card grade"},"card_id":{"type":"string","title":"Card Id","description":"Card ID"},"price":{"type":"string","title":"Price","description":"Price value"}},"type":"object","required":["closing_date","Grade","card_id","price"],"title":"PriceHistory","description":"Individual price point from CardHedge."},"PriceSubscriptionItem":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"CardHedge card ID"},"grade":{"type":"string","title":"Grade","description":"Card grade (e.g., 'PSA 10', 'BGS 9.5')"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Optional external reference ID. If omitted, the card_id is used as the external identifier."}},"type":"object","required":["card_id","grade"],"title":"PriceSubscriptionItem","description":"Single card to subscribe to price updates for."},"PriceUpdate":{"properties":{"price":{"type":"string","title":"Price","description":"Sale price"},"sale_date":{"type":"string","title":"Sale Date","description":"Date of the sale (YYYY-MM-DD)"},"grade":{"type":"string","title":"Grade","description":"Card grade (e.g., 'PSA 9', 'PSA 10', 'Raw')"},"card_desc":{"type":"string","title":"Card Desc","description":"Full card description"},"card_set":{"type":"string","title":"Card Set","description":"Card set name"},"card_number":{"type":"string","title":"Card Number","description":"Card number in set"},"player":{"type":"string","title":"Player","description":"Player or character name"},"variant":{"type":"string","title":"Variant","description":"Card variant"},"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier"},"update_timestamp":{"type":"string","title":"Update Timestamp","description":"Timestamp when the price was updated (ISO format)"}},"type":"object","required":["price","sale_date","grade","card_desc","card_set","card_number","player","variant","card_id","update_timestamp"],"title":"PriceUpdate","description":"Individual price update from the delta poll API."},"PriceUpdatesRequest":{"properties":{"since":{"type":"string","title":"Since","description":"ISO timestamp to fetch updates since (e.g., '2023-07-16T01:28:57.000Z')"},"ignore_grades":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Ignore Grades","description":"List of grades to exclude from results (e.g., ['Raw'])"}},"type":"object","required":["since"],"title":"PriceUpdatesRequest","description":"Request parameters for price updates endpoint."},"PriceUpdatesResponse":{"properties":{"updates":{"items":{"$ref":"#/components/schemas/PriceUpdate"},"type":"array","title":"Updates","description":"List of price updates since the specified timestamp"},"count":{"type":"integer","title":"Count","description":"Number of updates returned"}},"type":"object","required":["updates","count"],"title":"PriceUpdatesResponse","description":"Response model for price updates endpoint.","examples":[{"count":2,"updates":[{"card_desc":"James Wood 2022 Bowman Chrome Prospects Sapphire Baseball","card_id":"1669693578344x525012276222885900","card_number":"BCP-108","card_set":"2022 Bowman Chrome Prospects Sapphire Baseball","grade":"PSA 9","player":"James Wood","price":"53.88","sale_date":"2023-07-15","update_timestamp":"2023-07-16T01:29:01.227Z","variant":"Base"},{"card_desc":"James Wood 2022 Bowman Chrome Prospects Sapphire Baseball","card_id":"1669693578344x525012276222885900","card_number":"BCP-108","card_set":"2022 Bowman Chrome Prospects Sapphire Baseball","grade":"PSA 10","player":"James Wood","price":"116.5","sale_date":"2023-07-15","update_timestamp":"2023-07-16T01:29:02.774Z","variant":"Base"}]}]},"PricesByCardRequest":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier","examples":["1587446850514x224832321163624450"]},"grade":{"type":"string","title":"Grade","description":"Grade (e.g., 'PSA 9', 'BGS 9.5')","examples":["PSA 9"]},"days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Days","description":"Number of days of price history to retrieve (1-365, defaults to 180)","default":180,"examples":[180]}},"type":"object","required":["card_id","grade"],"title":"PricesByCardRequest","description":"Request parameters for prices by card endpoint.","examples":[{"card_id":"1587446850514x224832321163624450","days":180,"grade":"PSA 9"}]},"PricesByCardResponse":{"properties":{"prices":{"items":{"$ref":"#/components/schemas/PriceHistory"},"type":"array","title":"Prices","description":"Daily price history for the specified card and grade"}},"type":"object","required":["prices"],"title":"PricesByCardResponse","description":"Response model for prices by card endpoint.","examples":[{"prices":[{"Grade":"PSA 9","card_id":"1587446850514x224832321163624450","closing_date":"2025-10-26T23:59:00.000Z","price":"337.67"},{"Grade":"PSA 9","card_id":"1587446850514x224832321163624450","closing_date":"2025-10-25T23:59:00.000Z","price":"337.00"},{"Grade":"PSA 9","card_id":"1587446850514x224832321163624450","closing_date":"2025-10-24T23:59:00.000Z","price":"331.29"}]}]},"RawSale":{"properties":{"price":{"type":"number","title":"Price","description":"Sale price in USD"},"sale_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sale Date","description":"Sale date"},"price_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price Source","description":"Sale source"},"sale_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sale Url","description":"URL to sold eBay listing"}},"additionalProperties":true,"type":"object","required":["price"],"title":"RawSale","description":"Individual raw sale data."},"SalesStatsBucket":{"properties":{"start":{"type":"string","title":"Start","description":"Bucket start date in UTC, inclusive (YYYY-MM-DD)."},"end":{"type":"string","title":"End","description":"Bucket end date in UTC, inclusive (YYYY-MM-DD). For a partial bucket this is today's date."},"count":{"type":"integer","title":"Count","description":"Number of sales matching the player in this bucket window."},"total_amount":{"type":"number","title":"Total Amount","description":"Sum of sale prices in USD across all matching sales."},"average_sale":{"type":"number","title":"Average Sale","description":"Arithmetic mean sale price in USD (sum ÷ count). Returns 0 when `count` is 0."},"partial":{"type":"boolean","title":"Partial","description":"True only for the in-progress current bucket. Always false for fully-closed historical buckets.","default":false}},"type":"object","required":["start","end","count","total_amount","average_sale"],"title":"SalesStatsBucket"},"SalesStatsByPlayerRequest":{"properties":{"players":{"items":{"type":"string"},"type":"array","maxItems":25,"minItems":1,"title":"Players","description":"Player or character names to look up. Each name is matched against the sale description text. Up to 25 names per request."},"interval":{"type":"string","enum":["day","week","month"],"title":"Interval","description":"Bucket size. `day` = midnight-to-midnight UTC, `week` = ISO week (Monday → Sunday), `month` = calendar month (1st → last day).","default":"week"},"periods":{"type":"integer","minimum":1.0,"title":"Periods","description":"Total number of buckets to return, ending with the most recent period. When `include_current` is true (default) the newest bucket is the in-progress period and counts toward this total. Caps per interval: day ≤ 90, week ≤ 52, month ≤ 24.","default":12},"include_current":{"type":"boolean","title":"Include Current","description":"When true (default), the newest bucket is the in-progress current period (month-to-date, week-to-date, or today so far) and is flagged `partial: true`. Set false to return only fully-closed periods — preferred for clean trend charts.","default":true}},"type":"object","required":["players"],"title":"SalesStatsByPlayerRequest"},"SalesStatsByPlayerResponse":{"properties":{"interval":{"type":"string","enum":["day","week","month"],"title":"Interval","description":"Bucket size used for this response."},"periods":{"type":"integer","title":"Periods","description":"Number of buckets returned per player (matches the request)."},"results":{"items":{"$ref":"#/components/schemas/PlayerSalesStats"},"type":"array","title":"Results","description":"One entry per requested player, in request order."}},"type":"object","required":["interval","periods","results"],"title":"SalesStatsByPlayerResponse"},"SearchWith90DayPricesCard":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier"},"description":{"type":"string","title":"Description","description":"Full card description"},"search_text":{"type":"string","title":"Search Text","description":"Typesense search text"},"text_match_score":{"type":"integer","title":"Text Match Score","description":"Typesense relevancy score"},"gemrate_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gemrate Id"},"player":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Player"},"set":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set"},"number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Number"},"variant":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"category_group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category Group"},"set_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set Type"},"90_day_sales":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"90 Day Sales","description":"Number of sales in last 90 days"},"grade":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Grade"},"price":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price"}},"type":"object","required":["card_id","description","search_text","text_match_score"],"title":"SearchWith90DayPricesCard","description":"Card result from Typesense search merged with 90-day price data."},"SearchWith90DayPricesRequest":{"properties":{"search":{"type":"string","title":"Search","description":"Search query"},"grade":{"type":"string","title":"Grade","description":"Card grade (e.g., 'PSA 10')"},"page":{"type":"integer","minimum":1.0,"title":"Page","description":"Page number for pagination","default":1},"page_size":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Page Size","description":"Number of results per page (max 100)","default":50}},"type":"object","required":["search","grade"],"title":"SearchWith90DayPricesRequest","description":"Request model for Typesense search + 90-day price by grade endpoint."},"SearchWith90DayPricesResponse":{"properties":{"page":{"type":"integer","title":"Page","description":"Current page number"},"pages":{"type":"integer","title":"Pages","description":"Total Typesense pages"},"found":{"type":"integer","title":"Found","description":"Total Typesense matches"},"search_time_ms":{"type":"integer","title":"Search Time Ms","description":"Typesense search time in milliseconds"},"cards":{"items":{"$ref":"#/components/schemas/SearchWith90DayPricesCard"},"type":"array","title":"Cards","description":"Cards in Typesense relevancy order"}},"type":"object","required":["page","pages","found","search_time_ms"],"title":"SearchWith90DayPricesResponse","description":"Response model for Typesense search + 90-day price by grade endpoint."},"SetSearchRequest":{"properties":{"search":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search","description":"Search query for set name"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"Filter by category (e.g., 'Baseball', 'Basketball', 'Pokemon')"},"count":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Count","description":"Number of results to return (1-100)","default":25}},"type":"object","title":"SetSearchRequest","description":"Request parameters for set search endpoint."},"SetSearchResponse":{"properties":{"count":{"type":"integer","title":"Count","description":"Number of sets returned"},"sets":{"items":{"$ref":"#/components/schemas/SetSearchSet"},"type":"array","title":"Sets","description":"List of matching sets"}},"type":"object","required":["count","sets"],"title":"SetSearchResponse","description":"Response model for set search endpoint.","examples":[{"count":3,"sets":[{"30 Day Sales":1250,"category":"Baseball","description":"2023 Topps Chrome Baseball","id":"1587446850514x224832321163624450","image":"//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1724143874181x158765543979815900/crop_image","name":"2023 Topps Chrome Baseball","set_type":"Topps Chrome Baseball","year":"2023"},{"30 Day Sales":2340,"category":"Baseball","description":"2024 Topps Chrome Baseball","id":"1684286084852x189232814543430100","image":"//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1724143874181x158765543979815901/crop_image","name":"2024 Topps Chrome Baseball","set_type":"Topps Chrome Baseball","year":"2024"},{"30 Day Sales":870,"category":"Baseball","description":"2022 Topps Chrome Baseball","id":"1699670576265x928796749151534600","image":"//942284f33c575895b4be9de571ca6e40.cdn.bubble.io/d112/f1724143874181x158765543979815902/crop_image","name":"2022 Topps Chrome Baseball","set_type":"Topps Chrome Baseball","year":"2022"}]}]},"SetSearchSet":{"properties":{"id":{"type":"string","title":"Id","description":"Unique set identifier"},"name":{"type":"string","title":"Name","description":"Set name"},"year":{"type":"string","title":"Year","description":"Set year","default":""},"set_type":{"type":"string","title":"Set Type","description":"Set type"},"description":{"type":"string","title":"Description","description":"Set description"},"category":{"type":"string","title":"Category","description":"Set category"},"image":{"type":"string","title":"Image","description":"Set image URL"},"30 Day Sales":{"type":"integer","title":"30 Day Sales","description":"Sales in last 30 days"}},"type":"object","required":["id","name","set_type","description","category","image","30 Day Sales"],"title":"SetSearchSet","description":"Set information from search results."},"SingleCertResult":{"properties":{"cert_info":{"$ref":"#/components/schemas/GemRateCertInfo","description":"Certificate verification details including grade and card description"},"card":{"anyOf":[{"$ref":"#/components/schemas/CardDetails"},{"type":"null"}],"description":"Card details and metadata (null if not found)"}},"type":"object","required":["cert_info"],"title":"SingleCertResult","description":"Single certificate result in batch lookup."},"SubscribePriceUpdatesRequest":{"properties":{"client_id":{"type":"string","title":"Client Id","description":"Your CardHedge client ID, used to authenticate with the price subscription service."},"subscriptions":{"items":{"$ref":"#/components/schemas/PriceSubscriptionItem"},"type":"array","maxItems":100,"minItems":1,"title":"Subscriptions","description":"List of cards to subscribe to price updates (max 100)"}},"type":"object","required":["client_id","subscriptions"],"title":"SubscribePriceUpdatesRequest","description":"Request to subscribe to price updates for one or more cards."},"SubscribePriceUpdatesResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/SubscriptionResult"},"type":"array","title":"Results","description":"Per-card subscription results"},"total_requested":{"type":"integer","title":"Total Requested","description":"Number of subscriptions requested"},"total_successful":{"type":"integer","title":"Total Successful","description":"Number of subscriptions that succeeded"}},"type":"object","required":["results","total_requested","total_successful"],"title":"SubscribePriceUpdatesResponse","description":"Response showing the outcome of each subscription attempt.","examples":[{"results":[{"card_id":"1586812246197x228181943611293700","external_id":"my_ref_123","grade":"PSA 10","success":true},{"card_id":"1699670576265x928796749151534600","error":"Card not found","external_id":"1699670576265x928796749151534600","grade":"PSA 9","success":false}],"total_requested":2,"total_successful":1}]},"SubscriptionResult":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"CardHedge card ID from request"},"grade":{"type":"string","title":"Grade","description":"Grade from request"},"external_id":{"type":"string","title":"External Id","description":"External ID used (card_id if none was provided)"},"success":{"type":"boolean","title":"Success","description":"Whether the subscription was created successfully"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if subscription failed"}},"type":"object","required":["card_id","grade","external_id","success"],"title":"SubscriptionResult","description":"Result of a single subscription attempt."},"TopAccountResponse":{"properties":{"customer_id":{"type":"integer","title":"Customer Id"},"customer_name":{"type":"string","title":"Customer Name"},"total_calls":{"type":"integer","title":"Total Calls"},"success_count":{"type":"integer","title":"Success Count"},"error_count":{"type":"integer","title":"Error Count"},"success_rate":{"type":"number","title":"Success Rate"},"avg_duration_ms":{"type":"integer","title":"Avg Duration Ms"}},"type":"object","required":["customer_id","customer_name","total_calls","success_count","error_count","success_rate","avg_duration_ms"],"title":"TopAccountResponse","description":"Schema for top account usage response."},"TopMoverCard":{"properties":{"description":{"type":"string","title":"Description","description":"Full card description"},"player":{"type":"string","title":"Player","description":"Player or character name"},"set":{"type":"string","title":"Set","description":"Card set name"},"number":{"type":"string","title":"Number","description":"Card number in set"},"variant":{"type":"string","title":"Variant","description":"Card variant (e.g., 'Reverse Foil')"},"card_id":{"type":"string","title":"Card Id","description":"Unique card identifier"},"image":{"type":"string","title":"Image","description":"Card image URL"},"category":{"type":"string","title":"Category","description":"Card category"},"category_group":{"type":"string","title":"Category Group","description":"Category group"},"set_type":{"type":"string","title":"Set Type","description":"Set type"},"7 Day Sales":{"type":"integer","title":"7 Day Sales","description":"Sales in last 7 days"},"30 Day Sales":{"type":"integer","title":"30 Day Sales","description":"Sales in last 30 days"},"rookie":{"type":"boolean","title":"Rookie","description":"Whether the card is a rookie card"},"gain":{"type":"number","title":"Gain","description":"Percentage gain"},"prices":{"items":{"$ref":"#/components/schemas/CardPrice"},"type":"array","title":"Prices","description":"Price information at different grades"}},"type":"object","required":["description","player","set","number","variant","card_id","image","category","category_group","set_type","7 Day Sales","30 Day Sales","rookie","gain","prices"],"title":"TopMoverCard","description":"Card information for top movers endpoint."},"TopMoversResponse":{"properties":{"cards":{"items":{"$ref":"#/components/schemas/TopMoverCard"},"type":"array","title":"Cards","description":"List of top moving cards"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of cards returned"},"filtered_count":{"type":"integer","title":"Filtered Count","description":"Number of cards after filtering"},"gain_threshold":{"type":"number","title":"Gain Threshold","description":"Minimum gain percentage used for filtering (default: 500%)"}},"type":"object","required":["cards","total_count","filtered_count","gain_threshold"],"title":"TopMoversResponse","description":"Response model for top movers endpoint.","examples":[{"cards":[{"30 Day Sales":45,"7 Day Sales":12,"card_id":"1587446850514x224832321163624450","category":"Baseball","category_group":"Sports Cards","description":"Shohei Ohtani 2018 Topps Chrome Baseball","gain":650.5,"image":"//s3.amazonaws.com/appforest_uf/example.jpg","number":"150","player":"Shohei Ohtani","prices":[{"grade":"PSA 10","price":"2500"},{"grade":"PSA 9","price":"850"}],"rookie":true,"set":"2018 Topps Chrome Baseball","set_type":"Topps Chrome Baseball","variant":"Refractor"}],"filtered_count":1,"gain_threshold":500.0,"total_count":50}]},"TotalSalesByPlayerRequest":{"properties":{"players":{"items":{"type":"string"},"type":"array","maxItems":25,"minItems":1,"title":"Players","description":"List of player/character names to look up (max 25)"},"days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Days","description":"Number of days to look back (default: 30, max: 365)","default":30}},"type":"object","required":["players"],"title":"TotalSalesByPlayerRequest"},"TotalSalesByPlayerResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/PlayerSalesResult"},"type":"array","title":"Results"},"days":{"type":"integer","title":"Days","description":"Number of days looked back"}},"type":"object","required":["results","days"],"title":"TotalSalesByPlayerResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"servers":[{"url":"https://api.cardhedger.com","description":"Production server"}],"tags":[{"name":"Card Search","description":"Search for cards by text, AI matching, and set browsing"},{"name":"Image Search","description":"Find cards using visual image similarity"},{"name":"Card Details","description":"Get detailed card information and submit card requests"},{"name":"Pricing & Valuations","description":"Certificate lookups, price history, comps, and estimates"},{"name":"Market Data","description":"Top movers, price updates, and market trend analysis"},{"name":"Card Issues","description":"Report and track card data issues (Enterprise only)"},{"name":"Downloads & Exports","description":"Download CSV price exports"}]}