> ## 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 products

> Every sealed product, or one expansion at a time.

Every boxed, bundled and sealed thing in the catalog, ordered by id and paged by cursor.

Pass `expansion_id` to narrow to one expansion: `?expansion_id=sv03.5` for the boxes and bundles
sold around 151. It is a filter, not a lookup, so an id that matches nothing is an empty page
rather than a `404`.

A product can belong to more than one expansion, since a Trainer Kit box ships two decks, and it
still appears once here. A product attached to no expansion at all appears too.

Pass `q` to search by name. 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=booster%20box&expansion_id=sv03.5` searches inside one expansion. Ranking and ties behave as
they do on [List cards](/cards/list).

Rows are summaries. Fetch [the product](/products/get) for its expansions and its prices.


## OpenAPI

````yaml openapi.json GET /v1/products
openapi: 3.0.0
info:
  title: Cromos API
  version: 1.0.0
servers:
  - url: https://api.cromos.so
security:
  - bearerAuth: []
paths:
  /v1/products:
    get:
      tags:
        - Products
      summary: List products
      description: >-
        Sealed products (booster boxes, elite trainer boxes, collections),
        ordered by id. Pass `expansion_id` to narrow to one expansion, or `q` to
        search by name: rows then come back best-match first, each carrying a
        `score`, and the cursor keeps working exactly as it does without it. A
        product can belong to more than one expansion: a Trainer Kit box ships
        two decks, and it still appears once here. An `expansion_id` that
        matches nothing is an empty page, not a 404.
      operationId: listProducts
      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 products by name. Ranked best-match first, every row
              carrying its `score`, and the cursor keeps working.
          required: false
          description: >-
            Search products by name. Ranked best-match first, every row carrying
            its `score`, and the cursor keeps working.
          name: q
          in: query
      responses:
        '200':
          description: Product 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/ProductSummary'
                            - 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: 501999
                      name: 151 Pokemon Center Elite Trainer Box (Exclusive)
                      number: null
                      image:
                        low: https://assets.cromos.so/products/501999/low.webp
                        high: https://assets.cromos.so/products/501999/high.webp
                    - id: 502000
                      name: 151 Booster Bundle
                      number: null
                      image:
                        low: https://assets.cromos.so/products/502000/low.webp
                        high: https://assets.cromos.so/products/502000/high.webp
                    - id: 502001
                      name: 151 Poster Collection
                      number: null
                      image:
                        low: https://assets.cromos.so/products/502001/low.webp
                        high: https://assets.cromos.so/products/502001/high.webp
                  next_cursor: NTAyMDAx
                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:
    ProductSummary:
      type: object
      properties:
        id:
          type: number
        name:
          type: string
        number:
          type: string
          nullable: true
        image:
          $ref: '#/components/schemas/ImageUrls'
      required:
        - id
        - name
        - number
        - image
    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
    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

````