{
 "openapi": "3.0.3",
 "info": {
  "title": "CompsAPI Marketplace",
  "version": "1.8.1",
  "description": "Sold prices, comps and live listings as JSON from eBay and 12 more marketplaces, plus PSA's auction price record, behind one key and one schema. Leave source off for eBay. Set source= to reverb, stockx, goat, grailed, poshmark, mercari, vinted, goldin, fanatics, myslabs, pristine or tcgplayer to read that marketplace, source=psa for PSA Auction Prices Realized, or source=all to merge the 12 marketplaces in one call with each row tagged by its source (all does not include ebay or psa). Every marketplace sold row carries an authenticity object and a flags array and, where the marketplace has them, signals and a market block. exclude=ai_junk filters lots, parts, accessories and replicas with labels from our AI model, and ai=1 returns the label on each row. /v1/active?source= returns live listings on a marketplace. PSA population census and card lookup are at /v1/population and /v1/lookup. One call is one request on every source, from the same monthly quota. Docs: https://compsapi.com/docs and https://compsapi.com/docs/marketplaces.",
  "contact": {
   "name": "CompsAPI support",
   "url": "https://app.compsapi.com/support",
   "email": "keys@compsapi.com"
  },
  "termsOfService": "https://compsapi.com/terms",
  "x-logo": {
   "url": "https://compsapi.com/apple-touch-icon.png",
   "altText": "CompsAPI"
  }
 },
 "servers": [
  {
   "url": "https://api.compsapi.com"
  }
 ],
 "security": [
  {
   "apiKey": []
  },
  {
   "bearer": []
  }
 ],
 "components": {
  "securitySchemes": {
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   },
   "bearer": {
    "type": "http",
    "scheme": "bearer"
   }
  },
  "parameters": {
   "q": {
    "name": "q",
    "in": "query",
    "required": true,
    "schema": {
     "type": "string",
     "maxLength": 300
    },
    "description": "Search terms, max 300 characters. Every word must appear in the title, on eBay and on every marketplace source."
   },
   "days": {
    "name": "days",
    "in": "query",
    "schema": {
     "type": "integer",
     "minimum": 1,
     "maximum": 7000,
     "default": 90
    },
    "description": "How far back to search, in days. source=ebay: 1 to 1095 (3 years). Marketplace sources: 1 to 7000, and the window never starts earlier than 2008-01-01. Where each source's history starts is in the marketplace docs."
   },
   "size": {
    "name": "size",
    "in": "query",
    "schema": {
     "type": "integer",
     "minimum": 10,
     "maximum": 240,
     "default": 200
    },
    "description": "Results per page."
   },
   "condition": {
    "name": "condition",
    "in": "query",
    "schema": {
     "type": "string"
    },
    "description": "source=ebay: new, open_box, refurbished, used or parts. Marketplace sources: an exact match, ignoring case, on that marketplace's own condition label (Reverb 'Excellent', Grailed 'gently_used', Poshmark 'like_new', Fanatics 'PSA 10', GOAT 'new', 'used' or 'new_with_defects', TCGplayer 'Near Mint'), the same words on sold and live calls; read stats.by_condition to see the labels for a search. Comma separate to combine."
   },
   "best_offer": {
    "name": "best_offer",
    "in": "query",
    "schema": {
     "type": "string",
     "enum": [
      "1",
      "only",
      "verify"
     ]
    },
    "description": "eBay only: ignored when source is a marketplace. 1 adds the best_offer flag with real accepted prices; only returns accepted offers exclusively; verify also reads the public sold page and adds best_offer_confidence, asking_price and asking_gap_pct, because eBay's own accepted offer filter misses some negotiated sales."
   },
   "cards": {
    "name": "cards",
    "in": "query",
    "schema": {
     "type": "string",
     "enum": [
      "1"
     ]
    },
    "description": "eBay only: ignored when source is a marketplace. Adds the card object to every item without filtering."
   },
   "grader": {
    "name": "grader",
    "in": "query",
    "schema": {
     "type": "string"
    },
    "description": "eBay only: ignored when source is a marketplace. PSA, BGS, CGC, SGC, TAG, ACE and others. Comma separate to combine."
   },
   "grade": {
    "name": "grade",
    "in": "query",
    "schema": {
     "type": "string"
    },
    "description": "eBay only: ignored when source is a marketplace. Grade as text, e.g. 10 or 9.5. Comma separate to combine."
   },
   "graded": {
    "name": "graded",
    "in": "query",
    "schema": {
     "type": "string",
     "enum": [
      "true",
      "false"
     ]
    },
    "description": "eBay only: ignored when source is a marketplace. Only slabs, or only raw cards."
   },
   "lang": {
    "name": "lang",
    "in": "query",
    "schema": {
     "type": "string"
    },
    "description": "eBay only: ignored when source is a marketplace. en, ja, zh, ko, de, fr, it, es, pt. Comma separate to combine."
   },
   "first_edition": {
    "name": "first_edition",
    "in": "query",
    "schema": {
     "type": "string",
     "enum": [
      "true",
      "false"
     ]
    },
    "description": "eBay only: ignored when source is a marketplace. "
   },
   "exclude": {
    "name": "exclude",
    "in": "query",
    "schema": {
     "type": "string"
    },
    "description": "Comma list of what to drop. junk = the title rules set (lot, mystery, sealed, accessory, replica, keyword_stuffing, not_graded_claim, title_missing); single flags such as lot,sealed also work; none keeps everything. ai_junk (eBay and marketplace sources) drops rows our AI model labels as not a single normal item: lots, mystery boxes, parts, accessories, empty boxes, replicas, digital items and raw cards sold as grading candidates. parts, box_only and digital (marketplace sources) drop only the rows the model labels with that kind, and accessory also drops rows the model labels accessory. Combine as junk,ai_junk. An unknown word drops nothing. /v1/comps defaults to junk; passing exclude replaces that default. On source=ebay, /v1/comps with exclude=ai_junk keeps the title rules set on as well (it is applied as junk,ai_junk)."
   },
   "stats": {
    "name": "stats",
    "in": "query",
    "schema": {
     "type": "string",
     "enum": [
      "1"
     ]
    },
    "description": "Adds price stats for the filtered results (always on for /v1/comps). On marketplace sources stats also carry confidence, price_trend and by_condition."
   },
   "start": {
    "name": "start",
    "in": "query",
    "schema": {
     "type": "string",
     "format": "date",
     "example": "2024-12-01"
    },
    "description": "First day of an absolute window, written YYYY-MM-DD. Use start and end to ask for a fixed historical period instead of a lookback from today, for example start=2024-12-01&end=2025-12-01. Inclusive. Given on its own, the window runs to now. A start more than 1095 days ago is refused; on a plan with less history the start is pulled forward to that plan's limit and plan_limit says so. Slicing a long period into several short windows is faster and more reliable than walking deep pages. Marketplace sources (any source other than ebay) accept a start back to their earliest stored sale, 2008-01-01 at most. On marketplace sources start can be any date back to 2008-01-01."
   },
   "end": {
    "name": "end",
    "in": "query",
    "schema": {
     "type": "string",
     "format": "date",
     "example": "2025-12-01"
    },
    "description": "Last day of an absolute window, written YYYY-MM-DD. Inclusive, so the whole of that day counts, and it never runs past today. Given on its own, the window starts days before it. The answer carries window with the period actually served."
   },
   "require": {
    "name": "require",
    "in": "query",
    "schema": {
     "type": "string"
    },
    "description": "eBay only: ignored when source is a marketplace. Keep only sales whose title holds every one of these words or phrases, comma separated, for example require=lebron james or require=lebron james,red disco. Matching ignores case and punctuation and lands on whole words, so 2017 matches a 2017-18 title and ron jam matches nothing. Up to 6 terms. This is how you search broadly and then insist on the one thing that identifies your item. It can only remove rows, never find new ones, so the answer carries title_filter with the count before it ran and how many it removed. It runs on the page already retrieved, so on a broad query widen size or walk pages to see more."
   },
   "print_run": {
    "name": "print_run",
    "in": "query",
    "schema": {
     "type": "string",
     "example": "125"
    },
    "description": "eBay only: ignored when source is a marketplace. The serial number a card is limited to, read from the title. A number keeps only that print run, for example print_run=125 for a /125 parallel. numbered keeps every serial numbered card. any filters nothing and just labels the rows. All three add print_run to every item. #098/125 reads as 125 and not as 98, a bare /85 reads as 85, and a season like 2025/26, a card number like #100, a 100 card lot and a date are all left alone. A print run is not an identity: a /125 parallel of the same player exists in several seasons at very different prices, so keep the year in q and use this to separate parallels within it. Reported in title_filter the same way as require."
   },
   "source": {
    "name": "source",
    "in": "query",
    "schema": {
     "type": "string",
     "enum": [
      "ebay",
      "reverb",
      "stockx",
      "goat",
      "grailed",
      "poshmark",
      "mercari",
      "vinted",
      "goldin",
      "fanatics",
      "myslabs",
      "pristine",
      "tcgplayer",
      "psa",
      "all"
     ],
     "default": "ebay"
    },
    "description": "Which source to read. Defaults to ebay. One of: reverb, stockx, goat, grailed, poshmark, mercari, vinted, goldin, fanatics, myslabs, pristine, tcgplayer (marketplaces), psa (PSA Auction Prices Realized, a record of sales made on other venues), or all. all merges the 12 marketplaces in one call, newest sale first, and each row carries its own source. all does not include ebay rows and does not include psa, because PSA's record repeats sales from eBay, Fanatics Collect and Goldin. The eBay only parameters (best_offer, cards, grader, grade, graded, lang, first_edition, require, print_run, site, category) are ignored on marketplace sources. One call is one request on every source."
   },
   "ai": {
    "name": "ai",
    "in": "query",
    "schema": {
     "type": "string",
     "enum": [
      "1"
     ]
    },
    "description": "eBay and marketplace sources. 1 adds the ai object to every returned row: what our AI model says was sold (kind), whether it counts as junk, its confidence, a category and the release date of the model. Opt in, available on every plan. Use exclude=ai_junk to filter on it."
   }
  },
  "schemas": {
   "Card": {
    "type": "object",
    "properties": {
     "graded": {
      "type": "boolean",
      "nullable": true
     },
     "grader": {
      "type": "string",
      "nullable": true
     },
     "grade": {
      "type": "string",
      "nullable": true
     },
     "grade_label": {
      "type": "string",
      "nullable": true
     },
     "card_number": {
      "type": "string",
      "nullable": true
     },
     "year": {
      "type": "integer",
      "nullable": true
     },
     "language": {
      "type": "string",
      "nullable": true
     },
     "first_edition": {
      "type": "boolean",
      "nullable": true
     },
     "flags": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "psa_spec_id": {
      "type": "integer",
      "description": "PSA's canonical card id (source=psa rows). Pass to /v1/population?spec=."
     }
    }
   },
   "Item": {
    "type": "object",
    "properties": {
     "item_id": {
      "type": "string"
     },
     "title": {
      "type": "string"
     },
     "last_sold": {
      "type": "string",
      "format": "date-time",
      "description": "When the sale happened, UTC, YYYY-MM-DDTHH:MM:SSZ."
     },
     "price": {
      "type": "number",
      "description": "Price actually paid, USD. Non-USD sales are converted at the ECB reference rate on the sale date (see native_price). null when the source gives no reliable sale price or no rate exists for the currency.",
      "nullable": true
     },
     "units_sold": {
      "type": "integer"
     },
     "total_sales": {
      "type": "number"
     },
     "format": {
      "type": "string",
      "enum": [
       "FIXED_PRICE",
       "AUCTION"
      ]
     },
     "bids": {
      "type": "integer"
     },
     "us_sale": {
      "type": "boolean",
      "description": "true when the sale was made on eBay US, false when it was made on another eBay site. The default search merges eBay US with international coverage, so this separates them. Which other site a false row came from is not reported, because eBay does not expose it per item. With site pinned, every row is true or every row is false."
     },
     "native_price": {
      "type": "number",
      "nullable": true,
      "description": "The amount in the currency the sale actually happened in. price is always USD (non-USD sales are converted at the ECB reference rate for the sale date, or the previous published rate on weekends and holidays); this is the untouched figure. Always present for a non-USD sale; for USD sales only with native_price=1. null for a USD sale without native_price=1."
     },
     "native_currency": {
      "type": "string",
      "nullable": true,
      "description": "ISO 4217 code for native_price, for example GBP, EUR, CAD. Always present for a non-USD sale; for USD sales only with native_price=1."
     },
     "best_offer": {
      "type": "boolean",
      "nullable": true,
      "description": "Only present with the best_offer parameter. true means the sale was identified as an accepted offer; false means it was not identified as one, which is not the same as a full price sale."
     },
     "condition": {
      "type": "string",
      "description": "source=ebay: only present with a single condition value. Marketplace sources: the marketplace's own condition label, or null."
     },
     "shipping_cost": {
      "type": "number",
      "nullable": true
     },
     "free_shipping_pct": {
      "type": "number"
     },
     "url": {
      "type": "string"
     },
     "image": {
      "type": "string"
     },
     "card": {
      "$ref": "#/components/schemas/Card"
     },
     "best_offer_confidence": {
      "type": "string",
      "enum": [
       "confirmed",
       "likely",
       "unlikely",
       "unknown"
      ],
      "description": "Only with best_offer=verify. confirmed: eBay identifies the sale as an accepted offer. likely: the listing accepted offers and the sale closed materially below the asking price. unlikely: neither holds. unknown: the sale was not on the public pages we read, or another marketplace was pinned, so no comparison was possible."
     },
     "asking_price": {
      "type": "number",
      "nullable": true,
      "description": "Only with best_offer=verify. The price eBay's public sold page displays for this listing."
     },
     "asking_gap_pct": {
      "type": "number",
      "nullable": true,
      "description": "Only with best_offer=verify. How far the asking price sits above what the sale closed at, as a percentage of the amount paid. Negative when the public page reads low."
     },
     "source": {
      "type": "string",
      "description": "Which source this sale came from. Always present."
     },
     "authenticity": {
      "$ref": "#/components/schemas/Authenticity"
     },
     "raw": {
      "type": "object",
      "description": "Marketplace sources: everything the marketplace gives that is not a first class field, under the marketplace's own key names (e.g. brand, size, lot, watchers)."
     },
     "flags": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Flag"
      }
     },
     "signals": {
      "$ref": "#/components/schemas/Signals"
     },
     "market": {
      "$ref": "#/components/schemas/Market"
     },
     "ai": {
      "$ref": "#/components/schemas/AiLabel"
     }
    }
   },
   "Stats": {
    "type": "object",
    "properties": {
     "count": {
      "type": "integer"
     },
     "used_for_stats": {
      "type": "integer"
     },
     "median": {
      "type": "number"
     },
     "mean": {
      "type": "number"
     },
     "p25": {
      "type": "number"
     },
     "p75": {
      "type": "number"
     },
     "min": {
      "type": "number"
     },
     "max": {
      "type": "number"
     },
     "outliers_removed": {
      "type": "integer",
      "description": "Rows left out as price outliers. source=ebay and marketplace sources use their own outlier rule; see the docs."
     },
     "newest_sale": {
      "type": "string",
      "format": "date-time"
     },
     "oldest_sale": {
      "type": "string",
      "format": "date-time"
     },
     "junk_removed": {
      "type": "integer",
      "description": "Rows left out of the stats for a title flag. On /v1/comps the default exclude=junk removes them before stats run, so this is 0 there and the removed count is count_before_filters minus count."
     },
     "confidence": {
      "type": "object",
      "description": "Marketplace sources. How far to trust the median: score = min(1, n/30) x (1 - relative_iqr); label high from 0.66, medium from 0.33.",
      "properties": {
       "score": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
       },
       "label": {
        "type": "string",
        "enum": [
         "low",
         "medium",
         "high"
        ]
       },
       "n": {
        "type": "integer"
       },
       "relative_iqr": {
        "type": "number"
       }
      }
     },
     "price_trend": {
      "type": "object",
      "nullable": true,
      "description": "Marketplace sources. Median of the recent half of the sales used against the older half, split by count after sorting by sale date. Needs 8 or more dated sales, else null.",
      "properties": {
       "direction": {
        "type": "string",
        "enum": [
         "up",
         "down",
         "flat"
        ]
       },
       "pct_change": {
        "type": "number"
       },
       "recent_median": {
        "type": "number"
       },
       "prior_median": {
        "type": "number"
       },
       "n": {
        "type": "integer"
       }
      }
     },
     "by_condition": {
      "type": "object",
      "nullable": true,
      "description": "Up to 12 condition buckets by volume, each with count and median.",
      "additionalProperties": {
       "type": "object",
       "properties": {
        "count": {
         "type": "integer"
        },
        "median": {
         "type": "number"
        }
       }
      }
     }
    }
   },
   "SoldResponse": {
    "type": "object",
    "properties": {
     "ok": {
      "type": "boolean"
     },
     "query": {
      "type": "string"
     },
     "page": {
      "type": "integer"
     },
     "ms": {
      "type": "integer"
     },
     "count": {
      "type": "integer"
     },
     "no_results": {
      "type": "boolean"
     },
     "next_page": {
      "type": "boolean"
     },
     "days": {
      "type": "integer"
     },
     "size": {
      "type": "integer"
     },
     "cached": {
      "type": "boolean"
     },
     "cached_age_s": {
      "type": "integer"
     },
     "source": {
      "type": "string"
     },
     "filters": {
      "type": "object"
     },
     "count_before_filters": {
      "type": "integer"
     },
     "stats": {
      "$ref": "#/components/schemas/Stats"
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Item"
      }
     },
     "window": {
      "type": "object",
      "description": "The sold-date window actually served (start, end)."
     },
     "meta": {
      "type": "object",
      "nullable": true,
      "description": "Marketplace sources. What happened on this request, keyed by source: topup (the check for sales newer than what is held: status ok, skipped, timeout or error; reason window_closed, no_query, fresh, no_match, busy or not_supported; store_lag_s, new), gapfill (older parts of the window filled on this call) and ai (the AI filter report). Informational; never needed to read items.",
      "properties": {
       "topup": {
        "type": "object",
        "additionalProperties": {
         "type": "object"
        }
       },
       "gapfill": {
        "type": "object",
        "additionalProperties": {
         "type": "object"
        }
       },
       "ai": {
        "type": "object",
        "description": "Present with ai=1 or exclude=ai_junk.",
        "properties": {
         "status": {
          "type": "string",
          "description": "ok, or why labels were not available. Rows are kept when labels are unavailable, and when the filter is busy the rows come back unfiltered."
         },
         "rows": {
          "type": "integer",
          "description": "Rows looked at."
         },
         "unlabelled": {
          "type": "integer",
          "description": "Rows with no label (kept)."
         },
         "dropped": {
          "type": "integer",
          "description": "Rows removed by exclude=ai_junk."
         },
         "ms": {
          "type": "integer"
         }
        }
       }
      }
     },
     "ignored_params": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Parameters that were sent and do nothing on this source or endpoint. Absent when none."
     }
    }
   },
   "Error": {
    "type": "object",
    "properties": {
     "ok": {
      "type": "boolean",
      "example": false
     },
     "error": {
      "type": "string"
     }
    }
   },
   "ActiveItem": {
    "type": "object",
    "properties": {
     "item_id": {
      "type": "string"
     },
     "title": {
      "type": "string"
     },
     "url": {
      "type": "string"
     },
     "price": {
      "type": "number",
      "nullable": true,
      "description": "Price now in USD; the current bid on an auction."
     },
     "price_max": {
      "type": "number",
      "nullable": true,
      "description": "Top of the range on a listing that shows a price range, else null."
     },
     "currency": {
      "type": "string",
      "example": "USD"
     },
     "shipping": {
      "type": "number",
      "nullable": true,
      "description": "Cost to a US address; 0 when free, null when no price is shown."
     },
     "shipping_text": {
      "type": "string",
      "nullable": true
     },
     "format": {
      "type": "string",
      "enum": [
       "BIN",
       "AUCTION"
      ]
     },
     "bids": {
      "type": "integer",
      "nullable": true
     },
     "ends_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "buy_it_now_available": {
      "type": "boolean"
     },
     "best_offer_enabled": {
      "type": "boolean"
     },
     "quantity_available": {
      "type": "integer",
      "nullable": true
     },
     "condition": {
      "type": "string",
      "nullable": true
     },
     "seller": {
      "type": "string",
      "nullable": true
     },
     "seller_feedback": {
      "type": "integer",
      "nullable": true
     },
     "seller_positive_pct": {
      "type": "number",
      "nullable": true
     },
     "location": {
      "type": "string",
      "nullable": true
     },
     "image": {
      "type": "string",
      "nullable": true
     },
     "source": {
      "type": "string",
      "description": "Which source this live listing came from."
     },
     "authenticity": {
      "$ref": "#/components/schemas/Authenticity"
     },
     "raw": {
      "type": "object",
      "description": "Marketplace sources: listing fields the marketplace gives beyond the common ones, under its own key names (for example listed_date, original_list_price, brand and size on poshmark). The per source docs list them."
     }
    }
   },
   "ActiveResponse": {
    "type": "object",
    "properties": {
     "ok": {
      "type": "boolean"
     },
     "query": {
      "type": "string"
     },
     "page": {
      "type": "integer"
     },
     "ms": {
      "type": "integer"
     },
     "sort": {
      "type": "string"
     },
     "count": {
      "type": "integer"
     },
     "next_page": {
      "type": "boolean"
     },
     "source": {
      "type": "string"
     },
     "total_active": {
      "type": "integer",
      "description": "source=ebay: how many live listings eBay has for the search. Marketplace sources: the listings read for this answer."
     },
     "total_active_is_minimum": {
      "type": "boolean",
      "description": "source=ebay: true when eBay gives only a rounded figure, e.g. 12,000+. Marketplace sources: always true, because one search page is read per marketplace."
     },
     "cached": {
      "type": "boolean"
     },
     "cached_age_s": {
      "type": "integer"
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/ActiveItem"
      }
     },
     "live_status": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      },
      "description": "Marketplace sources: an object keyed by marketplace, one word each: ok, ok_cached, no_match (the keyword matched no product, on tcgplayer), busy (retry), timeout, error or not_available.",
      "example": {
       "reverb": "ok",
       "stockx": "ok_cached",
       "tcgplayer": "no_match",
       "goat": "error"
      }
     },
     "sources_failed": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Marketplace sources: the marketplaces that answered timeout, error or busy, sorted; [] when all answered. A marketplace listed here was not reached, which is different from having no listings. Retry it before reading a zero count as nothing for sale.",
      "example": []
     }
    }
   },
   "Authenticity": {
    "type": "object",
    "description": "How the item's authenticity is known. PASSTHROUGH ONLY: we report what the source states, never an inferred claim. basis is seller_declared unless the source supplies more.",
    "properties": {
     "basis": {
      "type": "string",
      "enum": [
       "marketplace_verified",
       "graded",
       "third_party_coa",
       "seller_declared"
      ],
      "description": "marketplace_verified: the marketplace authenticates every item in hand before payout (StockX). graded: the item is a graded slab; grader + grade come from the source's own grading fields (Fanatics, Goldin detail) or are stated in the listing title (Goldin, Fanatics, MySlabs, Pristine), in which case verified is false and cert_number is null. third_party_coa: the listing names an authenticator's COA/LOA/hologram (JSA, PSA/DNA, Beckett, Fanatics Authentic, Steiner, MLB Authenticated...). seller_declared: anything else (default)."
     },
     "verified": {
      "type": "boolean",
      "description": "true only when the source itself backs the claim: the marketplace's own in-hand verification (StockX), or a grade/authentication with a cert number supplied by the source. A grade or COA stated only in the listing text is false."
     },
     "grader": {
      "type": "string",
      "nullable": true,
      "description": "The grading company or authenticator, e.g. PSA, BGS, SGC, CGC, JSA, Beckett. null for seller_declared."
     },
     "grade": {
      "type": "string",
      "nullable": true,
      "description": "The grade as stated by the source, e.g. 10, 9.5, Authentic. Only for basis graded."
     },
     "cert_number": {
      "type": "string",
      "nullable": true,
      "description": "The grading/authentication cert number, when the source exposes it."
     },
     "coa_note": {
      "type": "string",
      "description": "Present when the source carries COA/LOA text (Pristine): the source's own wording, first 200 characters."
     },
     "cert_note": {
      "type": "string",
      "description": "Present when a cert exists but the source does not expose it publicly."
     }
    }
   },
   "Flag": {
    "type": "string",
    "enum": [
     "lot",
     "mystery",
     "sealed",
     "accessory",
     "replica",
     "not_graded_claim",
     "keyword_stuffing",
     "title_missing",
     "outlier"
    ],
    "description": "Why a row may not be a clean comp. Title rule flags are set on every marketplace row; outlier is added when stats run, on rows outside 1.5x IQR of the matched set. exclude=junk drops rows with a title flag. The rules were written for raw trading cards, so on slabs, gear and clothing prefer exclude=ai_junk."
   },
   "Signals": {
    "type": "object",
    "nullable": true,
    "description": "Days on market, list versus sold discount, listing date and seller standing under the same names on every marketplace, from the marketplace's own dates and prices. A field the marketplace does not have is omitted, and the object is omitted on sources with none (stockx, goat, tcgplayer).",
    "properties": {
     "days_on_market": {
      "type": "number"
     },
     "discount_pct": {
      "type": "number",
      "description": "List price versus sold price, percent."
     },
     "listed_date": {
      "type": "string",
      "format": "date-time"
     },
     "seller": {
      "type": "object",
      "properties": {
       "username": {
        "type": "string"
       },
       "rating": {
        "type": "number"
       },
       "rating_count": {
        "type": "integer"
       },
       "items_sold": {
        "type": "integer"
       },
       "verified": {
        "type": "boolean"
       }
      }
     }
    }
   },
   "Market": {
    "type": "object",
    "nullable": true,
    "description": "StockX only: the order book and price dynamics recorded with the sale. A snapshot stored with the row; it is not the book at the instant of the sale and not the book now.",
    "properties": {
     "lowest_ask": {
      "type": "number"
     },
     "highest_bid": {
      "type": "number"
     },
     "num_asks": {
      "type": "number"
     },
     "num_bids": {
      "type": "number"
     },
     "price_premium": {
      "type": "number"
     },
     "volatility": {
      "type": "number"
     },
     "sell_through_days": {
      "type": "number"
     },
     "sales_72h": {
      "type": "number"
     },
     "sales_annual": {
      "type": "number"
     }
    }
   },
   "LookupResult": {
    "type": "object",
    "properties": {
     "spec_id": {
      "type": "integer"
     },
     "subject": {
      "type": "string"
     },
     "year": {
      "type": "string"
     },
     "set": {
      "type": "string"
     },
     "number": {
      "type": "string"
     },
     "variety": {
      "type": "string",
      "nullable": true
     },
     "category": {
      "type": "string"
     },
     "description": {
      "type": "string"
     },
     "url": {
      "type": "string"
     }
    }
   },
   "LookupResponse": {
    "type": "object",
    "properties": {
     "ok": {
      "type": "boolean"
     },
     "query": {
      "type": "string"
     },
     "count": {
      "type": "integer"
     },
     "source": {
      "type": "string",
      "enum": [
       "psa"
      ]
     },
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/LookupResult"
      }
     }
    }
   },
   "PopulationResponse": {
    "type": "object",
    "properties": {
     "ok": {
      "type": "boolean"
     },
     "spec_id": {
      "type": "string"
     },
     "source": {
      "type": "string",
      "enum": [
       "psa"
      ]
     },
     "gem_rate": {
      "type": "number",
      "description": "Share of graded copies at PSA 10."
     },
     "total_graded": {
      "type": "integer"
     },
     "grades": {
      "type": "object",
      "description": "Keyed by grade (authentic, 1, 1.5 ... 10).",
      "additionalProperties": {
       "type": "object",
       "properties": {
        "graded": {
         "type": "integer"
        },
        "qualifier": {
         "type": "integer"
        },
        "total": {
         "type": "integer"
        }
       }
      }
     },
     "resolved_from": {
      "type": "object",
      "description": "Present when called with q=: the card q resolved to.",
      "properties": {
       "q": {
        "type": "string"
       },
       "card": {
        "$ref": "#/components/schemas/LookupResult"
       }
      }
     },
     "no_results": {
      "type": "boolean"
     },
     "has_dual_graded": {
      "type": "boolean",
      "description": "True when PSA also reports dual grade counts for this card."
     },
     "psa_spec_url": {
      "type": "string",
      "description": "PSA's page for this card."
     }
    }
   },
   "AiLabel": {
    "type": "object",
    "nullable": true,
    "description": "Our AI model's label for the row. Present only with ai=1 on eBay and marketplace sources; null when the row has no label. Rows are never deleted on the strength of it: it only labels, and exclude=ai_junk filters on request.",
    "properties": {
     "kind": {
      "type": "string",
      "enum": [
       "item",
       "lot",
       "mystery",
       "parts",
       "accessory",
       "box_only",
       "replica",
       "digital",
       "other"
      ],
      "description": "What was sold."
     },
     "junk": {
      "type": "boolean",
      "description": "true when kind is not item, or the row is a raw card sold as a grading candidate. What exclude=ai_junk filters on."
     },
     "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "How sure the model is of the item or not item call."
     },
     "category": {
      "type": "string",
      "description": "Broad product category, e.g. music_gear."
     },
     "model": {
      "type": "string",
      "description": "Release date of the model that made the call, e.g. 2026-11-17."
     }
    }
   }
  },
  "responses": {
   "Unauthorized": {
    "description": "Missing or invalid API key.",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   },
   "BadRequest": {
    "description": "Missing or invalid parameter.",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   },
   "RateLimited": {
    "description": "rate_limited (per minute rate passed; see retry_after and the Retry-After header) or quota_reached (monthly quota used).",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   },
   "NotAvailable": {
    "description": "not_available: live listings were asked for on a source that has none (for example psa).",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   },
   "Forbidden": {
    "description": "Key expired.",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   },
   "NotFound": {
    "description": "Unknown path.",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   },
   "ServerError": {
    "description": "A problem on our side. Retry after a second or two.",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   }
  }
 },
 "paths": {
  "/v1/sold": {
   "get": {
    "summary": "Sold listings for a search on eBay or a marketplace, newest first",
    "parameters": [
     {
      "$ref": "#/components/parameters/source"
     },
     {
      "$ref": "#/components/parameters/q"
     },
     {
      "$ref": "#/components/parameters/days"
     },
     {
      "$ref": "#/components/parameters/start"
     },
     {
      "$ref": "#/components/parameters/end"
     },
     {
      "$ref": "#/components/parameters/size"
     },
     {
      "name": "page",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 200,
       "default": 1
      },
      "description": "Page number. 1 to 10 on Free, 1 to 25 on Starter, 1 to 200 on Growth and above. Every plan reads the full 1,095 days, so a start and end window reaches any period without deep paging. Walk pages in order: each page is served from where the previous one stopped, so a deep page asked for on its own has to rebuild the whole walk and can time out. A walk stays resumable for 4 hours. The plan page limits apply to source=ebay."
     },
     {
      "$ref": "#/components/parameters/condition"
     },
     {
      "$ref": "#/components/parameters/best_offer"
     },
     {
      "$ref": "#/components/parameters/cards"
     },
     {
      "$ref": "#/components/parameters/grader"
     },
     {
      "$ref": "#/components/parameters/grade"
     },
     {
      "$ref": "#/components/parameters/graded"
     },
     {
      "$ref": "#/components/parameters/lang"
     },
     {
      "$ref": "#/components/parameters/first_edition"
     },
     {
      "$ref": "#/components/parameters/exclude"
     },
     {
      "$ref": "#/components/parameters/ai"
     },
     {
      "$ref": "#/components/parameters/require"
     },
     {
      "$ref": "#/components/parameters/print_run"
     },
     {
      "$ref": "#/components/parameters/stats"
     },
     {
      "name": "site",
      "in": "query",
      "description": "eBay only: ignored when source is a marketplace. Pin one eBay marketplace, returning only sales made on that site. Omit it for the default, which is eBay US plus international coverage merged. A pin means that site alone, not listings a buyer there could see. All prices are USD whichever you pick: eBay converts before we receive them, so a pin changes which sales you get, never the currency.",
      "schema": {
       "type": "string",
       "enum": [
        "US",
        "UK",
        "DE",
        "FR",
        "IT",
        "ES",
        "CA",
        "AU"
       ]
      }
     },
     {
      "name": "category",
      "in": "query",
      "description": "eBay only: ignored when source is a marketplace. eBay category id(s), comma separated, e.g. 31387 for wristwatches.",
      "schema": {
       "type": "string",
       "pattern": "^\\d+(,\\d+)*$"
      }
     },
     {
      "name": "min_price",
      "in": "query",
      "description": "Keep only sales at or above this sold price in USD.",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     },
     {
      "name": "max_price",
      "in": "query",
      "description": "Keep only sales at or below this sold price in USD.",
      "schema": {
       "type": "number",
       "minimum": 0
      }
     },
     {
      "name": "native_price",
      "in": "query",
      "description": "1 adds native_price and native_currency: the amount in the currency the buyer actually paid. source=ebay: eBay US sales are already USD; each non US sale costs one extra read, so it is capped per request and native_price_info reports coverage. Marketplace sources: non USD sales always carry the native fields, and 1 fills them on USD sales too.",
      "schema": {
       "type": "string",
       "enum": [
        "0",
        "1"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Sold listings.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SoldResponse"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "500": {
      "$ref": "#/components/responses/ServerError"
     }
    },
    "description": "source=ebay (default) is the eBay sold search. A marketplace source returns that marketplace's sold history with the same item shape plus source, authenticity, flags, signals, market and raw. source=all merges the 12 marketplaces. One request per call."
   }
  },
  "/v1/comps": {
   "get": {
    "summary": "Price stats plus the 10 newest matching sales",
    "description": "Stats over every matching sale in the window plus the 10 newest matching sales. The title rules filter (exclude=junk) is on by default; add ai_junk for the AI junk filter on eBay and marketplace sources. On source=ebay the card layer is always parsed. Not pageable.",
    "parameters": [
     {
      "$ref": "#/components/parameters/source"
     },
     {
      "$ref": "#/components/parameters/q"
     },
     {
      "$ref": "#/components/parameters/days"
     },
     {
      "$ref": "#/components/parameters/start"
     },
     {
      "$ref": "#/components/parameters/end"
     },
     {
      "$ref": "#/components/parameters/condition"
     },
     {
      "$ref": "#/components/parameters/best_offer"
     },
     {
      "$ref": "#/components/parameters/grader"
     },
     {
      "$ref": "#/components/parameters/grade"
     },
     {
      "$ref": "#/components/parameters/graded"
     },
     {
      "$ref": "#/components/parameters/lang"
     },
     {
      "$ref": "#/components/parameters/first_edition"
     },
     {
      "$ref": "#/components/parameters/exclude"
     },
     {
      "$ref": "#/components/parameters/ai"
     },
     {
      "$ref": "#/components/parameters/require"
     },
     {
      "$ref": "#/components/parameters/print_run"
     },
     {
      "name": "min_price",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      },
      "description": "Only sales at or above this price, in USD."
     },
     {
      "name": "max_price",
      "in": "query",
      "schema": {
       "type": "number",
       "minimum": 0
      },
      "description": "Only sales at or below this price, in USD."
     },
     {
      "name": "native_price",
      "in": "query",
      "description": "1 adds native_price and native_currency: the amount in the currency the buyer actually paid. source=ebay: eBay US sales are already USD; each non US sale costs one extra read, so it is capped per request and native_price_info reports coverage. Marketplace sources: non USD sales always carry the native fields, and 1 fills them on USD sales too.",
      "schema": {
       "type": "string",
       "enum": [
        "0",
        "1"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Stats and newest sales.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SoldResponse"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "500": {
      "$ref": "#/components/responses/ServerError"
     }
    }
   }
  },
  "/v1/active": {
   "get": {
    "summary": "Live listings for a search on eBay or a marketplace",
    "description": "What is for sale right now. source=ebay (default) is the eBay live search. A marketplace source returns that marketplace's current listings in the same item shape, read at the moment you call, with marketplace extras under raw. All 12 marketplaces have live listings. source=all searches the 12 in parallel and interleaves the results so the first page shows every marketplace. Each marketplace answer is one search, so total_active_is_minimum is true, and live_status reports per source what happened. min_price, max_price, condition and format apply to the page of listings read for the call, not to the whole marketplace, so a narrow price range can return 0 rows while matching listings exist. GET /v1/sources lists the sources with live listings under live_listings; psa has none and returns 501. One call is one request. Sold and live are separate searches.\n\nMarketplaces with live listings:\n- `fanatics`: open Weekly/Premier auction lots (price = current bid, bids, ends_at) and Fixed buy-now listings (price = asking) in one search; graded rows carry grader and cert (verified); raw: current_bid, starting_bid, asking_price, allow_offers, watchers, auction name/lot, guide_value\n- `goat`: one row per product, price = lowest new ask (else cheapest ask); raw: lowest ask per condition (new / new with defects / used), per-size asks with last sold, retail_price, release_date\n- `goldin`: open auction lots (price = current bid, or the opening bid when there are no bids; bids, ends_at); raw: min_bid, reserve_met, buyer_premium_pct, price_incl_bp, auction id/type, lot_number; grade is as stated in the title (not cert-verified)\n- `grailed`: fixed-price listings with shipping; raw: listed/bumped dates, price_drops, designers, size, color, seller rating / sold count / trusted flag, photo_count\n- `mercari`: fixed-price listings; raw: listed_date, original_list_price, discount_pct, brand/size/category ids, likes; seller is Mercari's numeric seller id\n- `myslabs`: graded slabs for sale (price = asking, offers accepted); grader and grade, cert when the seller lists it; raw: slab_id, grade, grader\n- `poshmark`: fixed-price listings (price = asking); every listing accepts offers; raw: listed_date, original_list_price, discount_pct, brand, size, category, like_count\n- `pristine`: open auction lots (price = current bid, else the starting price; bids, ends_at); the COA / LOA certifier is under authenticity; raw: reserve_met, buyer_premium, start_price, watchers, views\n- `reverb`: listings (format AUCTION for Reverb auctions, else BIN) with shipping; raw: make, model, year, finish, category, shop, preferred_seller, local pickup\n- `stockx`: one row per product, price = lowest ask; raw: the order book (lowest_ask, highest_bid, num_asks, num_bids), last_sale, sales_72h, price_premium, volatility, style_id\n- `tcgplayer`: per-seller listings for the best-matching product (price and shipping, condition, printing, quantity, seller); raw: product_id/name, set, market_price, total_listings, seller flags\n- `vinted`: fixed-price listings from the US catalogue (USD); raw: brand, size (EU sizing where the seller used it), total_with_buyer_fee, buyer_protection_fee, favourites, views\n\n`source=psa` answers 501: PSA Auction Prices Realized is sold-only: there is no live surface.\n\n`condition` is the marketplace's own condition label (Reverb 'Excellent', TCGplayer 'Near Mint', graded slabs carry grader/grade under `authenticity`).\n\nSort: best_match (the marketplace's own relevance), newly_listed, price_asc, price_desc, ending_soonest (auction marketplaces). A marketplace that cannot sort that way returns its relevance order.",
    "parameters": [
     {
      "$ref": "#/components/parameters/source"
     },
     {
      "name": "q",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "maxLength": 300
      },
      "description": "Search terms, max 300 characters. Live results follow each marketplace's own search ranking, so a row can lack one of your words."
     },
     {
      "name": "sort",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "best_match",
        "newly_listed",
        "ending_soonest",
        "price_asc",
        "price_desc"
       ],
       "default": "best_match"
      },
      "description": "best_match (default), newly_listed, price_asc or price_desc on every source; ending_soonest on eBay and the auction sources (goldin, fanatics, pristine). A sort a marketplace does not have falls back to its own order. An unknown value is served as best_match and sort is listed in ignored_params."
     },
     {
      "name": "per_page",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 10,
       "maximum": 200,
       "default": 200
      }
     },
     {
      "name": "page",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "default": 1
      }
     },
     {
      "name": "min_price",
      "in": "query",
      "schema": {
       "type": "number"
      },
      "description": "Price range in USD."
     },
     {
      "name": "max_price",
      "in": "query",
      "schema": {
       "type": "number"
      },
      "description": "Price range in USD."
     },
     {
      "$ref": "#/components/parameters/condition"
     },
     {
      "name": "format",
      "in": "query",
      "description": "bin for Buy It Now only, auction for auctions only.",
      "schema": {
       "type": "string",
       "enum": [
        "bin",
        "auction"
       ]
      }
     },
     {
      "name": "category",
      "in": "query",
      "description": "eBay only: ignored when source is a marketplace. eBay category id.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Live listings.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ActiveResponse"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/BadRequest"
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "501": {
      "$ref": "#/components/responses/NotAvailable"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "500": {
      "$ref": "#/components/responses/ServerError"
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     }
    }
   }
  },
  "/v1/usage": {
   "get": {
    "summary": "Usage for the current UTC day (does not count against limits)",
    "responses": {
     "200": {
      "description": "Usage counters.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "day_utc": {
           "type": "string"
          },
          "used": {
           "type": "integer"
          },
          "daily_cap": {
           "type": "integer"
          },
          "trial_hours": {
           "type": "integer",
           "nullable": true
          },
          "trial_started": {
           "type": "string",
           "nullable": true
          },
          "expires": {
           "type": "string",
           "nullable": true
          }
         }
        }
       }
      }
     },
     "401": {
      "$ref": "#/components/responses/Unauthorized"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "500": {
      "$ref": "#/components/responses/ServerError"
     }
    }
   }
  },
  "/v1/health": {
   "get": {
    "summary": "Service status",
    "security": [],
    "responses": {
     "200": {
      "description": "Service is up."
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "500": {
      "$ref": "#/components/responses/ServerError"
     }
    }
   }
  },
  "/v1/sources": {
   "get": {
    "summary": "List the valid source values",
    "security": [],
    "responses": {
     "200": {
      "description": "Valid sources.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "default": {
           "type": "string"
          },
          "sources": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "all": {
           "type": "string"
          },
          "all_merges": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "The sources source=all merges: the 12 marketplaces."
          },
          "not_in_all": {
           "type": "object",
           "additionalProperties": {
            "type": "string"
           },
           "description": "Sources left out of all, with the reason (psa)."
          },
          "live_listings": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Sources that answer /v1/active."
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "500": {
      "$ref": "#/components/responses/ServerError"
     }
    },
    "description": "No key needed, not counted."
   }
  },
  "/v1/lookup": {
   "get": {
    "operationId": "lookupCard",
    "tags": [
     "cards"
    ],
    "summary": "Resolve a card keyword to PSA spec ids",
    "description": "Keyword to canonical PSA spec ids with card metadata, best match first. The spec id keys /v1/population and card.psa_spec_id on source=psa sold rows. One request.",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string",
       "maxLength": 300
      },
      "required": true,
      "description": "Card keyword, e.g. 2018 panini prizm luka doncic 280."
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 25,
       "default": 10
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK. When PSA is unreachable: ok=false, error=psa_unavailable.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/LookupResponse"
        }
       }
      }
     },
     "400": {
      "description": "Missing or invalid parameter",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid key",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "500": {
      "$ref": "#/components/responses/ServerError"
     }
    }
   }
  },
  "/v1/population": {
   "get": {
    "operationId": "cardPopulation",
    "tags": [
     "cards"
    ],
    "summary": "PSA population census for a card",
    "description": "Per-grade PSA census and gem rate for a spec id, or for the top match of q. One request.",
    "parameters": [
     {
      "name": "spec",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^\\d+$"
      },
      "description": "PSA spec id (from /v1/lookup or card.psa_spec_id)."
     },
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string",
       "maxLength": 300
      },
      "description": "Card keyword, resolved to the top spec when spec is not given."
     }
    ],
    "responses": {
     "200": {
      "description": "OK. When PSA is unreachable: ok=false, error=psa_unavailable.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PopulationResponse"
        }
       }
      }
     },
     "400": {
      "description": "Missing or invalid parameter",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid key",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limit",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "500": {
      "$ref": "#/components/responses/ServerError"
     }
    }
   }
  }
 }
}
