### Example set response structure

Source: https://thecardapi.com/docs

A sample JSON response showing the fields returned when querying for sets.

```json
{
  "data": [{
    "usid":        "US-...",
    "set_name":    "Disney Lorcana ...",
    "category":    "trading_card_games",
    "subcategory": "lorcana",
    "sport":       "Gaming"
  }],
  "pagination": { "total": 22, "page": 1, "limit": 100, "pages": 1 }
}
```

--------------------------------

### GET /sales/export/csv

Source: https://thecardapi.com/docs

Download filtered sales as CSV. Same filter params as GET /sales, but no cursor or page. Available on Starter and above.

```APIDOC
## GET /sales/export/csv

### Description
Download a filtered result set as a CSV file. Same filter params as `GET /sales` — no `cursor` or `page`. Available on Starter and above.

### Method
GET

### Endpoint
/sales/export/csv

### Parameters
#### Query Parameters
Same filter parameters as GET /sales, excluding cursor and page.

### Request Example
```
curl "https://thecardapi.com/api/v1/market/sales/export/csv?q=psa+10+ohtani&date_from=2026-06-01" \
  -H "x-market-api-key: tca_your_key_here" \
  -o sales.csv
```
```

--------------------------------

### GET /platforms

Source: https://thecardapi.com/docs

Platform list with last updated date.

```APIDOC
## GET /platforms

### Description
Platform list with last updated date.

### Method
GET

### Endpoint
/platforms
```

--------------------------------

### Cursor Pagination Example

Source: https://thecardapi.com/docs

Demonstrates how to use the next_cursor field from the pagination object to fetch subsequent pages of results without offset drift.

```http
# Page 1 — no cursor needed
GET /v1/market/sales?q=psa+10+trout&limit=1000
→ pagination.next_cursor: "eyJwZ19pZCI6IDE4N..."

# Page 2 — pass the cursor
GET /v1/market/sales?q=psa+10+trout&limit=1000&cursor=eyJwZ19pZCI6IDE4N...
→ pagination.next_cursor: "eyJwZ19pZCI6IDE2N..."  # or null if last page
```

--------------------------------

### GET /coverage

Source: https://thecardapi.com/docs

Latest data freshness status.

```APIDOC
## GET /coverage

### Description
Latest data freshness status.

### Method
GET

### Endpoint
/coverage
```

--------------------------------

### JSON response for one-record existence check

Source: https://thecardapi.com/docs

Example JSON response from the GET /catalog endpoint for the one-record existence check. Shows the card data fields including ucid, slug, set_usid, set_name, card_number, subject, is_rookie, is_auto, and print_run, along with pagination info.

```json
{
  "data": [{
    "ucid":            "UC-1KJZD-TZG7C-6",
    "slug":            "2023-topps/27",
    "set_usid":        "US-J28FC-5H09C-4",
    "set_name":        "2023 Topps",
    "parent_set_name": null,
    "card_number":     "27",
    "subject":         "Mike Trout",
    "is_rookie":       false,
    "is_auto":         false,
    "print_run":       null
  }],
  "pagination": { "total": 1, "page": 1, "limit": 100, "pages": 1 }
}
```

--------------------------------

### cURL REST and MCP Requests

Source: https://thecardapi.com/docs

Examples of using cURL to perform a REST search and an MCP tool call.

```shell
# REST — search for PSA 10 cards
curl "https://thecardapi.com/api/v1/market/sales?q=psa+10&limit=25" \
  -H "x-market-api-key: tca_your_key_here"

# MCP — call price_momentum tool
curl https://www.thecardapi.com/api/mcp \
  -H "Authorization: Bearer tca_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"price_momentum","arguments":{"query":"Wembanyama Prizm Silver"}}}'
```

--------------------------------

### Card API Response JSON Example

Source: https://thecardapi.com/docs

Example JSON response from the Card API showing a single card record with fields like id, platform, price, grade, and player. Includes pagination and meta objects with total count, page, limit, and coverage dates.

```json
{
  "data": [
    {
      "id":                    "137222685761",
      "platform":              "eBay",
      "listing_type":          "auction",
      "title":                 "2021 Bowman Chrome Kyle Harrison Auto PSA 10",
      "sale_date":             "2026-06-14",
      "sold_at":               "2026-06-14T00:00:00Z",
      "price":                 47.50,
      "original_price":        null,
      "currency":              "USD",
      "price_confirmed":       true,
      "bids":                  12,
      "image_url":             "https://i.ebayimg.com/...",
      "thumbnail_url":         "https://i.ebayimg.com/...",
      "listing_url":           "https://www.ebay.com/itm/137222685761",
      "cert":                  "93265128",
      "condition":             null,
      "grade":                 "10",
      "grader":                "PSA",
      "grading_company":       "Professional Sports Authenticator",
      "has_autograph_grade":   false,
      "has_grade_qualifier":   false,
      "label":                 null,
      "grade_qualifier":       null,
      "autograph_grade":       null,
      "player":                "Kyle Harrison",
      "manufacturer":          "Bowman",
      "card_set":              "2021 Bowman Chrome",
      "card_number":           "BCP-42",
      "year":                  2021,
      "season":                "2021",
      "league":                "Major League (MLB)",
      "sport":                 "Baseball",
      "team":                  "San Francisco Giants",
      "features":              ["Auto", "Rookie"],
      "print_run":             null,
      "shipping_price":        4.99,
      "category":              "sports"
    }
  ],
  "pagination": {
    "total":       258817,
    "page":        1,
    "limit":       25,
    "pages":       10353,
    "has_more":    true,
    "next_cursor": "eyJwZ19pZCI6IDE4NzUwMDAwLCAic29ydCI6ICJkYXRlX2Rlc2MifQ=="
  },
  "meta": {
    "coverage_date_from":  "2026-06-01",
    "coverage_date_to":    "2026-06-17",
    "platforms_covered":   ["eBay", "Goldin", "Lelands", "SCP Auctions", "Hakes", "REA", "TCGplayer"],
    "generated_at":        "2026-06-17T10:00:00Z"
  }
}
```

--------------------------------

### GET /webhook

Source: https://thecardapi.com/docs

List active webhook endpoints.

```APIDOC
## GET /webhook

### Description
List active webhook endpoints.

### Method
GET

### Endpoint
/webhook
```

--------------------------------

### grading_value_calculator tool call

Source: https://thecardapi.com/docs

Example JSON-RPC call to the grading_value_calculator tool to evaluate the profitability of grading a specific card.

```json
{
  "jsonrpc": "2.0", "id": "1",
  "method": "tools/call",
  "params": {
    "name": "grading_value_calculator",
    "arguments": {
      "query":              "1986 Fleer Jordan 57",
      "raw_purchase_price": 6500,
      "target_grade":       "10",
      "grader":             "psa",
      "submission_tier":    "standard"
    }
  }
}
```

--------------------------------

### GET /daily

Source: https://thecardapi.com/docs

Aggregate stats for a date.

```APIDOC
## GET /daily

### Description
Aggregate stats for a date.

### Method
GET

### Endpoint
/daily
```

--------------------------------

### GET /catalog/sets

Source: https://thecardapi.com/docs

Browse and search sets by category, subcategory, name, year, and more. Supports pagination and filtering by product family.

```APIDOC
## GET /catalog/sets

### Description
Browse and search sets by category, subcategory, name, year, and more. Supports pagination and filtering by product family.

### Method
GET

### Endpoint
https://www.thecardapi.com/api/v1/catalog/sets

### Parameters
#### Query Parameters
- **category** (string) - Optional - Top-level category ID from /catalog/categories.
- **subcategory** (string) - Optional - Subcategory ID from /catalog/categories. A subcategory also implies its parent category.
- **sport** (string) - Optional - Legacy source-category filter, case-insensitive.
- **q** (string) - Optional - Case-insensitive set-name search (min 2 chars).
- **year** (integer) - Optional - Filter by set year.
- **family_of** (USID or UFID) - Optional - Return every set in a product family from either a member USID or the family UFID.
- **main_only** (boolean) - Optional - true returns top-level sets only, excluding inserts, parallels, autos, and other sub-sets.
- **page** (integer) - Optional - Pagination page number.
- **limit** (integer) - Optional - Pagination limit. Default 25; maximum 100.

### Request Example
curl -H "x-api-key: $KEY" \
  "https://www.thecardapi.com/api/v1/catalog/sets?subcategory=lorcana&limit=100"

### Response
#### Success Response (200)
- **data** (array) - List of sets with fields: usid, set_name, category, subcategory, sport.
- **pagination** (object) - Pagination info: total, page, limit, pages.

#### Response Example
{
  "data": [{
    "usid":        "US-...",
    "set_name":    "Disney Lorcana ...",
    "category":    "trading_card_games",
    "subcategory": "lorcana",
    "sport":       "Gaming"
  }],
  "pagination": { "total": 22, "page": 1, "limit": 100, "pages": 1 }
}
```

--------------------------------

### GET /api/v1/market/webhook

Source: https://thecardapi.com/docs

Lists all active webhook endpoints for the API key. Returns an array of endpoints with their details.

```APIDOC
## GET /api/v1/market/webhook

### Description
Lists all active webhook endpoints for the API key. Returns an array of endpoints with their details.

### Method
GET

### Endpoint
/api/v1/market/webhook

### Headers
- **x-market-api-key** (string) - Required - Your API key

### Response
#### Success Response (200)
- **endpoints** (array) - List of endpoints
  - **id** (integer) - Endpoint ID
  - **url** (string) - The registered URL
  - **label** (string) - The label
  - **created_at** (string) - Creation timestamp
- **count** (integer) - Number of endpoints
- **max** (integer) - Maximum allowed endpoints

#### Response Example
{
  "endpoints": [
    { "id": 1, "url": "https://your-server.com/webhook", "label": "prod-receiver", "created_at": "2026-06-20T10:00:00Z" },
    { "id": 2, "url": "https://your-server.com/backup",  "label": "backup",         "created_at": "2026-06-20T10:01:00Z" }
  ],
  "count": 2,
  "max":   5
}

### Error Handling
- 401: Invalid or missing API key
- 403: Action requires a higher plan or beta access
- 429: Daily sales limit reached
- 500: Server error
```

--------------------------------

### price_momentum tool call

Source: https://thecardapi.com/docs

Example JSON-RPC call to the price_momentum tool to analyze card trends over a 14-day window.

```json
{
  "jsonrpc": "2.0", "id": "1",
  "method": "tools/call",
  "params": {
    "name": "price_momentum",
    "arguments": {
      "query":         "Wembanyama Prizm Silver",
      "lookback_days": 14
    }
  }
}
```

--------------------------------

### Call grader_comparison MCP tool

Source: https://thecardapi.com/docs

Example of calling the grader_comparison tool to compare market premiums across graders, followed by the abbreviated JSON response.

```json
{
  "jsonrpc": "2.0", "id": "1",
  "method": "tools/call",
  "params": {
    "name": "grader_comparison",
    "arguments": {
      "query": "Wembanyama 2023 Prizm Silver",
      "grade": "9"
    }
  }
}
```

```json
{
  "query":        "Wembanyama 2023 Prizm Silver",
  "grade":        "9",
  "lookback_days": 90,
  "by_grader": [
    { "grader": "PSA", "sales": 18, "avg_price": 1450, "median_price": 1380 },
    { "grader": "BGS", "sales": 7,  "avg_price": 1210, "median_price": 1175 },
    { "grader": "CGC", "sales": 4,  "avg_price": 980,  "median_price": 950  },
    { "grader": "SGC", "sales": 2,  "avg_price": 890,  "median_price": 890  }
  ],
  "takeaway": "PSA commands the highest avg price at $1450",
  "comparisons": [
    { "grader": "BGS", "pct_cheaper_than_top": 17 },
    { "grader": "CGC", "pct_cheaper_than_top": 32 },
    { "grader": "SGC", "pct_cheaper_than_top": 39 }
  ]
}
```

--------------------------------

### List webhook endpoints (GET /api/v1/market/webhook)

Source: https://thecardapi.com/docs

Returns all registered endpoints for the API key. The response includes endpoint IDs, URLs, labels, creation timestamps, and the count and max limits.

```HTTP
GET /api/v1/market/webhook
x-market-api-key: tca_your_key_here
```

```JSON
{
  "endpoints": [
    { "id": 1, "url": "https://your-server.com/webhook", "label": "prod-receiver", "created_at": "2026-06-20T10:00:00Z" },
    { "id": 2, "url": "https://your-server.com/backup",  "label": "backup",         "created_at": "2026-06-20T10:01:00Z" }
  ],
  "count": 2,
  "max":   5
}
```

--------------------------------

### Call search_cards MCP tool

Source: https://thecardapi.com/docs

Example of calling the search_cards tool to find recent sales for a specific card, followed by the abbreviated JSON response.

```json
{
  "jsonrpc": "2.0", "id": "1",
  "method": "tools/call",
  "params": {
    "name": "search_cards",
    "arguments": {
      "query":        "PSA 10 Luka Doncic 2018 Prizm Silver",
      "listing_type": "BestOffer",
      "limit":        10
    }
  }
}
```

```json
{
  "total_returned": 10,
  "results": [
    {
      "id":           "ebay-137222685761",
      "title":        "2018 Panini Prizm Silver Luka Doncic PSA 10",
      "platform":     "eBay",
      "listing_type": "BestOffer",
      "price":        4800.00,
      "sale_date":    "2026-06-16",
      "sold_at":      "2026-06-16T14:23:00Z",
      "bids":         null,
      "grader":       "PSA",
      "grade":        "10",
      "slab_serial":  "84566824",
      "listing_url":  "https://www.ebay.com/itm/137222685761"
    }
  ],
  "note": "BestOffer prices reflect the true final negotiated amount, not the list price."
}
```

--------------------------------

### Call grade_impact_analysis MCP tool

Source: https://thecardapi.com/docs

Example of calling the grade_impact_analysis tool to retrieve a price ladder for a card, followed by the abbreviated JSON response.

```json
{
  "jsonrpc": "2.0", "id": "1",
  "method": "tools/call",
  "params": {
    "name": "grade_impact_analysis",
    "arguments": {
      "query":         "Luka Doncic 2018 Prizm Silver",
      "grader":        "psa",
      "lookback_days": 90
    }
  }
}
```

```json
{
  "query":        "Luka Doncic 2018 Prizm Silver",
  "grader":       "PSA",
  "lookback_days": 90,
  "total_sales":  49,
  "price_ladder": [
    { "grade": "10", "sales": 6,  "avg_price": 9200, "median_price": 8750, "min_price": 7800, "max_price": 11200 },
    { "grade": "9",  "sales": 28, "avg_price": 3400, "median_price": 3250, "min_price": 2800, "max_price": 4100 },
    { "grade": "8",  "sales": 12, "avg_price": 1950, "median_price": 1875, "min_price": 1600, "max_price": 2300 },
    { "grade": "7",  "sales": 3,  "avg_price": 850,  "median_price": 820,  "min_price": 750,  "max_price": 980  }
  ],
  "best_value_grade": {
    "grade":  "9",
    "reason": "Stepping up to 10 costs 171% more — this is the steepest value jump in the price ladder."
  }
}
```

--------------------------------

### GET /catalog/categories

Source: https://thecardapi.com/docs

Discovers the catalog's stable, developer-facing taxonomy. Returns machine IDs, display labels, descriptions, and valid subcategories for each category.

```APIDOC
## GET /catalog/categories

### Description
Discovers the catalog's stable, developer-facing taxonomy. Returns machine IDs, display labels, descriptions, and valid subcategories for each category.

### Method
GET

### Endpoint
https://www.thecardapi.com/api/v1/catalog/categories

### Parameters
#### Query Parameters
- **category** (string) - Optional - Top-level ID: sports, trading_card_games, or entertainment.
- **subcategory** (string) - Optional - Stable primary ID such as baseball, pokemon, lorcana, magic_the_gathering, marvel, or star_wars.
- **sport** (string) - Optional - Legacy source-category field retained for compatibility. New navigation should use category and subcategory.

### Request Example
curl -H "x-api-key: $KEY" \
  "https://www.thecardapi.com/api/v1/catalog/categories"

### Response
#### Success Response (200)
- **data** (array) - List of categories with fields: usid, set_name, category, subcategory, sport.
- **pagination** (object) - Pagination info: total, page, limit, pages.

#### Response Example
{
  "data": [{
    "usid":        "US-...",
    "set_name":    "Disney Lorcana ...",
    "category":    "trading_card_games",
    "subcategory": "lorcana",
    "sport":       "Gaming"
  }],
  "pagination": { "total": 22, "page": 1, "limit": 100, "pages": 1 }
}
```

--------------------------------

### GET /sales

Source: https://thecardapi.com/docs

Search and filter individual sale records. Results are ordered by date descending by default. Supports various filters including full-text search, platform, listing type, date range, price range, print run, shipping cost, category, grading, and sorting.

```APIDOC
## GET /sales

### Description
Search and filter individual sale records. Results are ordered by date descending by default. Your plan's lookback window is enforced on `date_from` automatically.

### Method
GET

### Endpoint
/sales

### Parameters
#### Query Parameters
- **q** (string) - Optional - Full-text search on listing title (min 4 chars). Supports boolean syntax: (term1,term2) for OR, -term for NOT, "exact phrase" for phrase match.
- **platform** (string) - Optional - Filter by platform. Values: ebay · tcgplayer · goldin · lelands · scp · hakes · rea. See GET /platforms for the full list.
- **listing_type** (string) - Optional - Comma-separated: auction, fixed_price, best_offer
- **date_from** (date) - Optional - Start date YYYY-MM-DD. Clamped to your plan's lookback window.
- **date_to** (date) - Optional - End date YYYY-MM-DD
- **price_min** (number) - Optional - Minimum sale price (USD)
- **price_max** (number) - Optional - Maximum sale price (USD)
- **print_run_min** (integer) - Optional - Minimum print run (e.g. 1 for 1/1 only)
- **print_run_max** (integer) - Optional - Maximum print run (e.g. 99 to filter to /99 and lower numbered cards)
- **shipping_max** (number) - Optional - Maximum buyer shipping cost in USD. Use shipping_max=0 for free-shipping listings only. Filters to records where shipping_price ≤ this value (null shipping_price records are excluded).
- **category** (string) - Optional - Filter by card category: sports, tcg, non_sport. eBay records indexed from June 6, 2026 onward. Auction house sources (Goldin, REA, etc.) return null until backfilled.
- **graded** (boolean) - Optional - graded=true returns only professionally graded cards (any grading company); graded=false returns only raw/ungraded. Works on every platform. Autograph-authentication-only slabs (PSA/DNA, JSA, BAS) count as ungraded — the card's condition was never graded.
- **grader** (string) - Optional - Filter by a specific grading company: PSA, BGS, SGC, CGC, etc. (case-insensitive)
- **grade** (string) - Optional - Filter by grade value: 10, 9.5, 9, etc. Combine with grader (e.g. grader=PSA&grade=10).
- **condition** (string) - Optional - Filter by listing condition string, e.g. Pre-Owned (ungraded) or New (Other) (graded slab). eBay records only.
- **sort** (string) - Optional - date_desc (default) | date_asc | price_desc | price_asc
- **page** (integer) - Optional - Page number (default: 1)
- **limit** (integer) - Optional - Results per request (default: 25, max: 1,000). Same cap on all plans.
- **cursor** (string) - Optional - Opaque cursor from a previous response's next_cursor field. Efficiently paginate large result sets without offset drift. When provided, page is ignored. Available on all plans.
- **indexed_after** (datetime) - Optional - ISO 8601 UTC. Return only records indexed after this time. Useful for incremental sync.

### Cursor Pagination
Every response includes a `next_cursor` field in `pagination` when more results exist. Pass it as `?cursor=` on the next request to fetch the next page — no offset drift, no missed records. Available on all plans.

### Search Syntax
- `(psa,bgs)` — title contains "psa" OR "bgs"
- `-reprint` — title does NOT contain "reprint"
- `-(lot,album)` — title contains neither "lot" nor "album"
- `"topps chrome"` — exact phrase match
- `ohtani (psa,bgs) -(lot,album) -reprint` — combine all forms
```

--------------------------------

### Configure Claude Desktop MCP

Source: https://thecardapi.com/docs

Add the server to your Claude Desktop configuration file using npx and your API key.

```JSON
{
  "mcpServers": {
    "thecardapi": {
      "command": "npx",
      "args": ["mcp-remote", "https://www.thecardapi.com/api/mcp",
               "--header", "Authorization: Bearer YOUR_API_KEY"]
    }
  }
}
```

--------------------------------

### Make a first request with cURL

Source: https://thecardapi.com/docs

Perform a search for sales data using the REST API with an API key header.

```shell
curl "https://thecardapi.com/api/v1/market/sales?q=psa+10+ohtani&limit=5" \
  -H "x-market-api-key: tca_your_key_here"
```

--------------------------------

### Configure Cursor or Windsurf MCP

Source: https://thecardapi.com/docs

Add the server configuration to your Cursor or Windsurf settings using the provided URL and headers.

```JSON
{
  "mcpServers": {
    "thecardapi": {
      "url": "https://www.thecardapi.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

--------------------------------

### Discover available MCP tools

Source: https://thecardapi.com/docs

Use this JSON-RPC 2.0 request to list all available tools exposed by the MCP server.

```JSON
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list"
}
```

--------------------------------

### GET /sales/{id}

Source: https://thecardapi.com/docs

Retrieve a single sale record by its ID.

```APIDOC
## GET /sales/{id}

### Description
Retrieve a single sale record by its ID.

### Method
GET

### Endpoint
/sales/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the sale record.
```

--------------------------------

### Python MCP Tool Execution

Source: https://thecardapi.com/docs

Shows how to call MCP tools via HTTP POST requests, including a helper function to handle JSON-RPC responses.

```python
import requests

MCP_URL = "https://www.thecardapi.com/api/mcp"
HEADERS = {"Authorization": "Bearer tca_your_key_here", "Content-Type": "application/json"}

def call_tool(name: str, arguments: dict) -> dict:
    payload = {
        "jsonrpc": "2.0", "id": "1",
        "method":  "tools/call",
        "params":  {"name": name, "arguments": arguments},
    }
    r = requests.post(MCP_URL, headers=HEADERS, json=payload)
    result = r.json()
    if result.get("error"):
        raise RuntimeError(result["error"]["message"])
    import json
    return json.loads(result["result"]["content"][0]["text"])

# Grade ladder for Mantle cards over $1,000
data = call_tool("grade_impact_analysis", {
    "query":         "Mickey Mantle",
    "grader":        "psa",
    "lookback_days": 30,
})
for row in data["price_ladder"]:
    avg = "{:,.0f}".format(row['avg_price'])
    print(f"PSA {row['grade']}: ${avg} avg ({row['sales']} sales)")
```

--------------------------------

### Python REST API Integration

Source: https://thecardapi.com/docs

Demonstrates searching for recent auctions and performing an incremental sync using the requests library.

```python
import requests

API_KEY = "tca_your_key_here"
BASE    = "https://thecardapi.com/api/v1/market"
HEADERS = {"x-market-api-key": API_KEY}

# Search recent Ohtani auctions
r = requests.get(f"{BASE}/sales", headers=HEADERS, params={
    "q":            "Shohei Ohtani",
    "listing_type": "auction",
    "price_min":    50,
    "limit":        50,
})
for sale in r.json()["data"]:
    print(sale["sale_date"], sale["price"], sale["title"][:60])

# Incremental sync — only records indexed since your last poll
r = requests.get(f"{BASE}/sales", headers=HEADERS, params={
    "indexed_after": "2026-06-15T10:00:00Z",
    "limit":         100,
})
```

--------------------------------

### GET /api/v1/market/sales

Source: https://thecardapi.com/docs

Search completed sales across supported marketplaces. This endpoint is part of the Market API and requires an x-market-api-key header.

```APIDOC
## GET /api/v1/market/sales

### Description
Search completed sales across supported marketplaces in one consistent schema.

### Method
GET

### Endpoint
/api/v1/market/sales

### Parameters
#### Query Parameters
- **q** (string) - Optional - Search query, e.g., 'psa 10 ohtani'
- **limit** (integer) - Optional - Maximum number of results to return

### Request Example
curl "https://thecardapi.com/api/v1/market/sales?q=psa+10+ohtani&limit=5" \
  -H "x-market-api-key: tca_your_key_here"

### Response
#### Success Response (200)
Returns a list of sales matching the query.

#### Response Example
(No response example provided in source.)
```

--------------------------------

### POST /webhook

Source: https://thecardapi.com/docs

Add a webhook endpoint (max 5) — available on all paid plans.

```APIDOC
## POST /webhook

### Description
Add a webhook endpoint (max 5) — available on all paid plans.

### Method
POST

### Endpoint
/webhook
```

--------------------------------

### GET /catalog

Source: https://thecardapi.com/docs

Search for cards using various filters. Supports filtering by set, player, card number, set name, full-text search, sport, year, and card attributes. Returns a paginated list of card records.

```APIDOC
## GET /catalog

### Description
Search for cards using various filters. Supports filtering by set, player, card number, set name, full-text search, sport, year, and card attributes. Returns a paginated list of card records.

### Method
GET

### Endpoint
https://www.thecardapi.com/api/v1/catalog

### Parameters
#### Query Parameters
- **set_id** (string) - Optional - Filter by set — fastest path. Accepts the set's USID.
- **player_id** (string) - Optional - Every card of a player — find the UPID via /catalog/players.
- **card_number** (string) - Optional - Exact card number, case-insensitive (leading # ignored). Combine with set_id for a one-record existence check.
- **set_name** (string) - Optional - Case-insensitive substring match on set name (min 2 chars).
- **q** (string) - Optional - Full-text search across card subject and set name (min 2 chars).
- **sport** (string) - Optional - Baseball, Basketball, Football, Hockey, Soccer, Gaming (TCG), Racing, and more.
- **year** (integer) - Optional - Set year.
- **is_rookie** (boolean) - Optional - Card attribute filter.
- **is_auto** (boolean) - Optional - Card attribute filter.
- **page** (integer) - Optional - Pagination. Default 1.
- **limit** (integer) - Optional - Pagination. Max limit: 100 (Builder), 1,000 (Pro/Enterprise).

### Request Example
```bash
curl -H "x-api-key: $KEY" \
  "https://www.thecardapi.com/api/v1/catalog?set_id=US-J28FC-5H09C-4&card_number=27"
```

### Response
#### Success Response (200)
- **data** (array) - List of card records.
  - **ucid** (string) - Unique card identifier.
  - **slug** (string) - Card slug.
  - **set_usid** (string) - Set USID.
  - **set_name** (string) - Set name.
  - **parent_set_name** (string|null) - Parent set name for parallels/inserts, null otherwise.
  - **card_number** (string) - Card number.
  - **subject** (string) - Card subject (player name).
  - **is_rookie** (boolean) - Whether the card is a rookie card.
  - **is_auto** (boolean) - Whether the card is an autograph.
  - **print_run** (integer|null) - Print run for serial-numbered parallels, null otherwise.
- **pagination** (object) - Pagination info.
  - **total** (integer) - Total number of records.
  - **page** (integer) - Current page.
  - **limit** (integer) - Records per page.
  - **pages** (integer) - Total pages.

#### Response Example
```json
{
  "data": [{
    "ucid":            "UC-1KJZD-TZG7C-6",
    "slug":            "2023-topps/27",
    "set_usid":        "US-J28FC-5H09C-4",
    "set_name":        "2023 Topps",
    "parent_set_name": null,
    "card_number":     "27",
    "subject":         "Mike Trout",
    "is_rookie":       false,
    "is_auto":         false,
    "print_run":       null
  }],
  "pagination": { "total": 1, "page": 1, "limit": 100, "pages": 1 }
}
```

### Error Handling
- **400** - Unrecognized parameters return a 400 listing the supported ones.

### Rate Limits
Catalog usage has its own daily pool. Each record returned counts as 1 (minimum 1 per request); counters reset at 00:00 UTC. Every /catalog response carries X-RateLimit-Limit and X-RateLimit-Remaining headers for this pool.
- Builder + Catalog add-on: 500 records/day
- Pro (included): 2,000 records/day
- Enterprise: Custom — defined in Order Form
```

--------------------------------

### Add MCP server to Claude Code

Source: https://thecardapi.com/docs

Use the Claude CLI to register the MCP server with the specified URL and authorization header.

```Shell
claude mcp add thecardapi \
  --transport http \
  --url https://www.thecardapi.com/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Add a webhook endpoint (POST /api/v1/market/webhook)

Source: https://thecardapi.com/docs

Registers a new HTTPS endpoint to receive card sale batches. Requires the x-market-api-key header and a JSON body with url, secret, and optional label. Max 5 active endpoints per key.

```HTTP
POST /api/v1/market/webhook
x-market-api-key: tca_your_key_here
Content-Type: application/json

{
  "url":    "https://your-server.com/webhook",
  "secret": "your-hmac-signing-secret",
  "label":  "prod-receiver"
}
```

--------------------------------

### LangChain Python MCP Integration

Source: https://thecardapi.com/docs

Integrates TheCardAPI MCP server into a LangGraph agent using the MultiServerMCPClient.

```python
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langchain_anthropic import ChatAnthropic

async def main():
    async with MultiServerMCPClient({
        "thecardapi": {
            "url":       "https://www.thecardapi.com/api/mcp",
            "transport": "streamable_http",
            "headers":   {"Authorization": "Bearer tca_your_key_here"},
        }
    }) as client:
        tools  = await client.get_tools()
        model  = ChatAnthropic(model="claude-sonnet-4-6")
        agent  = create_react_agent(model, tools)
        result = await agent.ainvoke({
            "messages": "Is grading my 1986 Fleer Jordan worth it at $6,500?"
        })
        print(result["messages"][-1].content)

asyncio.run(main())
```

--------------------------------

### POST /api/v1/market/webhook

Source: https://thecardapi.com/docs

Registers a new webhook endpoint to receive sale batches. Requires an API key and a valid HTTPS URL. Max 5 active endpoints per key.

```APIDOC
## POST /api/v1/market/webhook

### Description
Registers a new webhook endpoint to receive sale batches. Requires an API key and a valid HTTPS URL. Max 5 active endpoints per key.

### Method
POST

### Endpoint
/api/v1/market/webhook

### Headers
- **x-market-api-key** (string) - Required - Your API key
- **Content-Type** (string) - Required - application/json

### Request Body
- **url** (string) - Required - The HTTPS endpoint URL to receive webhook deliveries
- **secret** (string) - Required - HMAC signing secret for signature verification
- **label** (string) - Optional - A label for the endpoint

### Request Example
{
  "url": "https://your-server.com/webhook",
  "secret": "your-hmac-signing-secret",
  "label": "prod-receiver"
}

### Response
#### Success Response (200)
- **id** (integer) - Endpoint ID
- **url** (string) - The registered URL
- **label** (string) - The label
- **created_at** (string) - Creation timestamp

#### Response Example
{
  "id": 1,
  "url": "https://your-server.com/webhook",
  "label": "prod-receiver",
  "created_at": "2026-06-20T10:00:00Z"
}

### Error Handling
- 401: Invalid or missing API key
- 403: Action requires a higher plan or beta access
- 422: Validation error — check parameter types and ranges
- 429: Daily sales limit reached
- 500: Server error
```

--------------------------------

### Discover categories and browse sets via cURL

Source: https://thecardapi.com/docs

Use these commands to retrieve the valid category taxonomy and to browse sets filtered by subcategory.

```bash
# Discover every valid category and subcategory
curl -H "x-api-key: $KEY" \
  "https://www.thecardapi.com/api/v1/catalog/categories"

# Browse Lorcana sets
curl -H "x-api-key: $KEY" \
  "https://www.thecardapi.com/api/v1/catalog/sets?subcategory=lorcana&limit=100"
```

--------------------------------

### grading_value_calculator response

Source: https://thecardapi.com/docs

Abbreviated response from the grading_value_calculator tool containing cost estimates, grade scenarios, and profit analysis.

```json
{
  "query":              "1986 Fleer Jordan 57",
  "raw_purchase_price": 6500,
  "grader":             "PSA",
  "target_grade":       "10",
  "grading_costs": {
    "service_tier":       "standard",
    "per_card_fee":       "$79.99",
    "turnaround":         "25 days",
    "shipping_roundtrip": "$40–$60 (continental US)",
    "total_estimate":     "$119.99–$139.99",
    "total_mid_estimate": 130
  },
  "grade_scenarios": [
    { "grade": "10",  "sales": 8,  "avg_price": 42000, "expected_profit": 35370, "is_target": true },
    { "grade": "9",   "sales": 22, "avg_price": 9800,  "expected_profit": 3170,  "is_target": false },
    { "grade": "8",   "sales": 11, "avg_price": 4200,  "expected_profit": -2330, "is_target": false }
  ],
  "math": {
    "if_card_grades_at_target": "$42000 (avg sale price)",
    "minus_raw_cost":           "-$6500",
    "minus_grading_and_ship":   "-$130 (midpoint estimate)",
    "expected_profit":          "$+35370",
    "break_even_grade":         "8"
  },
  "caveats": [
    "Grading outcome is NOT guaranteed — these numbers assume the card achieves each grade.",
    "Only 8 comps found at 10 — price estimate may be unreliable."
  ]
}
```

--------------------------------

### Authentication headers for REST and MCP

Source: https://thecardapi.com/docs

Shows the required headers for authenticating requests to the REST API and the MCP Server.

```http
# REST API
GET /api/v1/market/sales
x-market-api-key: tca_your_key_here

# MCP Server
POST /api/mcp
Authorization: Bearer tca_your_key_here
```