> ## Documentation Index > Fetch the complete documentation index at: https://docs.cromos.dev/llms.txt > Use this file to discover all available pages before exploring further. # List cards > Every card in the catalog, in catalog order. Cards come back in catalog order, by expansion then collector number, paged by cursor. This is how you walk the whole catalog: keep calling with the `next_cursor` you were handed until it comes back `null`. Pass `expansion_id` to walk one expansion instead. It is a filter, not a lookup, so an id that matches nothing is an empty page rather than a `404`. Pass `q` to search by name or collector number. Rows then come back best-match first, each carrying a `score`, and the cursor keeps working exactly as it does without it. The two compose: `?q=charizard&expansion_id=base1` searches inside one expansion. A name resolves to candidates, not to one id. Dozens of cards are named exactly "Charizard", so they all score identically and `?q=charizard` hands back a list to choose from rather than an answer. Where rows tie at the top score the tie-break is `id` order, not relevance, so the first row is the lowest id among equals and not the best match. Show the candidates and let someone pick, or narrow with `expansion_id`. Ranking is by similarity, so a misspelling still finds its card. Rows here are summaries, not full [card objects](/cards/object). They carry enough to render a list. Fetch [the card](/cards/get) when someone opens one. ## Attaching more to each row `include` takes a comma-separated list of `variants`, `metadata`, `change`, or any combination. | Value | What it attaches | | ---------- | ------------------------------------------------------------------------------------- | | `variants` | Every printing of the card with its current prices | | `metadata` | The same metadata bag `GET /v1/cards/{id}` serves, or `null` for a card that has none | | `change` | Every computed window of price change for the card's headline printing | `variants` is the same array [the card object](/cards/object) carries, so one decoder covers both endpoints. With both includes, a row carries every field `GET /v1/cards/{id}` serves and `number_normalized` besides. Each include is absent entirely unless you ask for it. The key is not `null` and not an empty array. A card the catalog holds no printings for gets `[]` once you do ask. A value the endpoint does not recognise is dropped rather than refused. `change` stays absent even when asked for if the card has no computed mover row, and it reports the card's headline printing, not necessarily the one that moved most. See [Change](/cards/object#change) on the card object, and [List biggest gainers and losers](/cards/movers) for the leaderboard this is drawn from. This is how you build a local catalog. At `limit=200` the roughly 21,000-card catalog is about 105 requests instead of one per card. ## OpenAPI ````yaml openapi.json GET /v1/cards openapi: 3.0.0 info: title: Cromos API version: 1.0.0 servers: - url: https://api.cromos.so security: - bearerAuth: [] paths: /v1/cards: get: tags: - Cards summary: List cards description: >- Cards in catalog order, by expansion then collector number. Pass `expansion_id` to walk one expansion, or `q` to search by name or collector number: rows then come back best-match first, each carrying a `score`, and the cursor keeps working exactly as it does without it. `include=variants,metadata,change` attaches every printing with its current prices, the full metadata bag, and the price-change badge data for this card to each row, so a full catalog build is one request per page instead of one per card. Each include is absent entirely unless you ask for it, and `change` stays absent even when asked for if the card has no computed mover row; every other field is always present. An `expansion_id` that matches nothing is an empty page, not a 404. operationId: listCards parameters: - schema: type: integer description: >- How many rows to return. Defaults to 50 and stops at 200; a larger value is clamped, not rejected. minimum: 1 maximum: 200 default: 50 required: false description: >- How many rows to return. Defaults to 50 and stops at 200; a larger value is clamped, not rejected. name: limit in: query - schema: type: string description: >- The `next_cursor` from the previous page. Omit it for the first page. A cursor this endpoint did not issue is ignored, and you get the first page back. required: false description: >- The `next_cursor` from the previous page. Omit it for the first page. A cursor this endpoint did not issue is ignored, and you get the first page back. name: cursor in: query - schema: type: string description: >- Narrow the list to one expansion. An id that matches nothing is an empty page, not a 404. required: false description: >- Narrow the list to one expansion. An id that matches nothing is an empty page, not a 404. name: expansion_id in: query - schema: type: string minLength: 1 description: >- Search cards by name or collector number. Ranked best-match first, every row carrying its `score`, and the cursor keeps working. required: false description: >- Search cards by name or collector number. Ranked best-match first, every row carrying its `score`, and the cursor keeps working. name: q in: query - schema: type: string description: >- Comma-separated extras to attach to every row: `variants`, `metadata`, `change`, or any combination. A value that is not one of those is dropped rather than rejected. required: false description: >- Comma-separated extras to attach to every row: `variants`, `metadata`, `change`, or any combination. A value that is not one of those is dropped rather than rejected. name: include in: query responses: '200': description: Card list headers: ETag: description: >- A strong validator over the response body. Send it back as `If-None-Match` to get a `304 Not Modified` when nothing has changed. schema: type: string RateLimit: description: >- Remaining budget in the current window, RFC 9239 draft-7 form: `limit=300, remaining=284, reset=41`. `reset` is seconds until the window rolls. schema: type: string RateLimit-Policy: description: >- The policy the budget above is drawn from. `300;w=60` is 300 requests a minute. schema: type: string content: application/json: schema: type: object properties: data: type: object properties: items: type: array items: allOf: - $ref: '#/components/schemas/CardSummary' - type: object properties: score: type: number description: >- How closely this row matched `q`, from 0 to 1. Present only when `q` is set; the key is absent otherwise. Ties at the top score are common, and the tie-break is `id` order rather than relevance. next_cursor: type: string nullable: true description: >- Pass this back as `cursor` for the next page. `null` means this was the last. required: - items - next_cursor error: type: object nullable: true required: - data - error example: data: items: - id: base1-1 expansion_id: base1 number: '1' name: Alakazam rarity: Rare illustrator: Ken Sugimori image: low: https://assets.cromos.so/cards/base1-1/low.webp high: https://assets.cromos.so/cards/base1-1/high.webp palette: - '#f2d244' - '#ac9ccc' - '#0b2363' - '#7c6c9d' category: Pokemon number_normalized: '1' variants: - id: 2 type: holo subtype: unlimited size: standard stamps: [] foil: null tcgplayer: - condition: NM currency: USD market: 6665 low: 4699 high: 8035 listing_count: 25 observed_on: '2026-08-17' - condition: LP currency: USD market: 4826 low: 4495 high: 5399 listing_count: 25 observed_on: '2026-08-17' - condition: MP currency: USD market: 2736 low: 2317 high: 3969 listing_count: 25 observed_on: '2026-08-17' - condition: HP currency: USD market: 2217 low: 1950 high: 3847 listing_count: 25 observed_on: '2026-08-17' - condition: DMG currency: USD market: 1588 low: 1150 high: 4030 listing_count: 25 observed_on: '2026-08-17' - id: 3 type: holo subtype: shadowless size: standard stamps: - 1st-edition foil: null tcgplayer: - condition: NM currency: USD market: 42900 low: 42900 high: 42900 listing_count: 1 observed_on: '2026-08-17' - condition: LP currency: USD market: 56100 low: 56100 high: 56100 listing_count: 1 observed_on: '2026-08-17' - condition: MP currency: USD market: 32813 low: 32813 high: 32813 listing_count: 1 observed_on: '2026-08-17' - condition: HP currency: USD market: 31841 low: 24683 high: 38999 listing_count: 2 observed_on: '2026-08-17' - condition: DMG currency: USD market: 29505 low: 26499 high: 35000 listing_count: 5 observed_on: '2026-08-17' - id: 4 type: holo subtype: shadowless size: standard stamps: [] foil: null tcgplayer: - condition: NM currency: USD market: 29032 low: 25098 high: 35999 listing_count: 3 observed_on: '2026-08-17' - condition: LP currency: USD market: 16919 low: 11283 high: 21000 listing_count: 4 observed_on: '2026-08-17' - condition: MP currency: USD market: 8718 low: 6899 high: 11048 listing_count: 15 observed_on: '2026-08-17' - condition: HP currency: USD market: 6484 low: 4418 high: 10420 listing_count: 13 observed_on: '2026-08-17' - condition: DMG currency: USD market: 5714 low: 5000 high: 6623 listing_count: 11 observed_on: '2026-08-17' - id: 5 type: holo subtype: 1999-2000-copyright size: standard stamps: [] foil: null tcgplayer: [] change: - window: 1d card_variant_id: 3 printing: holo start_cents: 42900 end_cents: 42900 change_cents: 0 change_bp: 0 start_as_of: '2026-07-31' observed_on: '2026-08-17' - window: 7d card_variant_id: 3 printing: holo start_cents: 42900 end_cents: 42900 change_cents: 0 change_bp: 0 start_as_of: '2026-07-31' observed_on: '2026-08-17' - id: base1-2 expansion_id: base1 number: '2' name: Blastoise rarity: Rare illustrator: Ken Sugimori image: low: https://assets.cromos.so/cards/base1-2/low.webp high: https://assets.cromos.so/cards/base1-2/high.webp palette: - '#eccd46' - '#13145c' - '#448bbb' - '#cce2ec' category: Pokemon number_normalized: '2' variants: - id: 6 type: holo subtype: unlimited size: standard stamps: [] foil: null tcgplayer: - condition: NM currency: USD market: 22452 low: 19999 high: 27998 listing_count: 25 observed_on: '2026-08-17' - condition: LP currency: USD market: 13465 low: 12000 high: 16752 listing_count: 25 observed_on: '2026-08-17' - condition: MP currency: USD market: 9232 low: 8648 high: 11499 listing_count: 25 observed_on: '2026-08-17' - condition: HP currency: USD market: 6290 low: 5000 high: 7115 listing_count: 25 observed_on: '2026-08-17' - condition: DMG currency: USD market: 5285 low: 4500 high: 6775 listing_count: 25 observed_on: '2026-08-17' - id: 7 type: holo subtype: shadowless size: standard stamps: - 1st-edition foil: null tcgplayer: - condition: NM currency: USD market: 16550 low: 16550 high: 16550 listing_count: 1 observed_on: '2026-08-17' - condition: LP currency: USD market: 45000 low: 45000 high: 45000 listing_count: 1 observed_on: '2026-08-17' - condition: MP currency: USD market: 130000 low: 130000 high: 130000 listing_count: 1 observed_on: '2026-08-17' - condition: HP currency: USD market: 70000 low: 70000 high: 70000 listing_count: 1 observed_on: '2026-08-17' - condition: DMG currency: USD market: 96969 low: 96969 high: 96969 listing_count: 1 observed_on: '2026-08-17' - id: 8 type: holo subtype: shadowless size: standard stamps: [] foil: null tcgplayer: - condition: NM currency: USD market: 82000 low: 82000 high: 82000 listing_count: 1 observed_on: '2026-08-17' - condition: LP currency: USD market: 45366 low: 35100 high: 50499 listing_count: 3 observed_on: '2026-08-17' - condition: MP currency: USD market: 28557 low: 24800 high: 35122 listing_count: 6 observed_on: '2026-08-17' - condition: HP currency: USD market: 21582 low: 17260 high: 29895 listing_count: 8 observed_on: '2026-08-17' - condition: DMG currency: USD market: 18470 low: 13235 high: 23999 listing_count: 8 observed_on: '2026-08-17' - id: 9 type: holo subtype: 1999-2000-copyright size: standard stamps: [] foil: null tcgplayer: [] change: - window: 1d card_variant_id: 8 printing: holo start_cents: 82000 end_cents: 82000 change_cents: 0 change_bp: 0 start_as_of: '2026-07-31' observed_on: '2026-08-17' - window: 7d card_variant_id: 8 printing: holo start_cents: 82000 end_cents: 82000 change_cents: 0 change_bp: 0 start_as_of: '2026-07-31' observed_on: '2026-08-17' - id: base1-3 expansion_id: base1 number: '3' name: Chansey rarity: Rare illustrator: Ken Sugimori image: low: https://assets.cromos.so/cards/base1-3/low.webp high: https://assets.cromos.so/cards/base1-3/high.webp palette: - '#f2d242' - '#cde2ef' - '#a3b4c3' - '#2b3c53' category: Pokemon number_normalized: '3' variants: - id: 10 type: holo subtype: unlimited size: standard stamps: [] foil: null tcgplayer: - condition: NM currency: USD market: 6127 low: 3404 high: 13060 listing_count: 25 observed_on: '2026-08-17' - condition: LP currency: USD market: 2482 low: 2099 high: 3854 listing_count: 25 observed_on: '2026-08-17' - condition: MP currency: USD market: 1510 low: 1275 high: 2300 listing_count: 25 observed_on: '2026-08-17' - condition: HP currency: USD market: 937 low: 559 high: 1295 listing_count: 25 observed_on: '2026-08-17' - condition: DMG currency: USD market: 851 low: 500 high: 2520 listing_count: 25 observed_on: '2026-08-17' - id: 11 type: holo subtype: shadowless size: standard stamps: - 1st-edition foil: null tcgplayer: - condition: NM currency: USD market: 40000 low: 40000 high: 40000 listing_count: 1 observed_on: '2026-08-17' - condition: LP currency: USD market: 30000 low: 30000 high: 30000 listing_count: 1 observed_on: '2026-08-17' - condition: MP currency: USD market: 35030 low: 20060 high: 49999 listing_count: 3 observed_on: '2026-08-17' - condition: HP currency: USD market: 25400 low: 24650 high: 26149 listing_count: 2 observed_on: '2026-08-17' - condition: DMG currency: USD market: 10120 low: 440 high: 19800 listing_count: 3 observed_on: '2026-08-17' - id: 12 type: holo subtype: shadowless size: standard stamps: [] foil: null tcgplayer: - condition: NM currency: USD market: 40000 low: 40000 high: 40000 listing_count: 1 observed_on: '2026-08-17' - condition: LP currency: USD market: 10109 low: 8008 high: 14999 listing_count: 11 observed_on: '2026-08-17' - condition: MP currency: USD market: 5094 low: 3546 high: 12500 listing_count: 21 observed_on: '2026-08-17' - condition: HP currency: USD market: 2914 low: 2294 high: 3656 listing_count: 25 observed_on: '2026-08-17' - condition: DMG currency: USD market: 2050 low: 1733 high: 3000 listing_count: 25 observed_on: '2026-08-17' - id: 13 type: holo subtype: 1999-2000-copyright size: standard stamps: [] foil: null tcgplayer: [] change: - window: 1d card_variant_id: 11 printing: holo start_cents: 40000 end_cents: 40000 change_cents: 0 change_bp: 0 start_as_of: '2026-07-31' observed_on: '2026-08-17' - window: 7d card_variant_id: 11 printing: holo start_cents: 40000 end_cents: 40000 change_cents: 0 change_bp: 0 start_as_of: '2026-07-31' observed_on: '2026-08-17' next_cursor: eyJlIjoiYmFzZTEiLCJuIjozLCJpZCI6ImJhc2UxLTMifQ error: null '304': description: >- Not modified. The `If-None-Match` you sent still matches, and there is no body. headers: ETag: description: >- A strong validator over the response body. Send it back as `If-None-Match` to get a `304 Not Modified` when nothing has changed. schema: type: string RateLimit: description: >- Remaining budget in the current window, RFC 9239 draft-7 form: `limit=300, remaining=284, reset=41`. `reset` is seconds until the window rolls. schema: type: string RateLimit-Policy: description: >- The policy the budget above is drawn from. `300;w=60` is 300 requests a minute. schema: type: string '400': description: Bad request headers: ETag: description: >- A strong validator over the response body. Send it back as `If-None-Match` to get a `304 Not Modified` when nothing has changed. schema: type: string RateLimit: description: >- Remaining budget in the current window, RFC 9239 draft-7 form: `limit=300, remaining=284, reset=41`. `reset` is seconds until the window rolls. schema: type: string RateLimit-Policy: description: >- The policy the budget above is drawn from. `300;w=60` is 300 requests a minute. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized headers: ETag: description: >- A strong validator over the response body. Send it back as `If-None-Match` to get a `304 Not Modified` when nothing has changed. schema: type: string RateLimit: description: >- Remaining budget in the current window, RFC 9239 draft-7 form: `limit=300, remaining=284, reset=41`. `reset` is seconds until the window rolls. schema: type: string RateLimit-Policy: description: >- The policy the budget above is drawn from. `300;w=60` is 300 requests a minute. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limited headers: ETag: description: >- A strong validator over the response body. Send it back as `If-None-Match` to get a `304 Not Modified` when nothing has changed. schema: type: string RateLimit: description: >- Remaining budget in the current window, RFC 9239 draft-7 form: `limit=300, remaining=284, reset=41`. `reset` is seconds until the window rolls. schema: type: string RateLimit-Policy: description: >- The policy the budget above is drawn from. `300;w=60` is 300 requests a minute. schema: type: string Retry-After: description: Seconds to wait before retrying. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal error headers: ETag: description: >- A strong validator over the response body. Send it back as `If-None-Match` to get a `304 Not Modified` when nothing has changed. schema: type: string RateLimit: description: >- Remaining budget in the current window, RFC 9239 draft-7 form: `limit=300, remaining=284, reset=41`. `reset` is seconds until the window rolls. schema: type: string RateLimit-Policy: description: >- The policy the budget above is drawn from. `300;w=60` is 300 requests a minute. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: CardSummary: type: object properties: id: type: string expansion_id: type: string number: type: string nullable: true description: The printed collector number, e.g. `TG01`. name: type: string rarity: type: string nullable: true illustrator: type: string nullable: true image: $ref: '#/components/schemas/ImageUrls' palette: type: array nullable: true items: type: string description: >- Up to four dominant colours from the card art, most prominent first, as `#rrggbb`. Colours that appear only around the edge of the card, such as the printed border, are left out. Where the art carries a strong colour, the first entry is that colour rather than a grey or a white the card has more of; art with no strong colour leads with a neutral instead. Null when no image is available or it yields no colour, and may contain fewer than four: the list is never padded with colours the art does not contain. category: type: string nullable: true number_normalized: type: string nullable: true description: >- The collector number folded for matching, with zero padding stripped and any `/total` suffix dropped, so `001/131` becomes `1`. NOT a sort key: sorting a local catalog by this string puts `10` before `2`. Catalog order is expansion, then collector number NUMERICALLY, with non-numeric numbers (`TG01`, `2a`) last, then `id`. variants: type: array items: $ref: '#/components/schemas/CardVariant' description: >- Present only with `?include=variants`. Every printing of this card with its current prices, the same shape `GET /v1/cards/{id}` serves. Without the parameter the key is absent entirely; a card the catalog holds no printings for gets `[]`. metadata: type: object nullable: true properties: hp: type: number nullable: true types: type: array nullable: true items: type: string pokedex_numbers: type: array nullable: true items: type: number stage: type: string nullable: true evolve_from: type: string nullable: true description: type: string nullable: true effect: type: string nullable: true trainer_type: type: string nullable: true energy_type: type: string nullable: true retreat: type: number nullable: true abilities: type: array nullable: true items: type: object properties: kind: type: string description: >- The rule box kind: `ability`, `pokemon-power`, `poke-body` and so on. name: type: string text: type: string nullable: true required: - kind - name - text attacks: type: array nullable: true items: type: object properties: name: type: string cost: type: array nullable: true items: type: string description: Energy symbols in printed order. damage: type: string nullable: true description: 'As printed: `80`, `80+`, `30x`.' text: type: string nullable: true required: - name - cost - damage - text weaknesses: type: array nullable: true items: type: object properties: type: type: string modifier: type: string nullable: true description: 'As printed, ascii: `x2`, `-30`, `+10`.' required: - type - modifier resistances: type: array nullable: true items: type: object properties: type: type: string modifier: type: string nullable: true description: 'As printed, ascii: `x2`, `-30`, `+10`.' required: - type - modifier legality: type: object nullable: true properties: standard: type: boolean expanded: type: boolean required: - standard - expanded required: - hp - types - pokedex_numbers - stage - evolve_from - description - effect - trainer_type - energy_type - retreat - abilities - attacks - weaknesses - resistances - legality description: >- Present only with `?include=metadata`. The same bag `GET /v1/cards/{id}` serves, and `null` for a card that has none. Without the parameter the key is absent entirely. change: type: array items: type: object properties: window: type: string enum: - 1d - 7d - 30d description: The window this change was measured over. card_variant_id: type: integer description: >- The stable id of the printing this row is about, the same id `variants[].id` carries on the card. Use it to match the row to a printing: it is exact, where `printing` is not. printing: type: string description: >- Which printing of the card moved. This is the printing `type` alone (`normal`, `holo`, `reverse` and so on), and it is not unique on its own: a card can have two printings of the same `type`, differing on `subtype`, `size`, `stamps` or `foil`. Read `card_variant_id` to tell which one this is. start_cents: type: integer description: Market price at the start of the window, in cents. end_cents: type: integer description: Market price now, in cents. change_cents: type: integer description: '`end_cents - start_cents`.' change_bp: type: integer description: >- Change in basis points. +34.20% is `3420`. Integer, never a float. start_as_of: type: string description: >- The day `start_cents` was actually observed. Earlier than the window start whenever the value was carried forward -- prices are stored as a change log, so a flat card has no row on most days. Use this to tell a held price from a stale one. observed_on: type: string description: The day `end_cents` was observed. required: - window - card_variant_id - printing - start_cents - end_cents - change_cents - change_bp - start_as_of - observed_on description: >- Present only with `?include=change`, and only when this card has a computed mover row. Every window computed for the card's HEADLINE printing -- the one its displayed price is read from, not necessarily the one that moved the most -- so a client can switch window without a refetch. Without the parameter, or when no printing qualifies, the key is absent entirely. required: - id - expansion_id - number - name - rarity - illustrator - image - palette - category - number_normalized ErrorResponse: type: object properties: data: type: object nullable: true error: $ref: '#/components/schemas/ApiError' required: - data - error ImageUrls: type: object nullable: true properties: low: type: string format: uri description: Thumbnail-sized rendition. May be the same URL as `high`. high: type: string format: uri description: Full-sized rendition. May be the same URL as `low`. required: - low - high CardVariant: type: object properties: id: type: integer description: >- Stable identifier for this printing. Use it to key stored prices, and to resolve a `pokemon.card_variants.deleted` event. Lasts as long as the printing it names: when a printing is reclassified, the old id is deleted and a new one takes its place. type: type: string description: >- The printing: `normal`, `holo`, `reverse` and so on. A printing, not a physical dimension. See `size`. subtype: type: string nullable: true description: A narrower printing within `type`, where one exists. size: type: string nullable: true description: >- The physical card size, such as `standard` or `jumbo`. A different axis from `type`: a jumbo card and a holo card are not alternatives. stamps: type: array items: type: string description: >- Promotional stamps printed on this variant, such as a prerelease or staff stamp. foil: type: string nullable: true description: The foil treatment, where the printing carries one. tcgplayer: type: array items: $ref: '#/components/schemas/TcgplayerPrice' required: - id - type - subtype - size - stamps - foil - tcgplayer ApiError: type: object properties: code: type: string description: A stable machine-readable token. Switch on this, not on `message`. message: type: string description: A human-readable sentence. Always present, never empty. required: - code - message TcgplayerPrice: type: object properties: condition: type: string currency: type: string enum: - USD market: type: integer nullable: true description: An integer amount in cents (minor units). low: type: integer nullable: true description: An integer amount in cents (minor units). high: type: integer nullable: true description: An integer amount in cents (minor units). listing_count: type: integer nullable: true description: >- How many active listings this price is computed from. 1 means the price is a single seller's asking price, not a market consensus. The value caps at 25, so 25 means 25 or more. Null where no count is available. observed_on: type: string description: The date this price was observed, as YYYY-MM-DD. required: - condition - currency - market - low - high - listing_count - observed_on securitySchemes: bearerAuth: type: http scheme: bearer ````