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

# Search Players

`POST /v1/cards/player-search`

## Request

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

Search Card Hedge's canonical player catalog by partial name.

Duplicate player records (e.g. two "LeBron James" records) are folded into
one canonical player: `player_id` is the canonical ID and `aliases` lists
the merged IDs, whose stats are summed. `categories` lists every category
the player appears in; the optional `category` filter matches any of them.
`index` says whether a player index is available (`current`, `stale`,
`withheld`, or `none`).

Results are ranked by 30-day sales and capped by `count`.

**Example curl:**
```bash
curl -X POST -H "X-API-Key: your-api-key-here"          -H "Content-Type: application/json"          -d '{"search":"Luka","count":5}'          "https://api.cardhedger.com/v1/cards/player-search"
```

## Request body

- PlayerSearchRequest: Request parameters for the canonical player search endpoint.
  - `search` string, required: Player or character name to search for (2-100 characters)
  - `count` integer: Maximum number of players to return (1-100)
  - `category` string, nullable: Only return players in this category (name or slug, e.g. 'Baseball' or 'yu-gi-oh'). A multi-category player matches any of its categories.

## Response `200`

Successful Response

- PlayerSearchResponse: Response model for canonical player search.
  - `count` integer, required: Number of players returned
  - `players` PlayerSearchPlayer[]: Canonical players matching the search
    - `player_id` string, required: Canonical Card Hedge player ID. Duplicate player records are folded into one player; their IDs are listed in `aliases`.
    - `name` string, required: Canonical player or character name
    - `categories` string[]: Categories the player appears in, e.g. ['Basketball', 'Baseball']
    - `aliases` string[]: Other player IDs merged into this player; requests for them resolve here
    - `cards_tracked` integer, nullable: Cards tracked for the player, summed across merged records
    - `thirty_day_sales` integer, nullable: Sales in the last 30 days, summed across merged records
    - `index` PlayerIndexAvailability: Whether Card Hedge has a servable player index for this player.
      - `has_index` boolean, required: True when a cached player index exists
      - `as_of` string, date, nullable: Date of the latest index value
      - `status` 'current' | 'stale' | 'withheld' | 'none', required: `current` (updated within 2 days), `stale` (older, still served), `withheld` (mostly built from other players' cards, so not served), or `none` (no index).

## Other responses

- `422`: Unknown category (the response lists valid ones)

## Changes

- **2026-09-29** `637bcd3b9a98`: 3 breaking, 4 info
  - removed the media type `application/json` for the response with the status `422`
  - response property `players/items/cards_tracked` list-of-types was widened by adding types `null` to media type `application/json` of response `200`
  - response property `players/items/thirty_day_sales` list-of-types was widened by adding types `null` to media type `application/json` of response `200`
  - added the new optional request property `category`
  - …3 more
- **2026-09-05** `f2d0e595be79`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cardhedger/apis/card-hedge-api/changes/v1/cards/player-search/post.md)

---

[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)