> ## Documentation Index > Fetch the complete documentation index at: https://docs.cromos.so/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: an id that matches nothing is an empty page, not 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 — the first row is the lowest id among equals, 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. To identify a card from a photo rather than from a name, use [Scan a card](/scan). Rows here are summaries, not full [card objects](/cards/object) — enough to render a list, and without the metadata and printings. Fetch [the card](/cards/get) when someone opens one. Pass `include=prices` to attach a flat price list to every row and save a request per card. Without it the `prices` key is absent entirely — not `null`, and not an empty array. ## 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 — results then come back best-match first, each carrying a `score`, and the cursor keeps working exactly as it does without it. `include=prices` attaches a flat price list to every row and saves a request per card; without it the `prices` key is absent entirely, not null and not an empty array. An `expansion_id` that matches nothing is an empty page, not a 404. parameters: - schema: type: string description: >- How many rows to return. Defaults to 50 and stops at 200; a larger value is clamped, not rejected. 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. `prices` is the only value recognised today; anything else is dropped rather than rejected. required: false description: >- Comma-separated extras to attach to every row. `prices` is the only value recognised today; anything else is dropped rather than rejected. name: include in: query responses: '200': description: Card list 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 — the tie-break is `id` order, not 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 image: low: https://assets.cromos.so/cards/base1-1/low.webp high: https://assets.cromos.so/cards/base1-1/high.webp number_normalized: '1' prices: - variant: Holofoil condition: NM currency: USD market: 7127 low: 4900 high: 11340 - variant: Holofoil condition: LP currency: USD market: 4869 low: 4200 high: 7974 - variant: Holofoil condition: MP currency: USD market: 2899 low: 1199 high: 3969 - variant: Holofoil condition: HP currency: USD market: 2225 low: 1769 high: 3847 - variant: Holofoil condition: DMG currency: USD market: 1559 low: 1156 high: 4030 - variant: 1st Edition Holofoil condition: NM currency: USD market: 42900 low: 42900 high: 42900 - variant: 1st Edition Holofoil condition: LP currency: USD market: 56100 low: 56100 high: 56100 - variant: 1st Edition Holofoil condition: MP currency: USD market: 32813 low: 32813 high: 32813 - variant: 1st Edition Holofoil condition: HP currency: USD market: 31841 low: 24683 high: 38999 - variant: 1st Edition Holofoil condition: DMG currency: USD market: 29505 low: 26499 high: 35000 - variant: Unlimited Holofoil condition: NM currency: USD market: 29032 low: 25098 high: 35999 - variant: Unlimited Holofoil condition: LP currency: USD market: 14996 low: 11100 high: 21000 - variant: Unlimited Holofoil condition: MP currency: USD market: 8444 low: 6300 high: 11048 - variant: Unlimited Holofoil condition: HP currency: USD market: 6193 low: 4201 high: 10420 - variant: Unlimited Holofoil condition: DMG currency: USD market: 5942 low: 5301 high: 7500 - id: base1-2 expansion_id: base1 number: '2' name: Blastoise rarity: Rare image: low: https://assets.cromos.so/cards/base1-2/low.webp high: https://assets.cromos.so/cards/base1-2/high.webp number_normalized: '2' prices: - variant: Holofoil condition: NM currency: USD market: 22486 low: 18000 high: 32828 - variant: Holofoil condition: LP currency: USD market: 14450 low: 12000 high: 16773 - variant: Holofoil condition: MP currency: USD market: 9120 low: 8799 high: 10000 - variant: Holofoil condition: HP currency: USD market: 6321 low: 5495 high: 7000 - variant: Holofoil condition: DMG currency: USD market: 4439 low: 2600 high: 5500 - variant: 1st Edition Holofoil condition: NM currency: USD market: 16550 low: 16550 high: 16550 - variant: 1st Edition Holofoil condition: LP currency: USD market: 45000 low: 45000 high: 45000 - variant: 1st Edition Holofoil condition: MP currency: USD market: 130000 low: 130000 high: 130000 - variant: 1st Edition Holofoil condition: HP currency: USD market: 70000 low: 70000 high: 70000 - variant: 1st Edition Holofoil condition: DMG currency: USD market: 96969 low: 96969 high: 96969 - variant: Unlimited Holofoil condition: NM currency: USD market: 82000 low: 82000 high: 82000 - variant: Unlimited Holofoil condition: LP currency: USD market: 45366 low: 35100 high: 50499 - variant: Unlimited Holofoil condition: MP currency: USD market: 27620 low: 22000 high: 35122 - variant: Unlimited Holofoil condition: HP currency: USD market: 20269 low: 16151 high: 29895 - variant: Unlimited Holofoil condition: DMG currency: USD market: 16980 low: 13235 high: 23999 - variant: holo currency: EUR price_kind: plain avg: 11576 low: 1800 trend: 10864 avg_holo: null low_holo: null trend_holo: 7351 - id: base1-3 expansion_id: base1 number: '3' name: Chansey rarity: Rare image: low: https://assets.cromos.so/cards/base1-3/low.webp high: https://assets.cromos.so/cards/base1-3/high.webp number_normalized: '3' prices: - variant: Holofoil condition: NM currency: USD market: 6291 low: 4969 high: 22996 - variant: Holofoil condition: LP currency: USD market: 2248 low: 1600 high: 3399 - variant: Holofoil condition: MP currency: USD market: 1564 low: 1301 high: 2446 - variant: Holofoil condition: HP currency: USD market: 1219 low: 700 high: 3145 - variant: Holofoil condition: DMG currency: USD market: 868 low: 525 high: 2520 - variant: 1st Edition Holofoil condition: NM currency: USD market: 40000 low: 40000 high: 40000 - variant: 1st Edition Holofoil condition: LP currency: USD market: 30000 low: 30000 high: 30000 - variant: 1st Edition Holofoil condition: MP currency: USD market: 35030 low: 20060 high: 49999 - variant: 1st Edition Holofoil condition: HP currency: USD market: 25400 low: 24650 high: 26149 - variant: 1st Edition Holofoil condition: DMG currency: USD market: 10120 low: 440 high: 19800 - variant: Unlimited Holofoil condition: NM currency: USD market: 40000 low: 40000 high: 40000 - variant: Unlimited Holofoil condition: LP currency: USD market: 9207 low: 5000 high: 14999 - variant: Unlimited Holofoil condition: MP currency: USD market: 4947 low: 3399 high: 12500 - variant: Unlimited Holofoil condition: HP currency: USD market: 2894 low: 2287 high: 3656 - variant: Unlimited Holofoil condition: DMG currency: USD market: 2050 low: 1733 high: 3000 - variant: holo currency: EUR price_kind: plain avg: 3253 low: 400 trend: 2443 avg_holo: null low_holo: null trend_holo: 2143 next_cursor: eyJlIjoiYmFzZTEiLCJuIjozLCJpZCI6ImJhc2UxLTMifQ error: null '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal error 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 image: $ref: '#/components/schemas/ImageUrls' number_normalized: type: string nullable: true description: >- The collector number in a sortable form. This is the order the list returns. prices: type: array items: $ref: '#/components/schemas/CardPriceEntry' description: >- Present only with `?include=prices`. Without it the key is absent entirely, not null and not an empty array. required: - id - expansion_id - number - name - rarity - image - 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 CardPriceEntry: anyOf: - 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). variant: type: string required: - condition - currency - market - low - high - variant - type: object properties: currency: type: string enum: - EUR avg: 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). trend: type: integer nullable: true description: An integer amount in cents (minor units). avg_holo: type: integer nullable: true description: An integer amount in cents (minor units). low_holo: type: integer nullable: true description: An integer amount in cents (minor units). trend_holo: type: integer nullable: true description: An integer amount in cents (minor units). variant: type: string price_kind: type: string nullable: true enum: - plain - holo - null required: - currency - avg - low - trend - avg_holo - low_holo - trend_holo - variant - price_kind 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 securitySchemes: bearerAuth: type: http scheme: bearer ````