> ## Documentation Index
> Fetch the complete documentation index at: https://catchbackcards.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a pack's pool

> **Scope:** `read:catalog`

What a pack can pull right now: its value bands with odds at a risk level, the chase card if one is set, and every hittable card. A band at 0% odds is still listed, but its cards are not.

`kind` says what the pack pays out. A `slab` pack pays graded cards, listed in `cards`. A `sealed` pack (the Starter and the sealed mystery packs) pays sealed products: every in-stock product is its own band, `products` lists them, and `cards` is empty.

The pool is [point-in-time](/partner-api/errors-and-limits#inventory-is-point-in-time): any opening on CatchBack can take a card from it. A sold-out pack still answers `200` with `available: false`.



## OpenAPI

````yaml /partner-api/openapi.yaml get /api/partner/v1/catalog/packs/pool
openapi: 3.1.0
info:
  title: CatchBack Partner API
  version: 1.0.0
  summary: Open packs, trade cards, read card data and ship vaulted cards.
  description: >-
    The Partner API acts on one CatchBack account with its real CatchCoins
    balance. Several

    operations here move money or data, so read
    [Idempotency](/partner-api/idempotency) before

    you call them.


    Error bodies are JSON with a human-readable `error` and, where you might
    branch on it, a

    machine-readable `code`. Branch on the status and the `code`, because the
    `error` text can

    change. New fields can be added to any response.
  contact:
    name: CatchBack support
    email: catchbackcards@gmail.com
servers:
  - url: https://catchbackcards.com
    description: Production. Every call acts on real money and real inventory.
security:
  - bearerAuth: []
tags:
  - name: Gacha
    description: Open packs, see what they can pull, check a pull, and sell cards back.
  - name: Marketplace
    description: Search and buy cards, and manage your own listings.
  - name: Metadata
    description: Look cards up by id or cert, with price history and recent activity.
  - name: Shipping
    description: Estimate, create and track shipments of cards you hold.
  - name: Account
    description: Your key, balance, limits, vault and order history, across every rail.
  - name: Funding
    description: Deposit and withdraw your balance in USDC.
  - name: Testing
    description: Test logins for trying CatchBack without real money.
  - name: Webhooks
    description: Signed POSTs we send to your URL when something happens on your account.
paths:
  /api/partner/v1/catalog/packs/pool:
    get:
      tags:
        - Gacha
      summary: Get a pack's pool
      description: >-
        **Scope:** `read:catalog`


        What a pack can pull right now: its value bands with odds at a risk
        level, the chase card if one is set, and every hittable card. A band at
        0% odds is still listed, but its cards are not.


        `kind` says what the pack pays out. A `slab` pack pays graded cards,
        listed in `cards`. A `sealed` pack (the Starter and the sealed mystery
        packs) pays sealed products: every in-stock product is its own band,
        `products` lists them, and `cards` is empty.


        The pool is
        [point-in-time](/partner-api/errors-and-limits#inventory-is-point-in-time):
        any opening on CatchBack can take a card from it. A sold-out pack still
        answers `200` with `available: false`.
      operationId: getPackPool
      parameters:
        - name: pack_type
          in: query
          required: true
          description: A `pack_type` from List packs. A pack this key can't buy is a `404`.
          schema:
            type: string
            maxLength: 100
          example: bronze
        - $ref: '#/components/parameters/PackCategory'
        - name: risk_level
          in: query
          description: >-
            Odds change with the risk level, and so can which cards are
            hittable. `aggressive` is shown as Hot in the app. Use one of the
            pack's `risk_levels`; any other is a `400`.
          schema:
            $ref: '#/components/schemas/RiskLevel'
      responses:
        '200':
          description: The pool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackPool'
              example:
                pack_type: bronze
                name: Bronze Pack
                category: pokemon
                risk_level: standard
                price: 25
                available: true
                kind: slab
                expected_value: 24.1
                bands:
                  - bucket_id: P1
                    label: $5-$20
                    min_value: 5
                    max_value: 20
                    odds: 0.72
                    is_consolation: false
                    hittable_cards: 412
                  - bucket_id: P2
                    label: $20-$50
                    min_value: 20
                    max_value: 50
                    odds: 0.2
                    is_consolation: false
                    hittable_cards: 188
                chase: null
                total_cards: 1043
                cards:
                  - id: 0e94dc61-…
                    category: pokemon
                    name: Charizard ex
                    set: Pokemon Sv3 En-Obsidian Flames
                    language: english
                    slab_label: 2023 Obsidian Flames Charizard ex
                    grading_company: PSA
                    grading_rank: 10
                    cert_number: '84512377'
                    market_value: 410
                    front_image: https://…/0e94dc61-….png
                    back_image: https://…/0e94dc61-…-back.png
                    render_image: https://…/0e94dc61-…-render.png
                    image_url: https://…/0e94dc61-…-render.png
                    bucket_id: P5
        '400':
          description: >-
            A missing `pack_type`, an unknown `category`, or a risk level the
            pack doesn't open at.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: pack_type is required
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The key lacks `read:catalog`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`pack_type` is not one this key can buy in that category.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth:
            - read:catalog
components:
  parameters:
    PackCategory:
      name: category
      in: query
      description: The catalog.
      schema:
        $ref: '#/components/schemas/PackCategory'
  schemas:
    RiskLevel:
      type: string
      enum:
        - chill
        - standard
        - aggressive
      default: standard
    PackPool:
      type: object
      required:
        - pack_type
        - name
        - category
        - risk_level
        - price
        - available
        - kind
        - expected_value
        - bands
        - chase
        - total_cards
        - cards
      properties:
        pack_type:
          type: string
        name:
          type: string
        category:
          type: string
        risk_level:
          type: string
        price:
          type: number
          description: Price per pack in USD.
        available:
          type: boolean
        reason:
          type: string
          description: >-
            Why the pack is unavailable. Only when a sold-out slab pack's pool
            is empty.
        kind:
          type: string
          enum:
            - slab
            - sealed
        expected_value:
          type:
            - number
            - 'null'
          description: Expected value of one pack in USD at this risk level.
        bands:
          type: array
          items:
            type: object
            required:
              - bucket_id
              - label
              - min_value
              - max_value
              - odds
              - is_consolation
              - hittable_cards
            properties:
              bucket_id:
                type: string
                description: Band id. Each card's `bucket_id` points here.
              label:
                type:
                  - string
                  - 'null'
                description: >-
                  Display range, e.g. `$5-$20`. For a sealed pack, the product's
                  name.
              min_value:
                type: number
              max_value:
                type: number
              odds:
                type: number
                description: Probability of landing in this band, 0–1.
              is_consolation:
                type: boolean
              hittable_cards:
                type: integer
                description: How many cards in `cards` belong to this band.
        chase:
          type:
            - object
            - 'null'
          description: >-
            A hand-picked card hittable at fixed odds on top of the bands, or
            `null`.
          properties:
            card:
              anyOf:
                - $ref: '#/components/schemas/Card'
                - type: 'null'
            probability:
              type: number
            odds_label:
              type: string
              description: e.g. `1 in 5,000`.
            label:
              type: string
            ends_at:
              type:
                - string
                - 'null'
        total_cards:
          type: integer
        cards:
          type: array
          description: Every hittable card, highest value first. Empty for a sealed pack.
          items:
            allOf:
              - $ref: '#/components/schemas/Card'
              - type: object
                required:
                  - bucket_id
                properties:
                  bucket_id:
                    type: string
        total_products:
          type: integer
          description: Sealed packs only.
        products:
          type: array
          description: Sealed packs only. Every in-stock product, highest value first.
          items:
            type: object
            required:
              - id
              - bucket_id
              - market_value
              - in_stock
              - odds
            properties:
              id:
                type: string
              bucket_id:
                type: string
              name:
                type:
                  - string
                  - 'null'
              set:
                type:
                  - string
                  - 'null'
              product_type:
                type:
                  - string
                  - 'null'
                description: e.g. `loose_pack`, `booster_bundle`.
              language:
                type:
                  - string
                  - 'null'
              year:
                type:
                  - number
                  - 'null'
              image:
                type:
                  - string
                  - 'null'
              market_value:
                type: number
                description: USD.
              in_stock:
                type: integer
              odds:
                type: number
                description: Probability of pulling this product, 0–1.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: >-
            For people. The text can change, so branch on the status and the
            `code`.
        code:
          type: string
          description: Machine-readable, where you might branch on it.
    PackCategory:
      type: string
      description: A catalog that has packs and listings.
      enum:
        - pokemon
        - onepiece
        - sports
        - riftbound
        - watches
      default: pokemon
    Card:
      type: object
      description: >-
        The [card object](/partner-api/card-object). Other fields appear only on
        the catalogs that have them.
      required:
        - id
        - category
        - name
        - set
        - grading_company
        - grading_rank
        - slab_label
        - language
        - market_value
        - cert_number
        - front_image
        - back_image
        - render_image
        - image_url
      properties:
        id:
          type: string
          description: The card's id.
        category:
          $ref: '#/components/schemas/CardCategory'
        name:
          type:
            - string
            - 'null'
        set:
          type:
            - string
            - 'null'
        year:
          type:
            - string
            - 'null'
        number:
          type:
            - string
            - 'null'
        variant:
          type:
            - string
            - 'null'
        rarity:
          type:
            - string
            - 'null'
          description: Printed rarity.
        card_type:
          type:
            - string
            - 'null'
        language:
          type:
            - string
            - 'null'
        slab_label:
          type:
            - string
            - 'null'
          description: The text on the grading label.
        grading_company:
          type:
            - string
            - 'null'
        grading_rank:
          type:
            - number
            - 'null'
          description: The grade.
        cert_number:
          type:
            - string
            - 'null'
          description: The grading company's certificate number.
        card_condition:
          type:
            - string
            - 'null'
        market_value:
          type: number
          description: Our current market valuation in USD. `0` when we have no valuation.
        price:
          type:
            - number
            - 'null'
          description: The shop sale price in USD.
        market_value_last_updated:
          type:
            - string
            - 'null'
        front_image:
          type:
            - string
            - 'null'
        back_image:
          type:
            - string
            - 'null'
        render_image:
          type:
            - string
            - 'null'
        image_url:
          type:
            - string
            - 'null'
          description: '`render_image`, or `front_image` when there is no render.'
        sport:
          type:
            - string
            - 'null'
        player_name:
          type:
            - string
            - 'null'
        team:
          type:
            - string
            - 'null'
        manufacturer:
          type:
            - string
            - 'null'
        parallel:
          type:
            - string
            - 'null'
        is_rookie:
          type:
            - boolean
            - 'null'
        is_autograph:
          type:
            - boolean
            - 'null'
        is_memorabilia:
          type:
            - boolean
            - 'null'
        serial_numbered:
          type:
            - string
            - 'null'
        brand:
          type:
            - string
            - 'null'
        reference_number:
          type:
            - string
            - 'null'
        video_url:
          type:
            - string
            - 'null'
        condition:
          type:
            - string
            - 'null'
        size:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        attributes:
          type:
            - object
            - 'null'
          description: Luxury goods only. Key-value details that vary by item.
          additionalProperties: true
    CardCategory:
      type: string
      description: A card's catalog. `goods` is luxury goods and `singles` is raw singles.
      enum:
        - pokemon
        - onepiece
        - sports
        - riftbound
        - watches
        - goods
        - singles
  responses:
    Unauthorized:
      description: A missing, malformed, disabled or unknown API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Missing or malformed API key
    ServerError:
      description: An error on our side. Retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cb_live_<48 hex>
      description: >-
        Your API key, sent as a bearer token. Keep it on your server. See
        [Authentication](/partner-api/authentication). A request from a location
        we refuse gets a `403` with `Access denied`, whether or not it has a
        valid key: [where you can call
        from](/partner-api/errors-and-limits#where-you-can-call-from).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.