---
title: "Search Cards"
method: POST
path: "/v1/cards/card-search"
tags: ["Card Search"]
---

# Search Cards

`POST /v1/cards/card-search`

## Request

- Base URL: `https://api.cardhedger.com`
- URL: `https://api.cardhedger.com/v1/cards/card-search`
- Auth: API key in header `X-API-Key`

Search for cards with flexible filtering options.

Searches CardHedge database with optional filters for search query, set, category,
player, card number, subset, and rookie status. Supports pagination to iterate
through large result sets.

**Response includes:**
- `pages`: Total number of pages available
- `count`: Total number of matching cards
- `cards`: Array of card objects for the current page

**Example curl:**
```bash
curl -X POST -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{
       "search": "Shohei Ohtani",
       "category": "Baseball",
       "page": 1,
       "page_size": 20
     }' \
     "https://api.cardhedger.com/v1/cards/card-search"
```

Returns matching cards with pricing, sales data, and pagination metadata.

## Request body

- CardSearchRequest: Request parameters for card search endpoint.
  - `search` string, nullable: Search query for card name/description
  - `set` string, nullable: Filter by set name (e.g., '2025 Topps Baseball')
  - `category` string, nullable: Filter by category (e.g., 'Baseball', 'Basketball')
  - `player` string, nullable: Filter by player name
  - `number` string, nullable: Filter by card number within the set (exact match, e.g. '150')
  - `subset` string, nullable: Filter by subset within the set (exact match, e.g. 'Base Set', 'Chrome')
  - `rookie` string, nullable: Filter by rookie status (e.g., 'Rookie')
  - `page` integer: Page number for pagination
  - `page_size` integer: Number of results per page (1-100)
  - `raw_images_only` boolean, nullable: Image preference. Omitted (default): return the raw card photo, falling back to the graded slab image only when no raw photo exists. true: force raw-only (no graded fallback). false: prefer the graded slab image.

## Response `200`

Successful Response

- CardSearchResponse: Response model for card search endpoint.
  - `pages` integer: Total number of pages available
  - `count` integer: Total number of matching cards
  - `count_capped` boolean: True when `count` is a capped value and the real total is higher (filter-only browses cap the count for performance). Render as `count`+ — e.g. "10,000+".
  - `cards` CardSearchCard[], required: List of matching cards
    - `description` string, required: Full card description
    - `player` string, required: Player or character name
    - `set` string, required: Card set name
    - `number` string, required: Card number in set
    - `variant` string, required: Card variant (e.g., 'Base', 'Reverse Foil')
    - `card_id` string, required: Unique card identifier
    - `image` string, required: Card image URL
    - `category` string, required: Card category
    - `category_group` string, required: Category group
    - `set_type` string, required: Set type
    - `7 Day Sales` integer, required: Sales in last 7 days
    - `30 Day Sales` integer, required: Sales in last 30 days
    - `rookie` boolean, required: Whether the card is a rookie card
    - `gain` number, required: Price gain percentage
    - `prices` CardPrice[], required: Price information at different grades
      - `grade` string, required: Card grade (e.g., 'Raw', 'PSA 10')
      - `price` string, required: Price in string format
    - `subset` string, nullable: Card subset within the set (e.g. 'Base Set', 'Chrome'); null when the card has no subset

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/cardhedger/apis/card-hedge-api.md) - [All operations](https://skmtc.dev/cardhedger/apis/card-hedge-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardhedger/apis/card-hedge-api/revisions/6de42f192a4d?raw)